sc-hsm-tool(1)

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           Use with --public-key-auth and --required-pub-keys to require
36           public key authentication for login
37
38       --create-dkek-share filename, -C filename
39           Create a DKEK share encrypted under a password and save it to the
40           file given as parameter.
41
42           Use --password to provide a password for encryption rather than
43           prompting for one.
44
45           Use --pwd-shares-threshold and --pwd-shares-total to randomly
46           generate a password and split is using a (t, n) threshold scheme.
47
48       --import-dkek-share filename, -I filename
49           Prompt for user password, read and decrypt DKEK share and import
50           into SmartCard-HSM.
51
52           Use --password to provide a password for decryption rather than
53           prompting for one.
54
55           Use --pwd-shares-total to specify the number of shares that should
56           be entered to reconstruct the password.
57
58       --wrap-key filename, -W filename
59           Wrap the key referenced in --key-reference and save with it
60           together with the key description and certificate to the given
61           file.
62
63           Use --pin to provide the user PIN on the command line.
64
65       --unwrap-key filename, -U filename
66           Read wrapped key, description and certificate from file and import
67           into SmartCard-HSM under the key reference given in
68           --key-reference.
69
70           Determine the key reference using the output of pkcs15-tool -D.
71
72           Use --pin to provide a user PIN on the command line.
73
74           Use --force to remove any key, key description or certificate in
75           the way.
76
77       --dkek-shares number-of-shares, -s number-of-shares
78           Define the number of DKEK shares to use for recreating the DKEK.
79
80           This is an optional parameter. Using --initialize without
81           --dkek-shares will disable the DKEK completely.
82
83           Using --dkek-shares with 0 shares requests the SmartCard-HSM to
84           generate a random DKEK. Keys wrapped with this DKEK can only be
85           unwrapped in the same SmartCard-HSM.
86
87           After using --initialize with one or more DKEK shares, the
88           SmartCard-HSM will remain in the initialized state until all DKEK
89           shares have been imported. During this phase no new keys can be
90           generated or imported.
91
92       --pin pin, --so-pin sopin,
93           These options can be used to specify the PIN values on the command
94           line. If the value is set to env:VARIABLE, the value of the
95           specified environment variable is used. By default, the code is
96           prompted on the command line if needed.
97
98           Note that on most operation systems, any user can display the
99           command line of any process on the system using utilities such as
100           ps(1). Therefore, you should prefer passing the codes via an
101           environment variable on an unsecured system.
102
103       --pin-retry value
104           Define number of PIN retries for user PIN during initialization.
105           Default is 3.
106
107       --bio-server1 value
108           The hexadecimal AID of of the biometric server for template 1.
109           Switches on the use of the user PIN as session PIN.
110
111       --bio-server2 value
112           The hexadecimal AID of of the biometric server for template 2.
113           Switches on the use of the user PIN as session PIN.
114
115       --password value
116           Define password for DKEK share encryption. If set to env:VARIABLE,
117           the value of the environment variable VARIABLE is used.
118
119       --pwd-shares-threshold value
120           Define threshold for number of password shares required for
121           reconstruction.
122
123       --pwd-shares-total value
124           Define number of password shares.
125
126       --force
127           Force removal of existing key, description and certificate.
128
129       --label label, -l label
130           Define the token label to be used in --initialize.
131
132       --reader arg, -r arg
133           Number of the reader to use. By default, the first reader with a
134           present card is used. If arg is an ATR, the reader with a matching
135           card will be chosen.
136
137       --public-key-auth total-number-of-public-keys, -K
138       total-number-of-public-keys
139           Define the total number of public keys to use for public key
140           authentication when using --initialize.  --public-key-auth is
141           optional, but if it's present, it must be used with
142           --required-pub-keys.
143
144           When the SmartCard-HSM is initialized with these options, it will
145           require M-of-N public key authentication to be used, where
146           --required-pub-keys sets the M and --public-key-auth sets the N.
147           After the initialization, the user should use --register-public-key
148           to register the N public keys before the SmartCard-HSM can be used.
149
150       --required-pub-keys required-number-of-public-keys, -n
151       required-number-of-public-keys
152           Define the required number of public keys to use for public key
153           authentication when using --initialize. This is the M in M-of-N
154           public key authentication. See --public-key-auth for more
155           information.
156
157       --register-public-key input-public-key-file, -g input-public-key-file
158           Register a public key to be used for M-of-N public key
159           authentication. The file can be exported from a different
160           SmartCard-HSM with --export-for-pub-key-auth. This can only be used
161           when the SmartCard-HSM has been initialized with --public-key-auth
162           and --required-pub-keys and fewer than N public keys have been
163           registered. Use --public-key-auth-status to check the how many
164           public keys have been registered.
165
166       --export-for-pub-key-auth output-public-key-file, -e
167       output-public-key-file
168           Export a public key to be used for M-of-N public key
169           authentication. This should be used with --key-reference to choose
170           the key to export. The file should be registered on another
171           SmartCard-HSM using --register-public-key.
172
173       --public-key-auth-status -S
174           Print the public key authentication status. This is only valid if
175           the SmartCard-HSM was initialized to use M-of-N public key
176           authentication.
177
178       --wait, -w
179           Wait for a card to be inserted
180
181       --verbose, -v
182           Causes sc-hsm-tool to be more verbose. Specify this flag several
183           times to enable debug output in the opensc library.
184

EXAMPLES

186       Create a DKEK share:
187
188       sc-hsm-tool --create-dkek-share dkek-share-1.pbe
189
190       Create a DKEK share with random password split up using a (3, 5)
191       threshold scheme:
192
193       sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold
194       3 --pwd-shares-total 5
195
196       Initialize SmartCard-HSM to use a single DKEK share:
197
198       sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219
199       --dkek-shares 1 --label mytoken
200
201       Import DKEK share:
202
203       sc-hsm-tool --import-dkek-share dkek-share-1.pbe
204
205       Import DKEK share using a password split up using a (3, 5) threshold
206       scheme for encryption:
207
208       sc-hsm-tool --import-dkek-share dkek-share-1.pbe --pwd-shares-total 3
209
210       Wrap referenced key, description and certificate:
211
212       sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
213
214       Unwrap key into same or in different SmartCard-HSM with the same DKEK:
215
216       sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219
217       --force
218
219       Initialize SmartCard-HSM to use M-of-N public key authentication with
220       M=2 and N=5
221
222       sc-hsm-tool --initialize --required-pub-keys 2 --public-key-auth 5
223
224       Export a public key for M-of-N public key authentication to a file
225
226       sc-hsm-tool --key-reference 1 --export-for-pub-key-auth
227       ./public_key1.asn1
228
229       Register a public key for M-of-N public key authentication from a file
230
231       sc-hsm-tool --register-public-key ./public_key1.asn1
232

AUTHORS

237       sc-hsm-tool was written by Andreas Schwier
238       <andreas.schwier@cardcontact.de>.
239
240
241
242opensc                            08/08/2023                    SC-HSM-TOOL(1)

NAME

SYNOPSIS

OPTIONS

EXAMPLES

SEE ALSO

AUTHORS