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 --so-pin value
90 Define SO-PIN for initialization. If set to env:VARIABLE, the value
91 of the environment variable VARIABLE is used.
92 --pin value
94 Define user PIN for initialization, wrap or unwrap operation. If
95 set to env:VARIABLE, the value of the environment variable VARIABLE
96 is used.
97 --pin-retry value
99 Define number of PIN retries for user PIN during initialization.
100 Default is 3.
101 --bio-server1 value
103 The hexadecimal AID of of the biometric server for template 1.
104 Switches on the use of the user PIN as session PIN.
105 --bio-server2 value
107 The hexadecimal AID of of the biometric server for template 2.
108 Switches on the use of the user PIN as session PIN.
109 --password value
111 Define password for DKEK share encryption. If set to env:VARIABLE,
112 the value of the environment variable VARIABLE is used.
113 --pwd-shares-threshold value
115 Define threshold for number of password shares required for
116 reconstruction.
117 --pwd-shares-total value
119 Define number of password shares.
120 --force
122 Force removal of existing key, description and certificate.
123 --label label, -l label
125 Define the token label to be used in --initialize.
126 --reader arg, -r arg
128 Number of the reader to use. By default, the first reader with a
129 present card is used. If arg is an ATR, the reader with a matching
130 card will be chosen.
131 --wait, -w
133 Wait for a card to be inserted
134 --verbose, -v
136 Causes sc-hsm-tool to be more verbose. Specify this flag several
137 times to enable debug output in the opensc library.
138
140 Create a DKEK share:
141 sc-hsm-tool --create-dkek-share dkek-share-1.pbe
143 Create a DKEK share with random password split up using a (3, 5)
145 threshold scheme:
146 sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold
148 3 --pwd-shares-total 5
149 Initialize SmartCard-HSM to use a single DKEK share:
151 sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219
153 --dkek-shares 1 --label mytoken
154 Import DKEK share:
156 sc-hsm-tool --import-dkek-share dkek-share-1.pbe
158 Import DKEK share using a password split up using a (3, 5) threshold
160 scheme for encryption:
161 sc-hsm-tool --import-dkek-share dkek-share-1.pbe --pwd-shares-total 3
163 Wrap referenced key, description and certificate:
165 sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
167 Unwrap key into same or in different SmartCard-HSM with the same DKEK:
169 sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219
171 --force
172
174 opensc-tool(1)
175
177 sc-hsm-tool was written by Andreas Schwier
178 <andreas.schwier@cardcontact.de>.
179opensc 02/10/2020 SC-HSM-TOOL(1)