1P11SAK(1) openCryptoki P11SAK(1)
2
6 p11sak - Manage token keys in a PKCS #11 token repository.
7
9 p11sak command [ARGUMENTS] [OPTIONS]
10 p11sak --help|-h
12 p11sak --version|-v
13
15 The p11sak tool can be used to manage token keys in a PKCS #11 token
16 repository. The utility provides a flexible key management tool to gen‐
17 erate, list, remove, update, copy, import, and export symmetric (DES,
18 3DES, generic, AES, AES-XTS) and asymmetric (RSA, DH, DSA, EC, IBM
19 Dilithium, IBM Kyber) keys. This tool is also capable of listing the
20 keys with their PKCS #11 attributes and its values (not all attributes
21 may be displayed if a keys is sensitive).
22 Note: The p11sak tool only operates on token keys (i.e. CKA_TO‐
24 KEN=TRUE), but not on session keys (CKA_TOKEN=FALSE). Token keys are
25 stored persistently in the token's repository, while session keys are
26 not stored persistently, and only exist as long as the session is
27 alive. Thus, session keys generated or imported by the p11sak tool
28 would not exist anymore when the p11sak tool has exited.
29
31 The p11sak tool supports various commands to generate, list, remove,
32 update, import, and export token keys in a PKCS #11 token repository.
33 Generating symmetric and asymmetric keys
35 p11sak generate-key|gen-key|gen KEYTYPE [ARGUMENTS] [OPTIONS]
36 Use the generate-key|gen-key|gen command to generate a token key of the
38 specified KEYTYPE with the respective ARGUMENTS and OPTIONS. Possible
39 values for the KEYTYPE argument are:
40 des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber.
41 See below for a detailed description of the arguments and options. The
42 --help|-h option will also show the arguments and options available.
43 Generating DES/3DES keys
45 p11sak generate-key|gen-key|gen des|3des --slot|-s SLOTID [--pin|-p
46 PIN] [--force-pin-prompt] --label|-L LABEL --attr|-a ATTRS [--id|-i ID]
47 [--help|-h]
48 Use the generate-key|gen-key|gen command with the des|3des KEYTYPE ar‐
50 gument to generate a DES or 3DES key (CKK_DES or CKK_DES3). The --la‐
51 bel|-L LABEL option sets the CKA_LABEL attribute of the key and the
52 --attr|-a ATTRS option can be used to set the boolean attributes of the
53 key (see below for detailed description of the attributes). The --id|-i
54 ID option can be used to set the value of the CKA_ID attribute of the
55 key.
56 Generating generic secret keys
58 p11sak generate-key|gen-key|gen generic KEYBITS --slot|-s SLOTID
59 [--pin|-p PIN] [--force-pin-prompt] --label|-L LABEL --attr|-a ATTRS
60 [--id|-i ID] [--help|-h]
61 Use the generate-key|gen-key|gen generic KEYBITS command and KEYTYPE
63 argument to generate a generic secret key (CKK_GENERIC_SECRET) with the
64 key size in bits as specified by the KEYBITS argument.The --label|-L
65 LABEL option sets the CKA_LABEL attribute of the key and the --attr|-a
66 ATTRS option can be used to set the boolean attributes of the key (see
67 below for detailed description of the attributes). The --id|-i ID op‐
68 tion can be used to set the value of the CKA_ID attribute of the key.
69 Generating AES keys
71 p11sak generate-key|gen-key|gen aes 128|192|256 --slot|-s SLOTID
72 [--pin|-p PIN] [--force-pin-prompt] --label|-L LABEL --attr|-a ATTRS
73 [--id|-i ID] [--help|-h]
74 Use the generate-key|gen-key|gen aes 128|192|256 command and KEYTYPE
76 argument to generate a AES key (CKK_AES) with 128-, 192-, or 256-bit
77 length, respectively. The --label|-L LABEL option sets the CKA_LABEL
78 attribute of the key and the --attr|-a ATTRS option can be used to set
79 the boolean attributes of the key (see below for detailed description
80 of the attributes). The --id|-i ID option can be used to set the value
81 of the CKA_ID attribute of the key.
82 Generating AES-XTS keys
84 p11sak generate-key|gen-key|gen aes-xts 128|256 --slot|-s SLOTID
85 [--pin|-p PIN] [--force-pin-prompt] --label|-L LABEL --attr|-a ATTRS
86 [--id|-i ID] [--help|-h]
87 Use the generate-key|gen-key|gen aes-xts 128|256 command and KEYTYPE
89 argument to generate a AES-XTS key (CKK_AES_XTS) with 128- or 256-bit
90 length, respectively. The --label|-L LABEL option sets the CKA_LABEL
91 attribute of the key and the --attr|-a ATTRS option can be used to set
92 the boolean attributes of the key (see below for detailed description
93 of the attributes). The --id|-i ID option can be used to set the value
94 of the CKA_ID attribute of the key.
95 Generating RSA keys
97 p11sak generate-key|gen-key|gen rsa 512|1024|2048|4096 [PUBL-EXP]
98 --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt] --label|-L LA‐
99 BEL|PUB-LABEL:PRIV-LABEL --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i
100 ID] [--help|-h]
101 Use the generate-key|gen-key|gen rsa 1024|2048|4096 command and KEYTYPE
103 argument to generate an 512-, 1024-, 2048-, or 4096-bit RSA key
104 (CKK_RSA), respectively. The --label|-L LABEL|PUB-LABEL:PRIV-LABEL op‐
105 tion sets the CKA_LABEL attribute of the key and the --attr|-a AT‐
106 TRS|PUB-ATTRS:PRIV-ATTRS option can be used to set the boolean at‐
107 tributes of the key (see below for detailed description of the at‐
108 tributes). Optionally, set individual key attributes for public and
109 private key separated by a colon (:). The --id|-i ID option can be used
110 to set the value of the CKA_ID attribute of the key. Furthermore, the
111 optional PUBL-EXP argument allows the user to specify the exponent used
112 for generating the RSA key. The default is set to 65537 according to
113 the PKCS #11 standard.
114 Generating DH keys
116 p11sak generate-key|gen-key|gen dh GROUP|DH-PARAM-PEM-FILE [PRIV-BITS]
117 --slot|-s SLOTID [--pin|-p PIN] [--force-pin-prompt] --label|-L LA‐
118 BEL|PUB-LABEL:PRIV-LABEL --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i
119 ID] [--help|-h]
120 Use the generate-key|gen-key|gen dh GROUP|DH-PARAM-PEM-FILE command and
122 KEYTYPE argument to generate a DH key (CKK_DH), where GROUP specifies
123 the Diffie-Hellman FFC group name or DH-PARAM-PEM-FILE specifies the
124 name of a DH parameters PEM file. The following arguments can be used
125 for respective groups:
126 ffdhe2048|ffdhe3072|ffdhe4096|ffdhe6144|ffdhe8192|modp1536|modp2048|modp3072|modp4096|modp6144|modp8192
127 Note: Not all groups are supported by all tokens and key generation
129 will fail when the specified GROUP is not supported. Also, not all
130 groups are supported by all OpenSSL versions. If the p11sak tool is
131 compiled against an OpenSSL version that does not support certain
132 groups, then those groups are not accepted for the GROUP argument.
133 Alternatively, specify a DH parameters PEM file as DH-PARAM-PEM-FILE
135 argument. You can for example generate DH parameters using the OpenSSL
136 command line tool as follows: 'openssl dhparam <numbits> -out
137 <pem-file> -outform PEM'. See the OpenSSL man page for details about
138 this command.
139 The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL at‐
141 tribute of the key and the --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS option
142 can be used to set the boolean attributes of the key (see below for de‐
143 tailed description of the attributes). Optionally, set individual key
144 attributes for public and private key separated by a colon (:). The
145 --id|-i ID option can be used to set the value of the CKA_ID attribute
146 of the key. Furthermore, the optional PRIV-BITS argument allows the
147 user to specify the size of the private key in bits.
148 Generating DSA keys
150 p11sak generate-key|gen-key|gen dsa DSA-PARAM-PEM-FILE --slot|-s SLOTID
151 [--pin|-p PIN] [--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LA‐
152 BEL --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
153 Use the generate-key|gen-key|gen dsa DSA-PARAM-PEM-FILE command and
155 KEYTYPE argument to generate a DSA key (CKK_DSA), where
156 DSA-PARAM-PEM-FILE specifies the name of a DSA parameters PEM file. You
157 can for example generate DSA parameters using the OpenSSL command line
158 tool as follows: 'openssl dsaparam <numbits> -out <pem-file> -outform
159 PEM'. See the OpenSSL man page for details about this command.
160 The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL at‐
162 tribute of the key and the --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS option
163 can be used to set the boolean attributes of the key (see below for de‐
164 tailed description of the attributes). Optionally, set individual key
165 attributes for public and private key separated by a colon (:). The
166 --id|-i ID option can be used to set the value of the CKA_ID attribute
167 of the key.
168 Generating EC keys
170 p11sak generate-key|gen-key|gen ec CURVE --slot|-s SLOTID [--pin|-p
171 PIN] [--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LABEL
172 --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
173 Use the generate-key|gen-key|gen ec CURVE command and KEYTYPE argument
175 to generate an EC key (CKK_EC), where CURVE specifies the elliptic
176 curve used to create the EC key. The following arguments can be used
177 for respective curves:
178 prime256v1|prime192|secp224|secp384r1|secp521r1|secp265k1|brain‐
179 poolP160r1|brainpoolP160t1|brainpoolP192r1|brainpoolP192t1|brain‐
180 poolP224r1|brainpoolP224t1|brainpoolP256r1|brainpoolP256t1|brain‐
181 poolP320r1|brainpoolP320t1|brainpoolP384r1|brainpoolP384t1|brain‐
182 poolP512r1|brainpoolP512t1|curve25519|curve448|ed25519|ed448
183 Note: Not all curves will be supported by all tokens and key generation
185 will fail when the specified CURVE is not supported.
186 The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL at‐
188 tribute of the key and the --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS option
189 can be used to set the boolean attributes of the key (see below for de‐
190 tailed description of the attributes). Optionally, set individual key
191 attributes for public and private key separated by a colon (:). The
192 --id|-i ID option can be used to set the value of the CKA_ID attribute
193 of the key.
194 Generating IBM Dilithium keys
196 p11sak generate-key|gen-key|gen ibm-dilithium VERSION --slot|-s SLOTID
197 [--pin|-p PIN] [--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LA‐
198 BEL --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
199 Use the generate-key|gen-key|gen ibm-dilithium VERSION command and KEY‐
201 TYPE argument to generate an IBM Dilithium key (CKK_IBM_PQC_DILITHIUM),
202 where VERSION specifies the version of the IBM Dilithium keypair. The
203 following arguments can be used for respective keys:
204 r2_65|r2_87|r2_44|r3_65|r3_87
205 Note: Not all IBM Dilithium versions will be supported by all tokens
207 and key generation will fail when the specified VERSION is not sup‐
208 ported.
209 The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL at‐
211 tribute of the key and the --attr|-a ATTRS can be used to set the bool‐
212 ean attributes of the key (see below for detailed description of the
213 attributes). Optionally, set individual key attributes for public and
214 private key separated by a colon (:). The --id|-i ID option can be used
215 to set the value of the CKA_ID attribute of the key.
216 Generating IBM Kyber keys
218 p11sak generate-key|gen-key|gen ibm-kyber VERSION --slot|-s SLOTID
219 [--pin|-p PIN] [--force-pin-prompt] --label|-L LABEL|PUB-LABEL:PRIV-LA‐
220 BEL --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS [--id|-i ID] [--help|-h]
221 Use the generate-key|gen-key|gen ibm-kyber VERSION command and KEYTYPE
223 argument to generate an IBM Kyber key (CKK_IBM_PQC_KYBER), where VER‐
224 SION specifies the version of the IBM Kyber keypair. The following ar‐
225 guments can be used for respective keys: r2_768|r2_1024
226 Note: Not all IBM Kyber versions will be supported by all tokens and
228 key generation will fail when the specified VERSION is not supported.
229 The --label|-L LABEL|PUB-LABEL:PRIV-LABEL option sets the CKA_LABEL at‐
231 tribute of the key and the --attr|-a ATTRS can be used to set the bool‐
232 ean attributes of the key (see below for detailed description of the
233 attributes). Optionally, set individual key attributes for public and
234 private key separated by a colon (:). The --id|-i ID option can be used
235 to set the value of the CKA_ID attribute of the key.
236 Listing symmetric and asymmetric keys
238 p11sak list-key|ls-key|ls [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN]
239 [--force-pin-prompt] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS]
240 [--long|-l] [--detailed-uri] [--sort|-S SORT-SPEC] [--help|-h]
241 Use the list-key|ls-key|ls command and the optional KEYTYPE argument to
243 list symmetric or asymmetric keys. Public, private, secret, or all keys
244 can also be listed irrespective of the key type.
245 Possible values for the KEYTYPE argument are:
247 des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber|pub‐
248 lic|private|secret|all. If KEYTYPE is omitted, then all key types are
249 listed.
250 Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a AT‐
252 TRS options to filter the list of keys to display. You can use wild‐
253 cards (* and ?) in the LABEL specification. To specify a wildcard char‐
254 acter that should not be treated as a wildcard, it must be escaped us‐
255 ing a backslash (\* or \?). Also, a backslash character that should
256 not be treated as an escape character must be escaped (\\). The ID
257 must be specified as hex string (not prefixed with 0x) of any number of
258 bytes.
259 By default, the keys are listed in a short, tabular format showing only
261 the boolean attributes, the key type (CKA_KEY_TYPE) and the key label
262 (CKA_LABEL). The attributes are denoted using the same single letters
263 as used with the --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS option. When op‐
264 tion --long|-l is specified, the keys are listed in long format, dis‐
265 playing the values of all attributes defined for the key type, includ‐
266 ing non-boolean attributes.
267 By default, the keys are displayed in the order as they are retrieved
269 from the PKCS #11 implementation. To display the keys in a certain or‐
270 der, specify the --sort|-S SORT-SPEC option. You can sort the keys by
271 label, key type, object class, and/or key size. For details, see the
272 description of the --sort|-S SORT-SPEC option below.
273 Deleting symmetric and asymmetric keys
275 p11sak remove-key|rm-key|rm [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN]
276 [--force-pin-prompt] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS]
277 [--long|-l] [--force|-f] [--help|-h]
278 Use the remove-key|rm-key|rm command and the optional KEYTYPE argument
280 to remove symmetric or asymmetric keys. Public, private, secret, or all
281 keys can also be selected for removal irrespective of the key type.
282 Possible values for the KEYTYPE argument are:
284 des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber|pub‐
285 lic|private|secret|all. If KEYTYPE is omitted, then all key types are
286 selected for removal.
287 Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a AT‐
289 TRS options to filter the list of keys to display. You can use wild‐
290 cards (* and ?) in the LABEL specification. To specify a wildcard char‐
291 acter that should not be treated as a wildcard, it must be escaped us‐
292 ing a backslash (\* or \?). Also, a backslash character that should
293 not be treated as an escape character must be escaped (\\). The ID
294 must be specified as hex string (not prefixed with 0x) of any number of
295 bytes.
296 The user will be prompted to confirm the removal of the key. To sup‐
298 press the prompt, use the --force|-f option.
299 Setting or updating boolean attributes of symmetric and asymmetric keys
301 p11sak set-key-attr|set-key|set [KEYTYPE] --slot|-s SLOTID [--pin|-p
302 PIN] [--force-pin-prompt] [--label|-L LABEL] [--id|-i ID] [--attr|-a
303 ATTRS] [--force|-f] [--new-attr|-A ATTRS] [--new-label|-l LABEL]
304 [--new-id|-I ID] [--help|-h]
305 Use the set-key-attrs | set-key | set command and the optional KEYTYPE
307 argument to set or update boolean attributes of symmetric or asymmetric
308 keys. Public, private, secret, or all keys can also be selected for
309 updating irrespective of the key type.
310 Possible values for the KEYTYPE argument are:
312 des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber|pub‐
313 lic|private|secret|all. If KEYTYPE is omitted, then all key types are
314 selected for updating.
315 Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a AT‐
317 TRS options to filter the list of keys to display. You can use wild‐
318 cards (* and ?) in the LABEL specification. To specify a wildcard char‐
319 acter that should not be treated as a wildcard, it must be escaped us‐
320 ing a backslash (\* or \?). Also, a backslash character that should
321 not be treated as an escape character must be escaped (\\). The ID
322 must be specified as hex string (not prefixed with 0x) of any number of
323 bytes.
324 Use the --new-attr|-A ATTRS option to specify the boolean attributes of
326 the key you want to update (see below for detailed description of the
327 attributes). Attributes that are not specified are not changed. Use the
328 --new-label|-l LABEL option to specify the new label, or the
329 --new-id|-I ID option to specify the new ID to set for the key. At
330 least one of the --new-attr|-A ATTRS, --new-label|-l LABEL, or
331 --new-id|-I ID options must be specified.
332 The user will be prompted to confirm the updating of the key. To sup‐
334 press the prompt, use the --force|-f option.
335 Coyping symmetric and asymmetric keys
337 p11sak copy-key|copy|cp [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN]
338 [--force-pin-prompt] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS]
339 [--force|-f] [--new-attr|-A ATTRS] [--new-label|-l LABEL] [--new-id|-I
340 ID] [--help|-h]
341 Use the copy-key | copy | cp command and the optional KEYTYPE argument
343 to copy symmetric or asymmetric keys and optionally set or change bool‐
344 ean attributes, the label, or ID of the copied keys. Public, private,
345 secret, or all keys can also be copied irrespective of the key type.
346 Possible values for the KEYTYPE argument are:
348 des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber|pub‐
349 lic|private|secret|all. If KEYTYPE is omitted, then all key types are
350 selected for copying.
351 Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a AT‐
353 TRS options to filter the list of keys to display. You can use wild‐
354 cards (* and ?) in the LABEL specification. To specify a wildcard char‐
355 acter that should not be treated as a wildcard, it must be escaped us‐
356 ing a backslash (\* or \?). Also, a backslash character that should
357 not be treated as an escape character must be escaped (\\). The ID
358 must be specified as hex string (not prefixed with 0x) of any number of
359 bytes.
360 Use the --new-attr|-A ATTRS option to specify the boolean attributes of
362 the copied key you want to set or update (see below for detailed de‐
363 scription of the attributes). Attributes that are not specified are not
364 changed. Use the --new-label|-l LABEL option to specify the new label,
365 or the --new-id|-I ID option to specify the new ID to set for the
366 copied key.
367 The user will be prompted to confirm the copying of the key. To sup‐
369 press the prompt, use the --force|-f option.
370 Importing symmetric and asymmetric keys from a file
372 p11sak import-key|import|imp KEYTYPE [KIND] --slot|-s SLOTID [--pin|-p
373 PIN] [--force-pin-prompt] --label|-L LABEL [--id|-i ID] [--force|-f]
374 [--attr|-a ATTRS] --file|-F FILENAME [--pem-password|-P PASSWORD]
375 [--force-pem-pwd-prompt] [--opaque|-o] [--help|-h]
376 Use the import-key|import|imp command and KEYTYPE argument to import an
378 symmetric or asymmetric key from a file. When importing an asymmetric
379 key, the KIND argument is required and specifies to either import a
380 private or public key.
381 Possible values for the KEYTYPE argument are:
383 des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber|pub‐
384 lic|private|secret|all.
385 The --label|-L LABEL option sets the CKA_LABEL attribute of the key and
387 the --attr|-a ATTRS can be used to set the boolean attributes of the
388 key (see below for detailed description of the attributes). The --id|-i
389 ID option can be used to set the value of the CKA_ID attribute of the
390 key.
391 The --file|-F FILENAME option specifies the file name of the file that
393 contains the key to be imported. For symmetric keys, this is a binary
394 file containing the key material in clear. For asymmetric keys, this
395 is an OpenSSL PEM file containing a public or private key. PEM files
396 can optionally be password protected. Specify the PEM password with the
397 --pem-password|-P PASSWORD option or environment variable
398 P11SAK_PEM_PASSWORD. If the PEM file is password protected, but no PEM
399 password is specified, you will be prompted for the PEM password.
400 Specify the --opaque|-o option to import an opaque secure key blob. Not
401 all tokens support this.
402 Exporting symmetric and asymmetric keys to a file
404 p11sak export-key|export|exp [KEYTYPE] --slot|-s SLOTID [--pin|-p PIN]
405 [--force-pin-prompt] [--label|-L LABEL] [--id|-i ID] [--attr|-a ATTRS]
406 [--force|-f] --file|-F FILENAME [--opaque|-o] [--spki|-S] [--help|-h]
407 Use the export-key|export|exp command and the optional KEYTYPE argument
409 to export symmetric or asymmetric keys to a file. Public, private, se‐
410 cret, or all keys can also be selected for export irrespective of the
411 key type.
412 Possible values for the KEYTYPE argument are:
414 des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber|pub‐
415 lic|private|secret|all. If KEYTYPE is omitted, then all key types are
416 selected for export.
417 Specify the --label|-L LABEL, the --id|-i ID, and/or the --attr|-a AT‐
419 TRS options to filter the list of keys to display. You can use wild‐
420 cards (* and ?) in the LABEL specification. To specify a wildcard char‐
421 acter that should not be treated as a wildcard, it must be escaped us‐
422 ing a backslash (\* or \?). Also, a backslash character that should
423 not be treated as an escape character must be escaped (\\). The ID
424 must be specified as hex string (not prefixed with 0x) of any number of
425 bytes.
426 The --file|-F FILENAME option specifies the file name of the file to
428 which the keys to be exported are written to. For symmetric keys, this
429 is a binary file where the key material in clear is written to. For
430 asymmetric keys, this is an OpenSSL PEM file where the public or pri‐
431 vate keys are written to. If multiple asymmetric keys match the filter,
432 the keys are appended to the PEM file specified with the --file|-F
433 FILENAME option. If multiple symmetric keys or a mixture of asymmetric
434 and symmetric keys match the filter, then you are prompted to confirm
435 to overwrite the previously created file, unless the [--force|-f] op‐
436 tion is specified.
437 Specify the --opaque|-o option to export the opaque secure key blobs of
439 the key. Not all tokens support this.
440 Specify the --spki|-S option to export the Subject Public Key Info
442 (SPKI) from the CKA_PUBLIC_KEY_INFO attribute of an asymmetric private
443 key instead of its private key material. This option can only be used
444 with private keys.
445 Note: Not all keys can be exported, because its attribute setting may
447 forbid to reveal the values of certain attributes. To allow exporting
448 of a secret (CKO_SECRET_KEY) or private (CKO_PRIVATE_KEY) key, attri‐
449 bute CKA_SENSITIVE must be CK_FALSE and attribute CKA_EXTRACTABLE must
450 be CK_TRUE. Secret or private keys that contain an opaque secure key
451 blob (attribute CKA_IBM_OPAQUE) can also not be exported in clear, even
452 if the attributes would allow it. For such keys only the opaque secure
453 key blob can be exported by using the --opaque|-o option.
454
456 KEYTYPE
457 Selects the respective symmetric or asymmetric key to be generated, im‐
458 ported or selected. Possible values are:
459 des|3des|generic|aes|aes-xts|rsa|dh|dsa|ec|ibm-dilithium|ibm-kyber|pub‐
460 lic|private|secret|all. The public|private|secret|all argument can
461 only be used with commands that use the KEYTYPE argument as filter,
462 such as the list-key command, the remove-key command, the set-key-attrs
463 command, or the export-key command.
464 KEYBITS
466 Specifies the size of the key in bits. For the aes key type, possible
467 values are 128|192|256. For the aes-xts key type, possible values are
468 128|256. For the rsa key type, possible values are 512|1024|2048|4096.
469 PUBL-EXP
471 Specifies the public exponent for an RSA key. If not specified, the de‐
472 fault is 65537 according to the PKCS #11 standard.
473 PRIV-BITS
475 Specifies the size of the private key in bits for an DH key.
476 GROUP
478 Specifies the Diffie-Hellman FFC group name for an DH key. Possible
479 values are
480 ffdhe2048|ffdhe3072|ffdhe4096|ffdhe6144|ffdhe8192|modp1536|modp2048|modp3072|modp4096|modp6144|modp8192.
481 Note: Not all groups are supported by all tokens and key generation
483 will fail when the specified GROUP is not supported. Also, not all
484 groups are supported by all OpenSSL versions. If the p11sak tool is
485 compiled against an OpenSSL version that does not support certain
486 groups, then those groups are not accepted for the GROUP argument.
487 DH-PARAM-PEM-FILE
489 Specifies the DH parameters PEM file name. You can for example generate
490 DH parameters using the OpenSSL command line tool as follows: 'openssl
491 dhparam <numbits> -out <pem-file> -outform PEM' . See the OpenSSL man
492 page for details about this command.
493 DSA-PARAM-PEM-FILE
495 Specifies the DSA parameters PEM file name. You can for example gener‐
496 ate DSA parameters using the OpenSSL command line tool as follows:
497 'openssl dsaparam <numbits> -out <pem-file> -outform PEM' . See the
498 OpenSSL man page for details about this command.
499 CURVE
501 Specifies the curve for an EC key. Possible values are:
502 prime256v1|prime192|secp224|secp384r1|secp521r1|secp265k1|brain‐
503 poolP160r1|brainpoolP160t1|brainpoolP192r1|brainpoolP192t1|brain‐
504 poolP224r1|brainpoolP224t1|brainpoolP256r1|brainpoolP256t1|brain‐
505 poolP320r1|brainpoolP320t1|brainpoolP384r1|brainpoolP384t1|brain‐
506 poolP512r1|brainpoolP512t1|curve25519|curve448|ed25519|ed448.
507 VERSION
509 Specifies the version for an IBM Dilithium or IBM Kyber key. For the
510 ibm-dilithium key type, possible values are
511 r2_65|r2_87|r2_44|r3_65|r3_87. For the ibm-kyber key type, possible
512 values are r2_768|r2_1024.
513 KIND
515 Specifies the kind of the asymmetric key to import. Possible values are
516 public|private.
517
519 --slot|-s SLOT
520 Specifies the slot number of the token to use.
521 --pin|-p PIN
523 Specifies the token user PIN to login with.
524 Alternatively, the PKCS11_USER_PIN environment variable may be
526 used to provide the token user PIN. If neither this option is
527 specified nor the einvironment variable is set, you are
528 prompted for the PIN.
529 --force-pin-prompt
531 Enforce the p11sak tool to prompt for the token user PIN (re‐
532 gardless if it has been specified elsewhere)
533 --label|-L LABEL|PUB-LABEL:PRIV-LABEL
535 Specifies the key label attribute value (CKA_LABEL).
536 For commands such as the list-key command, the remove-key com‐
538 mand, the set-key-attrs command, and the export-key command,
539 specify the label to filter the list of keys to operate on. You
540 can use wildcards (* and ?) in the LABEL specification. To
541 specify a wildcard character that should not be treated as a
542 wildcard, it must be escaped using a backslash (\* or \?).
543 Also, a backslash character that should not be treated as an
544 escape character must be escaped (\\).
545 For generation of asymmetric keys, the specified label is ap‐
547 pended by :pub and :prv for the public and private key objects.
548 Optionally, a user can set different labels for the public and
549 private key objects by specifying them separated by a colon
550 (:), e.g. pub-label:priv-label. The label string in front of
551 the colon is used as label for the public key object, the label
552 string after the colon is used for the private key object. To
553 set the public and private key label the exact same, use
554 pub-label:=. The equal sign (=) means to use the same label
555 string for the private key objects as for the public key ob‐
556 ject. In case a colon character or a equal sign is supposed to
557 appear within a label string, it must be escaped using a back
558 slash (\), e.g. abc\:xyz results in abx:xyz where the colon is
559 not treated as separator character. Note that the shell may
560 interpret escape characters as well, so better quote the LA‐
561 BEL|PUB-LABEL:PRIV-LABEL specification.
562 --id|-i ID
564 Specifies the key ID attribute value (CKA_ID) as hex string
565 (not prefixed with 0x) of any number of bytes.
566 For commands such as the list-key command, the remove-key com‐
568 mand, the set-key-attrs command, and the export-key command,
569 specify the key ID to filter the list of keys to operate on.
570 For generation of asymmetric keys, the same ID is set for both,
572 the public and the private key.
573 --attr|-a ATTRS|PUB-ATTRS:PRIV-ATTRS
575 For the generate-key command the and import-key commands, spec‐
576 ify the boolean attributes that are to be set for the new
577 key(s). For commands such as the list-key command, the re‐
578 move-key command, the set-key-attrs command, and the export-key
579 command, specify the attribute values to filter the list of
580 keys to operate on.
581 Note: Not all boolean attributes are applicable to all key
583 types and/or commands and will be silently ignored if not ap‐
584 plicable.
585 The respective attributes are set to TRUE when the correspond‐
587 ing letter is specified in uppercase, or FALSE when the corre‐
588 sponding letter is specified in lowercase. Attributes (except
589 CKA_TOKEN and CKA_SENSITIVE, see below) that are not specified
590 get the default value as defined by the PKCS #11 standard or
591 the used PKCS #11 token implementation when generating keys, or
592 are not updated when setting the attributes of an existing key.
593 Attribute CKA_TOKEN is always set to TRUE when generating a
595 key. The p11sak tool always generates token keys, since session
596 keys are not persistent, and thus would no longer exist after
597 the session that the p11sak tool has opened for generating the
598 key is closed when it exists.
599 When generating or importing a key with the p11sak tool, attri‐
601 bute CKA_SENSITIVE defaults to TRUE for secret keys or the pri‐
602 vate key of asymmetric key pairs. However, this can be overrid‐
603 den by specifying the respective uppercase or lowercase letter
604 for the CKA_SENSITIVE attribute in the attribute string, as de‐
605 sired.
606 Note: The default setting for the CKA_SENSITIVE attribute is
608 defined by the p11sak tool, and might be different from the de‐
609 fault setting that would be chosen by the used PKCS #11 imple‐
610 mentation.
611 The following letters are associated with the respective CK_AT‐
613 TRIBUTE:
614 • P - CKA_PRIVATE
616 • L - CKA_LOCAL (read only)
618 • M - CKA_MODIFIABLE
620 • B - CKA_COPYABLE
622 • Y - CKA_DESTROYABLE
624 • R - CKA_DERIVE
626 • E - CKA_ENCRYPT
628 • D - CKA_DECRYPT
630 • G - CKA_SIGN
632 • C - CKA_SIGN_RECOVER
634 • V - CKA_VERIFY
636 • O - CKA_VERIFY_RECOVER
638 • W - CKA_WRAP
640 • U - CKA_UNWRAP
642 • S - CKA_SENSITIVE
644 • A - CKA_ALWAYS_SENSITIVE (read only)
646 • X - CKA_EXTRACTABLE
648 • N - CKA_NEVER_EXTRACTABLE (read only)
650 • T - CKA_TRUSTED (can only be set by SO user)
652 • I - CKA_WRAP_WITH_TRUSTED
654 • K - CKA_IBM_PROTKEY_EXTRACTABLE (IBM specific, not all tokens
656 support this)
657 • Z - CKA_IBM_PROTKEY_NEVER_EXTRACTABLE (IBM specific, not all
659 tokens support this, read only)
660 For multiple attributes, specify a set of these letters without
662 any blanks in between, e. g. 'MlD'. An uppercase letter means
663 TRUE, while a lowercase letter means FALSE. From Example
664 above, 'MlD' corresponds to: CKA_MODIFIABLE=TRUE, CKA_LO‐
665 CAL=FALSE, CKA_DECRYPT=TRUE.
666 For generating asymmetric keys set individual key attributes
668 for public and private key separated by a colon (:). The at‐
669 tributes in front of the colon are set for the public key and
670 the attributes after the colon are set for the private key.
671 When no colon is used, the same attribute set is used for both,
672 the public and private keys. To set a configuration for only
673 the public key, the string must end with the colon and respec‐
674 tively, to use a configuration for the private key only, the
675 string must start with the colon.
676 --new-attr|-A ATTRS
678 Specifies the boolean attributes to set or update for a key
679 with the set-key-attr or copy-key commands. See the description
680 of the --attr|-a option above for a list of letters that are
681 associated with the respective CK_ATTRIBUTE.
682 --new-label|-L LABEL
684 Specifies the new label attribute value (CKA_LABEL) to set for
685 the key.
686 --new-id|-I ID
688 Specifies the new ID attribute value (CKA_ID) as hex string
689 (not prefixed with 0x) of any number of bytes to set for the
690 key.
691 --long|-l
693 Prints the list-key output in long format, displaying the val‐
694 ues of all attributes defined for the key type, including non-
695 boolean attributes. If the --long|-l option is omitted, the
696 output is in a short, tabular format, showing only the boolean
697 attributes, the key type (CKA_KEY_TYPE) and the key label
698 (CKA_LABEL).
699 --detailed-uri
701 Displayes a detailed PKCS #11 URI.
702 --sort|-S SORT-SPEC
704 Sort the keys by label, key type, object class, and/or key
705 size. Specify a sort selection of up to 4 fields, each field
706 represented by its coresponding letter, separated by comma (,):
707 • l - sort by label (CKA_LABEL)
709 • k - sort by key type (CKA_KEY_TYPE)
711 • c - sort by object class (CKA_CLASS, secret key, private key,
713 public key)
714 • s - sort by key size (CKA_VALUE_LEN, or derived from other
716 key type spcifi attribute)
717 The sort order can be appended to the field designator by a
719 colon (:) and its coressponding letter:
720 • a - ascending order (default)
722 • d - descending order
724 Example: l:a,k:d will sort by label in ascending order and then
726 by key type in descending order.
727 --force|-f
729 Suppress the prompt whether the user wants to remove, update,
730 or export the keys matching the specified KEYTYPE, label, and
731 ID filter (if specified).
732 --file|-F FILENAME
734 For the import-key command, this option specifies the file name
735 of the file that contains the key to be imported. For symmetric
736 keys, this is a binary file containing the key material in
737 clear. For asymmetric keys, this is an OpenSSL PEM file con‐
738 taining a public or private key. PEM files used for importing
739 keys can be password protected. Specify the PEM password with
740 the --pem-password|-P PASSWORD option or environment variable
741 P11SAK_PEM_PASSWORD. If the PEM file is password protected,
742 but no PEM password is specified, you will be prompted for the
743 PEM password.
744 For the export-key command, this option specifies the file name
746 of the file to which the keys to be exported are written to.
747 For symmetric keys, this is a binary file where the key mate‐
748 rial in clear is written to. For asymmetric keys, this is an
749 OpenSSL PEM file where the public or private keys are written
750 to. If multiple asymmetric keys match the filter, the keys are
751 appended to the PEM file specified with this option. If multi‐
752 ple symmetric keys or a mixture of asymmetric and symmetric
753 keys match the filter, then you are prompted to confirm to
754 overwrite the previously created file, unless the [--force|-f]
755 option is specified.
756 --pem-password|-P PASSWORD
758 Specifies the password of the PEM file specified with the
759 --file|-F FILENAME option for the import-key command. If the
760 PEM file is password protected, but this option is not speci‐
761 fied, nor environment variable P11SAK_PEM_PASSWORD is set, you
762 will be prompted for the PEM password.
763 --force-pem-pwd-prompt
765 Enforce the import-key command to prompt for the PEM password
766 (regardless if it has been specified elsewhere).
767 --opaque
769 The key material in the file specified with the --file|-F FILE‐
770 NAME option is an opaque secure key blob. Not all tokens sup‐
771 port this.
772 --help|-h
774 Prints help for the usage of the p11sak tool and/or the respec‐
775 tive command and then exits.
776 --version|-v
778 Prints the version of the p11sak tool and then exits.
779
781 /etc/opencryptoki/p11sak_defined_attrs.conf
782 ~/.p11sak_defined_attrs.conf
783 In the output config file a user can define additional attributes,
784 which are not mentioned in the PKCS#11 standard or are not known by the
785 p11sak tool. A custom file path can be set with environment variable
786 P11SAK_DEFAULT_CONF_FILE. If the environment variable is not set, then
787 .p11sak_defined_attrs.conf is first tried to be read from the current
788 user's home directory. If this is not available, the global /etc/open‐
789 cryptoki/p11sak_defined_attrs.conf config file is read. If none of
790 these files are available, a warning message is displayed, and printing
791 of custom attributes is not available.
792
794 P11SAK_DEFAULT_CONF_FILE
795 A custom path for the p11sak_defined_attrs.conf config file can be set
796 with the environment variable P11SAK_DEFAULT_CONF_FILE. If the envi‐
797 ronment variable is not set, then .p11sak_defined_attrs.conf is first
798 tried to be read from the current user's home directory. If this is not
799 available, the global /etc/opencryptoki/p11sak_defined_attrs.conf con‐
800 fig file is read. If none of these files are available, a warning mes‐
801 sage is displayed, and printing of custom attributes is not available.
802 PKCS11_USER_PIN
804 The token user PIN can be specified via the environment variable
805 PKCS11_USER_PIN. If this environment variable is not set, and the op‐
806 tion --pin|-p PIN is not specified, p11sak will prompt for the token
807 user PIN interactively.
808 PKCSLIB
810 An alternative PKCS #11 library name can be specified with the PKCSLIB
811 environment variable. If this environment variable is not set, then the
812 default PKCS #11 library libopencryptoki.so is used.
813 P11SAK_PEM_PASSWORD
815 PEM files used for importing keys from can be password protected. The
816 PEM password can be specified via the environment variable
817 P11SAK_PEM_PASSWORD. If this environment variable is not set, and the
818 option --pem-password|-P PASSWORD is not specified, p11sak will prompt
819 for the PEM password interactively.
820
822 The p11sak tool returns error codes as defined by the PKCS #11 stan‐
823 dard, i.e. the CKR_nnn errors. On success, CKR_OK (which is zero) is
824 returned.
825 The PKCS #11 error codes may originate from a PKCS #11 function called
827 by the p11sak tool, or from the p11sak tool itself, like the following:
828 CKR_ARGUMENTS_BAD (0x00000007):
831 An argument, option or keyword is not valid.
832 CKR_DATA_INVALID (0x00000020):
834 The p11sak_defined_attrs.conf cannot be parsed or its syntax is in‐
835 valid.
836 CKR_MECHANISM_INVALID (0x00000070):
838 The token does not support the key generation mechanism for the speci‐
839 fied key type.
840 CKR_KEY_SIZE_RANGE (0x00000062):
842 The token does not support the key size for the specified key type.
843 CKR_HOST_MEMORY (0x00000002):
845 Allocating memory has failed.
846 CKR_FUNCTION_FAILED (0x00000006):
848 A subfunction or library call has failed.
849
851 p11sak_defined_attrs.conf(5)
8523.21.0 May 2020 P11SAK(1)