1SC-HSM-TOOL(1) OpenSC Tools SC-HSM-TOOL(1)
2
6 sc-hsm-tool - smart card utility for SmartCard-HSM
7
9 sc-hsm-tool [OPTIONS]
10 The sc-hsm-tool utility can be used from the command line to perform
13 extended maintenance tasks not available via PKCS#11 or other tools in
14 the OpenSC package. It can be used to query the status of a
15 SmartCard-HSM, initialize a device, generate and import Device Key
16 Encryption Key (DKEK) shares and to wrap and unwrap keys.
17
19 --initialize, -X
20 Initialize token, removing all existing keys, certificates and
21 files.
22 Use --so-pin to define SO-PIN for first initialization or to verify
24 in subsequent initializations.
25 Use --pin to define the initial user pin value.
27 Use --pin-retry to define the maximum number of wrong user PIN
29 presentations.
30 Use with --dkek-shares to enable key wrap / unwrap.
32 Use with --label to define a token label
34 --create-dkek-share filename, -C filename
36 Create a DKEK share encrypted under a password and save it to the
37 file given as parameter.
38 Use --password to provide a password for encryption rather than
40 prompting for one.
41 Use --pwd-shares-threshold and --pwd-shares-total to randomly
43 generate a password and split is using a (t, n) threshold scheme.
44 --import-dkek-share filename, -I filename
46 Prompt for user password, read and decrypt DKEK share and import
47 into SmartCard-HSM.
48 Use --password to provide a password for decryption rather than
50 prompting for one.
51 Use --pwd-shares-total to specify the number of shares that should
53 be entered to reconstruct the password.
54 --wrap-key filename, -W filename
56 Wrap the key referenced in --key-reference and save with it
57 together with the key description and certificate to the given
58 file.
59 Use --pin to provide the user PIN on the command line.
61 --unwrap-key filename, -U filename
63 Read wrapped key, description and certificate from file and import
64 into SmartCard-HSM under the key reference given in
65 --key-reference.
66 Determine the key reference using the output of pkcs15-tool -D.
68 Use --pin to provide a user PIN on the command line.
70 Use --force to remove any key, key description or certificate in
72 the way.
73 --dkek-shares number-of-shares, -s number-of-shares
75 Define the number of DKEK shares to use for recreating the DKEK.
76 This is an optional parameter. Using --initialize without
78 --dkek-shares will disable the DKEK completely.
79 Using --dkek-shares with 0 shares requests the SmartCard-HSM to
81 generate a random DKEK. Keys wrapped with this DKEK can only be
82 unwrapped in the same SmartCard-HSM.
83 After using --initialize with one or more DKEK shares, the
85 SmartCard-HSM will remain in the initialized state until all DKEK
86 shares have been imported. During this phase no new keys can be
87 generated or imported.
88 --pin pin, --so-pin sopin,
90 These options can be used to specify the PIN values on the command
91 line. If the value is set to env:VARIABLE, the value of the
92 specified environment variable is used. By default, the code is
93 prompted on the command line if needed.
94 Note that on most operation systems, any user can display the
96 command line of any process on the system using utilities such as
97 ps(1). Therefore, you should prefer passing the codes via an
98 environment variable on an unsecured system.
99 --pin-retry value
101 Define number of PIN retries for user PIN during initialization.
102 Default is 3.
103 --bio-server1 value
105 The hexadecimal AID of of the biometric server for template 1.
106 Switches on the use of the user PIN as session PIN.
107 --bio-server2 value
109 The hexadecimal AID of of the biometric server for template 2.
110 Switches on the use of the user PIN as session PIN.
111 --password value
113 Define password for DKEK share encryption. If set to env:VARIABLE,
114 the value of the environment variable VARIABLE is used.
115 --pwd-shares-threshold value
117 Define threshold for number of password shares required for
118 reconstruction.
119 --pwd-shares-total value
121 Define number of password shares.
122 --force
124 Force removal of existing key, description and certificate.
125 --label label, -l label
127 Define the token label to be used in --initialize.
128 --reader arg, -r arg
130 Number of the reader to use. By default, the first reader with a
131 present card is used. If arg is an ATR, the reader with a matching
132 card will be chosen.
133 --wait, -w
135 Wait for a card to be inserted
136 --verbose, -v
138 Causes sc-hsm-tool to be more verbose. Specify this flag several
139 times to enable debug output in the opensc library.
140
142 Create a DKEK share:
143 sc-hsm-tool --create-dkek-share dkek-share-1.pbe
145 Create a DKEK share with random password split up using a (3, 5)
147 threshold scheme:
148 sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold
150 3 --pwd-shares-total 5
151 Initialize SmartCard-HSM to use a single DKEK share:
153 sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219
155 --dkek-shares 1 --label mytoken
156 Import DKEK share:
158 sc-hsm-tool --import-dkek-share dkek-share-1.pbe
160 Import DKEK share using a password split up using a (3, 5) threshold
162 scheme for encryption:
163 sc-hsm-tool --import-dkek-share dkek-share-1.pbe --pwd-shares-total 3
165 Wrap referenced key, description and certificate:
167 sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
169 Unwrap key into same or in different SmartCard-HSM with the same DKEK:
171 sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219
173 --force
174
176 opensc-tool(1)
177
179 sc-hsm-tool was written by Andreas Schwier
180 <andreas.schwier@cardcontact.de>.
181opensc 05/02/2022 SC-HSM-TOOL(1)