SC-HSM-TOOL(1) | OpenSC Tools | SC-HSM-TOOL(1) |
NAME¶
sc-hsm-tool - smart card utility for SmartCard-HSM
SYNOPSIS¶
sc-hsm-tool [OPTIONS]
¶
The sc-hsm-tool utility can be used from the command line to perform extended maintenance tasks not available via PKCS#11 or other tools in the OpenSC package. It can be used to query the status of a SmartCard-HSM, initialize a device, generate and import Device Key Encryption Key (DKEK) shares and to wrap and unwrap keys.
OPTIONS¶
--initialize, -X
Use --so-pin to define SO-PIN for first initialization or to verify in subsequent initializations.
Use --pin to define the initial user pin value.
Use --pin-retry to define the maximum number of wrong user PIN presentations.
Use with --dkek-shares to enable key wrap / unwrap.
Use with --label to define a token label
Use with --public-key-auth and --required-pub-keys to require public key authentication for login
--create-dkek-share filename, -C filename
Use --password to provide a password for encryption rather than prompting for one.
Use --pwd-shares-threshold and --pwd-shares-total to randomly generate a password and split is using a (t, n) threshold scheme.
--import-dkek-share filename, -I filename
Use --password to provide a password for decryption rather than prompting for one.
Use --pwd-shares-total to specify the number of shares that should be entered to reconstruct the password.
--wrap-key filename, -W filename
Use --pin to provide the user PIN on the command line.
--unwrap-key filename, -U filename
Determine the key reference using the output of pkcs15-tool -D.
Use --pin to provide a user PIN on the command line.
Use --force to remove any key, key description or certificate in the way.
--dkek-shares number-of-shares, -s number-of-shares
This is an optional parameter. Using --initialize without --dkek-shares will disable the DKEK completely.
Using --dkek-shares with 0 shares requests the SmartCard-HSM to generate a random DKEK. Keys wrapped with this DKEK can only be unwrapped in the same SmartCard-HSM.
After using --initialize with one or more DKEK shares, the SmartCard-HSM will remain in the initialized state until all DKEK shares have been imported. During this phase no new keys can be generated or imported.
--pin pin, --so-pin sopin,
Note that on most operation systems, any user can display the command line of any process on the system using utilities such as ps(1). Therefore, you should prefer passing the codes via an environment variable on an unsecured system.
--pin-retry value
--bio-server1 value
--bio-server2 value
--password value
--pwd-shares-threshold value
--pwd-shares-total value
--force
--label label, -l label
--reader arg, -r arg
--public-key-auth total-number-of-public-keys, -K total-number-of-public-keys
When the SmartCard-HSM is initialized with these options, it will require M-of-N public key authentication to be used, where --required-pub-keys sets the M and --public-key-auth sets the N. After the initialization, the user should use --register-public-key to register the N public keys before the SmartCard-HSM can be used.
--required-pub-keys required-number-of-public-keys, -n required-number-of-public-keys
--register-public-key input-public-key-file, -g input-public-key-file
--export-for-pub-key-auth output-public-key-file, -e output-public-key-file
--public-key-auth-status -S
--wait, -w
--verbose, -v
EXAMPLES¶
Create a DKEK share:
sc-hsm-tool --create-dkek-share dkek-share-1.pbe
Create a DKEK share with random password split up using a (3, 5) threshold scheme:
sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold 3 --pwd-shares-total 5
Initialize SmartCard-HSM to use a single DKEK share:
sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 --dkek-shares 1 --label mytoken
Import DKEK share:
sc-hsm-tool --import-dkek-share dkek-share-1.pbe
Import DKEK share using a password split up using a (3, 5) threshold scheme for encryption:
sc-hsm-tool --import-dkek-share dkek-share-1.pbe --pwd-shares-total 3
Wrap referenced key, description and certificate:
sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
Unwrap key into same or in different SmartCard-HSM with the same DKEK:
sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219 --force
Initialize SmartCard-HSM to use M-of-N public key authentication with M=2 and N=5
sc-hsm-tool --initialize --required-pub-keys 2 --public-key-auth 5
Export a public key for M-of-N public key authentication to a file
sc-hsm-tool --key-reference 1 --export-for-pub-key-auth ./public_key1.asn1
Register a public key for M-of-N public key authentication from a file
sc-hsm-tool --register-public-key ./public_key1.asn1
SEE ALSO¶
AUTHORS¶
sc-hsm-tool was written by Andreas Schwier <andreas.schwier@cardcontact.de>.
02/08/2024 | opensc |