sc-hsm-tool
1
OpenSC
OpenSC Tools
opensc

# sc-hsm-tool

smart card utility for SmartCard-HSM

    			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.

`--so-pin` value

  Define SO-PIN for initialization. If set to env:VARIABLE, the value of the environment variable VARIABLE is used.

`--pin` value

  Define user PIN for initialization, wrap or unwrap operation. If set to env:VARIABLE, the value of the environment variable VARIABLE is used.

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