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

       --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.

       --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

SEE ALSO

       opensc-tool(1)

AUTHORS

       sc-hsm-tool was written by Andreas Schwier <andreas.schwier@cardcontact.de>.