Provided by: opensc_0.25.0~rc1-1build2_amd64 
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
Initialize token, removing all existing keys, certificates and files.
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
Create a DKEK share encrypted under a password and save it to the file given as parameter.
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
Prompt for user password, read and decrypt DKEK share and import into SmartCard-HSM.
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
Wrap the key referenced in --key-reference and save with it together with the key description and
certificate to the given file.
Use --pin to provide the user PIN on the command line.
--unwrap-key filename, -U filename
Read wrapped key, description and certificate from file and import into SmartCard-HSM under the key
reference given in --key-reference.
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
Define the number of DKEK shares to use for recreating the DKEK.
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,
These options can be used to specify the PIN values on the command line. If the value is set to
env:VARIABLE, the value of the specified environment variable is used. By default, the code is
prompted on the command line if needed.
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
Define number of PIN retries for user PIN during initialization. Default is 3.
--bio-server1 value
The hexadecimal AID of of the biometric server for template 1. Switches on the use of the user PIN as
session PIN.
--bio-server2 value
The hexadecimal AID of of the biometric server for template 2. Switches on the use of the user PIN as
session PIN.
--password value
Define password for DKEK share encryption. If set to env:VARIABLE, the value of the environment
variable VARIABLE is used.
--pwd-shares-threshold value
Define threshold for number of password shares required for reconstruction.
--pwd-shares-total value
Define number of password shares.
--force
Force removal of existing key, description and certificate.
--label label, -l label
Define the token label to be used in --initialize.
--reader arg, -r arg
Number of the reader to use. By default, the first reader with a present card is used. If arg is an
ATR, the reader with a matching card will be chosen.
--public-key-auth total-number-of-public-keys, -K total-number-of-public-keys
Define the total number of public keys to use for public key authentication when using --initialize.
--public-key-auth is optional, but if it's present, it must be used with --required-pub-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
Define the required number of public keys to use for public key authentication when using
--initialize. This is the M in M-of-N public key authentication. See --public-key-auth for more
information.
--register-public-key input-public-key-file, -g input-public-key-file
Register a public key to be used for M-of-N public key authentication. The file can be exported from
a different SmartCard-HSM with --export-for-pub-key-auth. This can only be used when the
SmartCard-HSM has been initialized with --public-key-auth and --required-pub-keys and fewer than N
public keys have been registered. Use --public-key-auth-status to check the how many public keys have
been registered.
--export-for-pub-key-auth output-public-key-file, -e output-public-key-file
Export a public key to be used for M-of-N public key authentication. This should be used with
--key-reference to choose the key to export. The file should be registered on another SmartCard-HSM
using --register-public-key.
--public-key-auth-status -S
Print the public key authentication status. This is only valid if the SmartCard-HSM was initialized
to use M-of-N public key authentication.
--wait, -w
Wait for a card to be inserted
--verbose, -v
Causes sc-hsm-tool to be more verbose. Specify this flag several times to enable debug output in the
opensc library.
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
opensc-tool(1)
AUTHORS
sc-hsm-tool was written by Andreas Schwier <andreas.schwier@cardcontact.de>.
opensc 04/01/2024 SC-HSM-TOOL(1)