1SC-HSM-TOOL(1)                   OpenSC Tools                   SC-HSM-TOOL(1)
2
3
4

NAME

6       sc-hsm-tool - smart card utility for SmartCard-HSM
7

SYNOPSIS

9       sc-hsm-tool [OPTIONS]
10
11
12       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

OPTIONS

19       --initialize, -X
20           Initialize token, removing all existing keys, certificates and
21           files.
22
23           Use --so-pin to define SO-PIN for first initialization or to verify
24           in subsequent initializations.
25
26           Use --pin to define the initial user pin value.
27
28           Use --pin-retry to define the maximum number of wrong user PIN
29           presentations.
30
31           Use with --dkek-shares to enable key wrap / unwrap.
32
33           Use with --label to define a token label
34
35       --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
39           Use --password to provide a password for encryption rather than
40           prompting for one.
41
42           Use --pwd-shares-threshold and --pwd-shares-total to randomly
43           generate a password and split is using a (t, n) threshold scheme.
44
45       --import-dkek-share filename, -I filename
46           Prompt for user password, read and decrypt DKEK share and import
47           into SmartCard-HSM.
48
49           Use --password to provide a password for decryption rather than
50           prompting for one.
51
52           Use --pwd-shares-total to specify the number of shares that should
53           be entered to reconstruct the password.
54
55       --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
60           Use --pin to provide the user PIN on the command line.
61
62       --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
67           Determine the key reference using the output of pkcs15-tool -D.
68
69           Use --pin to provide a user PIN on the command line.
70
71           Use --force to remove any key, key description or certificate in
72           the way.
73
74       --dkek-shares number-of-shares, -s number-of-shares
75           Define the number of DKEK shares to use for recreating the DKEK.
76
77           This is an optional parameter. Using --initialize without
78           --dkek-shares will disable the DKEK completely.
79
80           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
84           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
89       --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
95           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
100       --pin-retry value
101           Define number of PIN retries for user PIN during initialization.
102           Default is 3.
103
104       --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
108       --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
112       --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
116       --pwd-shares-threshold value
117           Define threshold for number of password shares required for
118           reconstruction.
119
120       --pwd-shares-total value
121           Define number of password shares.
122
123       --force
124           Force removal of existing key, description and certificate.
125
126       --label label, -l label
127           Define the token label to be used in --initialize.
128
129       --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
134       --wait, -w
135           Wait for a card to be inserted
136
137       --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

EXAMPLES

142       Create a DKEK share:
143
144       sc-hsm-tool --create-dkek-share dkek-share-1.pbe
145
146       Create a DKEK share with random password split up using a (3, 5)
147       threshold scheme:
148
149       sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold
150       3 --pwd-shares-total 5
151
152       Initialize SmartCard-HSM to use a single DKEK share:
153
154       sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219
155       --dkek-shares 1 --label mytoken
156
157       Import DKEK share:
158
159       sc-hsm-tool --import-dkek-share dkek-share-1.pbe
160
161       Import DKEK share using a password split up using a (3, 5) threshold
162       scheme for encryption:
163
164       sc-hsm-tool --import-dkek-share dkek-share-1.pbe --pwd-shares-total 3
165
166       Wrap referenced key, description and certificate:
167
168       sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
169
170       Unwrap key into same or in different SmartCard-HSM with the same DKEK:
171
172       sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219
173       --force
174

SEE ALSO

176       opensc-tool(1)
177

AUTHORS

179       sc-hsm-tool was written by Andreas Schwier
180       <andreas.schwier@cardcontact.de>.
181
182
183
184opensc                            05/02/2022                    SC-HSM-TOOL(1)
Impressum