1PKCS11-TOOL(1)                   OpenSC Tools                   PKCS11-TOOL(1)
2
3
4

NAME

6       pkcs11-tool - utility for managing and using PKCS #11 security tokens
7

SYNOPSIS

9       pkcs11-tool [OPTIONS]
10

DESCRIPTION

12       The pkcs11-tool utility is used to manage the data objects on smart
13       cards and similar PKCS #11 security tokens. Users can list and read
14       PINs, keys and certificates stored on the token. User PIN
15       authentication is performed for those operations that require it.
16

OPTIONS

18       --attr-from filename
19           Extract information from filename (DER-encoded certificate file)
20           and create the corresponding attributes when writing an object to
21           the token. Example: the certificate subject name is used to create
22           the CKA_SUBJECT attribute.
23
24       --change-pin, -c
25           Change the user PIN on the token
26
27       --unlock-pin
28           Unlock User PIN (without --login unlock in logged in session;
29           otherwise --login-type has to be 'context-specific').
30
31       --hash, -h
32           Hash some data.
33
34       --hash-algorithm mechanism
35           Specify hash algorithm used with RSA-PKCS-PSS signature or RSA-OAEP
36           decryption. Allowed values are "SHA-1", "SHA256", "SHA384",
37           "SHA512", and some tokens may also allow "SHA224". Default is
38           "SHA-1".
39
40           Note that the input to RSA-PKCS-PSS has to be of the size equal to
41           the specified hash algorithm. E.g., for SHA256 the signature input
42           must be exactly 32 bytes long (for mechanisms SHA256-RSA-PKCS-PSS
43           there is no such restriction). For RSA-OAEP, the plaintext input
44           size mLen must be at most keyLen - 2 - 2*hashLen. For example, for
45           RSA 3072-bit key and SHA384, the longest plaintext to encrypt with
46           RSA-OAEP is (with all sizes in bytes): 384 - 2 - 2*48 = 286, aka
47           286 bytes.
48
49       --id id, -d id
50           Specify the id of the object to operate on.
51
52       --init-pin
53           Initializes the user PIN. This option differs from --change-pin in
54           that it sets the user PIN for the first time. Once set, the user
55           PIN can be changed using --change-pin.
56
57       --init-token
58           Initialize a token: set the token label as well as a Security
59           Officer PIN (the label must be specified using --label).
60
61       --input-file filename, -i filename
62           Specify the path to a file for input.
63
64       --keypairgen, -k
65           Generate a new key pair (public and private pair.)
66
67       --keygen
68           Generate a new key.
69
70       --key-type specification
71           Specify the type and length (bytes if symmetric) of the key to
72           create, for example RSA:1024, EC:prime256v1, GOSTR3410-2012-256:B,
73           DES:8, DES3:24, AES:16 or GENERIC:64.
74
75       --usage-sign
76           Specify 'sign' key usage flag (sets SIGN in privkey, sets VERIFY in
77           pubkey).
78
79       --usage-decrypt
80           Specify 'decrypt' key usage flag (RSA only, set DECRYPT privkey,
81           ENCRYPT in pubkey).
82
83       --usage-derive
84           Specify 'derive' key usage flag (EC only).
85
86       --usage-wrap
87           Specify 'wrap' key usage flag.
88
89       --label name, -a name
90           Specify the name of the object to operate on (or the token label
91           when --init-token is used).
92
93       --list-mechanisms, -M
94           Display a list of mechanisms supported by the token.
95
96       --list-objects, -O
97           Display a list of objects.
98
99       --list-slots, -L
100           Display a list of available slots on the token.
101
102       --list-token-slots, -T
103           List slots with tokens.
104
105       --list-interfaces
106           List interfaces of PKCS #11 3.0 library.
107
108       --login, -l
109           Authenticate to the token before performing other operations. This
110           option is not needed if a PIN is provided on the command line.
111
112       --login-type
113           Specify login type ('so', 'user', 'context-specific';
114           default:'user').
115
116       --mechanism mechanism, -m mechanism
117           Use the specified mechanism for token operations. See -M for a list
118           of mechanisms supported by your token. The mechanism can also be
119           specified in hexadecimal, e.g., 0x80001234.
120
121       --mgf function
122           Use the specified Message Generation Function (MGF) function for
123           RSA-PKCS-PSS signatures or RSA-OAEP decryptions. Supported
124           arguments are MGF1-SHA1 to MGF1-SHA512 if supported by the driver.
125           The default is based on the hash selection.
126
127       --module mod
128           Specify a PKCS#11 module (or library) to load.
129
130       --moz-cert filename, -z filename
131           Test a Mozilla-like key pair generation and certificate request.
132           Specify the filename to the certificate file.
133
134       --output-file filename, -o filename
135           Specify the path to a file for output.
136
137       --pin pin, -p pin
138           Use the given pin for token operations. If set to env:VARIABLE, the
139           value of the environment variable VARIABLE is used. WARNING: Be
140           careful using this option as other users may be able to read the
141           command line from the system or if it is embedded in a script. If
142           set to env:VARIABLE, the value of the environment variable VARIABLE
143           is used.
144
145           This option will also set the --login option.
146
147       --puk puk
148           Supply User PUK on the command line.
149
150       --new-pin pin
151           Supply new User PIN on the command line.
152
153       --sensitive
154           Set the CKA_SENSITIVE attribute (object cannot be revealed in
155           plaintext).
156
157       --extractable
158           Set the CKA_EXTRACTABLE attribute (object can be extracted)
159
160       --set-id id, -e id
161           Set the CKA_ID of the object.
162
163       --show-info, -I
164           Display general token information.
165
166       --sign, -s
167           Sign some data.
168
169       --decrypt,
170           Decrypt some data.
171
172       --derive,
173           Derive a secret key using another key and some data.
174
175       --derive-pass-der,
176           Derive ECDHpass DER encoded pubkey for compatibility with some
177           PKCS#11 implementations
178
179       --salt-len bytes
180           Specify how many bytes of salt should be used in RSA-PSS
181           signatures. Accepts two special values: "-1" means salt length
182           equals to digest length, "-2" means use maximum permissible length.
183           Default is digest length (-1).
184
185       --slot id
186           Specify the id of the slot to use.
187
188       --slot-description description
189           Specify the description of the slot to use.
190
191       --slot-index index
192           Specify the index of the slot to use.
193
194       --object-index index
195           Specify the index of the object to use.
196
197       --use-locking
198           Tell pkcs11 module it should use OS thread locking.
199
200       --test-threads options
201           Test a pkcs11 module's thread implication. (See source code).
202
203       --token-label label
204           Specify the label of token. Will be used the first slot, that has
205           the inserted token with this label.
206
207       --so-pin pin
208           Use the given pin as the Security Officer PIN for some token
209           operations (token initialization, user PIN initialization, etc). If
210           set to env:VARIABLE, the value of the environment variable VARIABLE
211           is used. The same warning as --pin also applies here.
212
213       --test, -t
214           Perform some tests on the token. This option is most useful when
215           used with either --login or --pin.
216
217       --test-hotplug
218           Test hotplug capabilities (C_GetSlotList + C_WaitForSlotEvent).
219
220       --private
221           Set the CKA_PRIVATE attribute (object is only viewable after a
222           login).
223
224       --always-auth
225           Set the CKA_ALWAYS_AUTHENTICATE attribute to a private key object.
226           If set, the user has to supply the PIN for each use (sign or
227           decrypt) with the key.
228
229       --allowed-mechanisms mechanisms
230           Sets the CKA_ALLOWED_MECHANISMS attribute to a key objects when
231           importing an object or generating a keys. The argument accepts
232           comma-separated list of algorithmsm, that can be used with the
233           given key.
234
235       --test-ec
236           Test EC (best used with the --login or --pin option).
237
238       --test-fork
239           Test forking and calling C_Initialize() in the child.
240
241       --type type, -y type
242           Specify the type of object to operate on. Valid value are cert,
243           privkey, pubkey, secrkey and data.
244
245       --verbose, -v
246           Cause pkcs11-tool to be more verbose.
247
248           NB! This does not affect OpenSC debugging level! To set OpenSC
249           PKCS#11 module into debug mode, set the OPENSC_DEBUG environment
250           variable to a non-zero number.
251
252       --verify,
253           Verify signature of some data.
254
255       --read-object, -r
256           Get object's CKA_VALUE attribute (use with --type).
257
258       --delete-object, -b
259           Delete an object.
260
261       --application-label label
262           Specify the application label of the data object (use with --type
263           data).
264
265       --application-id id
266           Specify the application ID of the data object (use with --type
267           data).
268
269       --issuer data
270           Specify the issuer in hexadecimal format (use with --type cert).
271
272       --subject data
273           Specify the subject in hexadecimal format (use with --type
274           cert/privkey/pubkey).
275
276       --signature-file filename
277           The path to the signature file for signature verification
278
279       --signature-format format
280           Format for ECDSA signature: 'rs' (default), 'sequence', 'openssl'.
281
282       --write-object filename, -w filename
283           Write a key or certificate object to the token.  filename points to
284           the DER-encoded certificate or key file.
285
286       --generate-random num
287           Get num bytes of random data.
288
289       --allow-sw
290           Allow using software mechanisms that do not have the CKF_HW flag
291           set. May be required when using software tokens and emulators.
292

EXAMPLES

294       To list all certificates on the smart card:
295
296           pkcs11-tool --list-objects --type cert
297
298       To read the certificate with ID KEY_ID in DER format from smart card:
299
300           pkcs11-tool --read-object --id KEY_ID --type cert --output-file cert.der
301
302       To convert the certificate in DER format to PEM format, use OpenSSL
303       tools:
304
305           openssl x509 -inform DER -in cert.der -outform PEM > cert.pem
306
307       To sign some data stored in file data using the private key with ID ID
308       and using the RSA-PKCS mechanism:
309
310           pkcs11-tool --sign --id ID --mechanism RSA-PKCS --input-file data --output-file data.sig
311
312

AUTHORS

314       pkcs11-tool was written by Olaf Kirch <okir@suse.de>.
315
316
317
318opensc                            08/10/2021                    PKCS11-TOOL(1)
Impressum