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       --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       --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
93       --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
98       --pin-retry value
99           Define number of PIN retries for user PIN during initialization.
100           Default is 3.
101
102       --password value
103           Define password for DKEK share encryption. If set to env:VARIABLE,
104           the value of the environment variable VARIABLE is used.
105
106       --pwd-shares-threshold value
107           Define threshold for number of password shares required for
108           reconstruction.
109
110       --pwd-shares-total value
111           Define number of password shares.
112
113       --force
114           Force removal of existing key, description and certificate.
115
116       --label label, -l label
117           Define the token label to be used in --initialize.
118
119       --reader num, -r num
120           Use the given reader number. The default is 0, the first reader in
121           the system.
122
123       --wait, -w
124           Wait for a card to be inserted
125
126       --verbose, -v
127           Causes sc-hsm-tool to be more verbose. Specify this flag several
128           times to enable debug output in the opensc library.
129

EXAMPLES

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

NAME

SYNOPSIS

OPTIONS

EXAMPLES

SEE ALSO