1PKCS11-TOOL(1) OpenSC Tools PKCS11-TOOL(1)
2
6 pkcs11-tool - utility for managing and using PKCS #11 security tokens
7
9 pkcs11-tool [OPTIONS]
10
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
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 --change-pin, -c
25 Change the user PIN on the token
26 --unlock-pin
28 Unlock User PIN (without --login unlock in logged in session;
29 otherwise --login-type has to be 'context-specific').
30 --hash, -h
32 Hash some data.
33 --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 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 --id id, -d id
50 Specify the id of the object to operate on.
51 --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 --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 --input-file filename, -i filename
62 Specify the path to a file for input.
63 --keypairgen, -k
65 Generate a new key pair (public and private pair.)
66 --keygen
68 Generate a new key.
69 --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 --usage-sign
76 Specify 'sign' key usage flag (sets SIGN in privkey, sets VERIFY in
77 pubkey).
78 --usage-decrypt
80 Specify 'decrypt' key usage flag.
81 For RSA keys, sets DECRYPT in privkey and ENCRYPT in pubkey. For
83 secret keys, sets both DECRYPT and ENCRYPT.
84 --usage-derive
86 Specify 'derive' key usage flag (EC only).
87 --usage-wrap
89 Specify 'wrap' key usage flag.
90 --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 --list-mechanisms, -M
96 Display a list of mechanisms supported by the token.
97 --list-objects, -O
99 Display a list of objects.
100 --list-slots, -L
102 Display a list of available slots on the token.
103 --list-token-slots, -T
105 List slots with tokens.
106 --list-interfaces
108 List interfaces of PKCS #11 3.0 library.
109 --session-rw,
111 Forces to open the PKCS#11 session with CKF_RW_SESSION.
112 --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 --login-type
118 Specify login type ('so', 'user', 'context-specific';
119 default:'user').
120 --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 --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 --module mod
133 Specify a PKCS#11 module (or library) to load.
134 --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 --output-file filename, -o filename
140 Specify the path to a file for output.
141 --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 This option will also set the --login option.
151 --puk puk
153 Supply User PUK on the command line.
154 --new-pin pin
156 Supply new User PIN on the command line.
157 --sensitive
159 Set the CKA_SENSITIVE attribute (object cannot be revealed in
160 plaintext).
161 --extractable
163 Set the CKA_EXTRACTABLE attribute (object can be extracted)
164 --undestroyable
166 Set the CKA_DESTROYABLE attribute to false (object cannot be
167 destroyed)
168 --set-id id, -e id
170 Set the CKA_ID of the object.
171 --show-info, -I
173 Display general token information.
174 --sign, -s
176 Sign some data.
177 --decrypt,
179 Decrypt some data.
180 --encrypt,
182 Encrypt some data.
183 --unwrap,
185 Unwrap key.
186 --wrap,
188 Wrap key.
189 --derive,
191 Derive a secret key using another key and some data.
192 --derive-pass-der,
194 Derive ECDHpass DER encoded pubkey for compatibility with some
195 PKCS#11 implementations
196 --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 --slot id
207 Specify the id of the slot to use.
208 --slot-description description
210 Specify the description of the slot to use.
211 --slot-index index
213 Specify the index of the slot to use.
214 --object-index index
216 Specify the index of the object to use.
217 --use-locking
219 Tell pkcs11 module it should use OS thread locking.
220 --test-threads options
222 Test a pkcs11 module's thread implication. (See source code).
223 --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 --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 --test, -t
235 Perform some tests on the token. This option is most useful when
236 used with either --login or --pin.
237 --test-hotplug
239 Test hotplug capabilities (C_GetSlotList + C_WaitForSlotEvent).
240 --private
242 Set the CKA_PRIVATE attribute (object is only viewable after a
243 login).
244 --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 --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 --test-ec
257 Test EC (best used with the --login or --pin option).
258 --test-fork
260 Test forking and calling C_Initialize() in the child.
261 --type type, -y type
263 Specify the type of object to operate on. Valid value are cert,
264 privkey, pubkey, secrkey and data.
265 --verbose, -v
267 Cause pkcs11-tool to be more verbose.
268 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 --verify,
274 Verify signature of some data.
275 --read-object, -r
277 Get object's CKA_VALUE attribute (use with --type).
278 --delete-object, -b
280 Delete an object.
281 --application-label label
283 Specify the application label of the data object (use with --type
284 data).
285 --application-id id
287 Specify the application ID of the data object (use with --type
288 data).
289 --issuer data
291 Specify the issuer in hexadecimal format (use with --type cert).
292 --subject data
294 Specify the subject in hexadecimal format (use with --type
295 cert/privkey/pubkey).
296 --signature-file filename
298 The path to the signature file for signature verification
299 --signature-format format
301 Format for ECDSA signature: 'rs' (default), 'sequence', 'openssl'.
302 --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 --generate-random num
308 Get num bytes of random data.
309 --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 --iv data
315 Initialization vector for symmetric ciphers. The data is
316 hexadecimal number, i.e. "000013aa7bffa0".
317
319 To list all certificates on the smart card:
320 pkcs11-tool --list-objects --type cert
322 To read the certificate with ID KEY_ID in DER format from smart card:
324 pkcs11-tool --read-object --id KEY_ID --type cert --output-file cert.der
326 To convert the certificate in DER format to PEM format, use OpenSSL
328 tools:
329 openssl x509 -inform DER -in cert.der -outform PEM > cert.pem
331 To sign some data stored in file data using the private key with ID ID
333 and using the RSA-PKCS mechanism:
334 pkcs11-tool --sign --id ID --mechanism RSA-PKCS --input-file data --output-file data.sig
336 To encrypt file using the AES key with ID 85 and using mechanism
338 AES-CBC with padding:
339 pkcs11-tool --encrypt --id 85 -m AES-CBC-PAD \
341 --iv "00000000000000000000000000000000" \
342 -i file.txt -o encrypted_file.data
343 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 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
358 pkcs11-tool was written by Olaf Kirch <okir@suse.de>.
359opensc 08/08/2023 PKCS11-TOOL(1)