--- name: "sc-hsm-tool" section: "1" platform: "linux" package: "opensc" version: "0.27.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/sc-hsm-tool" --- # sc-hsm-tool(1) smart card utility for SmartCard-HSM ## 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)](/ps/1.md)**. 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)](/opensc-tool/1.md) ## AUTHORS **sc-hsm-tool** was written by Andreas Schwier \.