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.
81
82           For RSA keys, sets DECRYPT in privkey and ENCRYPT in pubkey. For
83           secret keys, sets both DECRYPT and ENCRYPT.
84
85       --usage-derive
86           Specify 'derive' key usage flag (EC only).
87
88       --usage-wrap
89           Specify 'wrap' key usage flag.
90
91       --label name, -a name
92           Specify the name of the object to operate on (or the token label
93           when --init-token is used).
94
95       --list-mechanisms, -M
96           Display a list of mechanisms supported by the token.
97
98       --list-objects, -O
99           Display a list of objects.
100
101       --list-slots, -L
102           Display a list of available slots on the token.
103
104       --list-token-slots, -T
105           List slots with tokens.
106
107       --list-interfaces
108           List interfaces of PKCS #11 3.0 library.
109
110       --session-rw,
111           Forces to open the PKCS#11 session with CKF_RW_SESSION.
112
113       --login, -l
114           Authenticate to the token before performing other operations. This
115           option is not needed if a PIN is provided on the command line.
116
117       --login-type
118           Specify login type ('so', 'user', 'context-specific';
119           default:'user').
120
121       --mechanism mechanism, -m mechanism
122           Use the specified mechanism for token operations. See -M for a list
123           of mechanisms supported by your token. The mechanism can also be
124           specified in hexadecimal, e.g., 0x80001234.
125
126       --mgf function
127           Use the specified Message Generation Function (MGF) function for
128           RSA-PKCS-PSS signatures or RSA-OAEP decryptions. Supported
129           arguments are MGF1-SHA1 to MGF1-SHA512 if supported by the driver.
130           The default is based on the hash selection.
131
132       --module mod
133           Specify a PKCS#11 module (or library) to load.
134
135       --moz-cert filename, -z filename
136           Test a Mozilla-like key pair generation and certificate request.
137           Specify the filename to the certificate file.
138
139       --output-file filename, -o filename
140           Specify the path to a file for output.
141
142       --pin pin, -p pin
143           Use the given pin for token operations. If set to env:VARIABLE, the
144           value of the environment variable VARIABLE is used. WARNING: Be
145           careful using this option as other users may be able to read the
146           command line from the system or if it is embedded in a script. If
147           set to env:VARIABLE, the value of the environment variable VARIABLE
148           is used.
149
150           This option will also set the --login option.
151
152       --puk puk
153           Supply User PUK on the command line.
154
155       --new-pin pin
156           Supply new User PIN on the command line.
157
158       --sensitive
159           Set the CKA_SENSITIVE attribute (object cannot be revealed in
160           plaintext).
161
162       --extractable
163           Set the CKA_EXTRACTABLE attribute (object can be extracted)
164
165       --undestroyable
166           Set the CKA_DESTROYABLE attribute to false (object cannot be
167           destroyed)
168
169       --set-id id, -e id
170           Set the CKA_ID of the object.
171
172       --show-info, -I
173           Display general token information.
174
175       --sign, -s
176           Sign some data.
177
178       --decrypt,
179           Decrypt some data.
180
181       --encrypt,
182           Encrypt some data.
183
184       --unwrap,
185           Unwrap key.
186
187       --wrap,
188           Wrap key.
189
190       --derive,
191           Derive a secret key using another key and some data.
192
193       --derive-pass-der,
194           Derive ECDHpass DER encoded pubkey for compatibility with some
195           PKCS#11 implementations
196
197       --salt-len bytes
198           Specify how many bytes of salt should be used in RSA-PSS
199           signatures. Accepts two special values: "-1" means salt length
200           equals to digest length, "-2" or "-3" means use maximum permissible
201           length. For verify operation "-2" means that the salt length is
202           automatically recovered from signature. The value "-2" for the
203           verify operation is supported for opensc pkcs#11 module only.
204           Default is digest length (-1).
205
206       --slot id
207           Specify the id of the slot to use.
208
209       --slot-description description
210           Specify the description of the slot to use.
211
212       --slot-index index
213           Specify the index of the slot to use.
214
215       --object-index index
216           Specify the index of the object to use.
217
218       --use-locking
219           Tell pkcs11 module it should use OS thread locking.
220
221       --test-threads options
222           Test a pkcs11 module's thread implication. (See source code).
223
224       --token-label label
225           Specify the label of token. Will be used the first slot, that has
226           the inserted token with this label.
227
228       --so-pin pin
229           Use the given pin as the Security Officer PIN for some token
230           operations (token initialization, user PIN initialization, etc). If
231           set to env:VARIABLE, the value of the environment variable VARIABLE
232           is used. The same warning as --pin also applies here.
233
234       --test, -t
235           Perform some tests on the token. This option is most useful when
236           used with either --login or --pin.
237
238       --test-hotplug
239           Test hotplug capabilities (C_GetSlotList + C_WaitForSlotEvent).
240
241       --private
242           Set the CKA_PRIVATE attribute (object is only viewable after a
243           login).
244
245       --always-auth
246           Set the CKA_ALWAYS_AUTHENTICATE attribute to a private key object.
247           If set, the user has to supply the PIN for each use (sign or
248           decrypt) with the key.
249
250       --allowed-mechanisms mechanisms
251           Sets the CKA_ALLOWED_MECHANISMS attribute to a key objects when
252           importing an object or generating a keys. The argument accepts
253           comma-separated list of algorithmsm, that can be used with the
254           given key.
255
256       --test-ec
257           Test EC (best used with the --login or --pin option).
258
259       --test-fork
260           Test forking and calling C_Initialize() in the child.
261
262       --type type, -y type
263           Specify the type of object to operate on. Valid value are cert,
264           privkey, pubkey, secrkey and data.
265
266       --verbose, -v
267           Cause pkcs11-tool to be more verbose.
268
269           NB! This does not affect OpenSC debugging level! To set OpenSC
270           PKCS#11 module into debug mode, set the OPENSC_DEBUG environment
271           variable to a non-zero number.
272
273       --verify,
274           Verify signature of some data.
275
276       --read-object, -r
277           Get object's CKA_VALUE attribute (use with --type).
278
279       --delete-object, -b
280           Delete an object.
281
282       --application-label label
283           Specify the application label of the data object (use with --type
284           data).
285
286       --application-id id
287           Specify the application ID of the data object (use with --type
288           data).
289
290       --issuer data
291           Specify the issuer in hexadecimal format (use with --type cert).
292
293       --subject data
294           Specify the subject in hexadecimal format (use with --type
295           cert/privkey/pubkey).
296
297       --signature-file filename
298           The path to the signature file for signature verification
299
300       --signature-format format
301           Format for ECDSA signature: 'rs' (default), 'sequence', 'openssl'.
302
303       --write-object filename, -w filename
304           Write a key or certificate object to the token.  filename points to
305           the DER-encoded certificate or key file.
306
307       --generate-random num
308           Get num bytes of random data.
309
310       --allow-sw
311           Allow using software mechanisms that do not have the CKF_HW flag
312           set. May be required when using software tokens and emulators.
313
314       --iv data
315           Initialization vector for symmetric ciphers. The data is
316           hexadecimal number, i.e. "000013aa7bffa0".
317

EXAMPLES

319       To list all certificates on the smart card:
320
321           pkcs11-tool --list-objects --type cert
322
323       To read the certificate with ID KEY_ID in DER format from smart card:
324
325           pkcs11-tool --read-object --id KEY_ID --type cert --output-file cert.der
326
327       To convert the certificate in DER format to PEM format, use OpenSSL
328       tools:
329
330           openssl x509 -inform DER -in cert.der -outform PEM > cert.pem
331
332       To sign some data stored in file data using the private key with ID ID
333       and using the RSA-PKCS mechanism:
334
335           pkcs11-tool --sign --id ID --mechanism RSA-PKCS --input-file data --output-file data.sig
336
337       To encrypt file using the AES key with ID 85 and using mechanism
338       AES-CBC with padding:
339
340           pkcs11-tool --encrypt --id 85 -m AES-CBC-PAD \
341            --iv "00000000000000000000000000000000" \
342            -i file.txt -o encrypted_file.data
343
344
345       Use the key with ID 22 and mechanism RSA-PKCS to unwrap key from file
346       aes_wrapped.key. After a successful unwrap operation, a new AES key is
347       created on token. ID of this key is set to 90 and label of this key is
348       set to unwrapped-key Note: for the MyEID card, the AES key size must be
349       present in key specification i.e. AES:16
350
351           pkcs11-tool --unwrap --mechanism RSA-PKCS --id 22 \
352             -i aes_wrapped.key --key-type AES: \
353             --application-id 90 --applicatin-label unwrapped-key
354
355
356

AUTHORS

358       pkcs11-tool was written by Olaf Kirch <okir@suse.de>.
359
360
361
362opensc                            08/08/2023                    PKCS11-TOOL(1)
Impressum