1P11SAK(1) openCryptoki P11SAK(1)
2
6 p11sak - generate and list token keys in an openCryptoki token reposi‐
7 tory.
8
10 p11sak command [ARGS] [OPTIONS]
11 p11sak --help|-h
13
16 p11sak can be used to generate, list and delete the token keys in an
17 openCryptoki token repository. The utility provides a flexible key
18 management tool in openCryptoki to list and generate symmetric (DES,
19 3DES, AES, AES-XTS) and asymmetric (RSA, EC, IBM Dilithium, IBM Kyber)
20 keys. This tool is especially capable of a well defined listing of
21 keys with their PKCS #11 attributes.
22
24 The p11sak tool can operate in three modes: when command generate-key
25 is specified, it operates in the mode to generate a token key in the
26 openCryptoki token repository. If command list-key is given, it lists
27 the keys specified in the arguments. If command remove-key is given,
28 it removes the keys specified in the arguments.
29 generate-key
31 Use the generate-key|gen-key|gen command and key argument to generate a
32 token key with the respective [ARGS] and [OPTIONS]. The --help|-h op‐
33 tion will show the arguments and options available.
34 list-key
36 Use the list-key|ls-key|ls command and key argument to list token keys
37 given the respective [ARGS] and [OPTIONS]. The --help|-h option will
38 show the arguments and options available.
39 remove-key
41 Use the remove-key|rm-key|rm command and key argument to delete token
42 keys given the respective [ARGS] and [OPTIONS]. The --help|-h option
43 will show the arguments and options available.
44 Generating DES/3DES keys
46 p11sak generate-key|gen-key|gen des|3des --slot SLOTID --pin PIN --la‐
47 bel LABEL --attr [PMRLSEDGVWUAXNT] --help | -h
48 Use the generate-key command with the des|3des key argument to generate
50 a DES or 3DES key. The --slot SLOTID and --pin PIN options are required
51 to set the token to SLOTID and the token PIN. The --label option allows
52 the user to set the LABEL attribute of the key and --attr [PM‐
53 RLSEDGVWUAXNT] can be used to set the binary attributes of the key (see
54 below for detailed description of the attributes).
55 Generating AES keys
57 p11sak generate-key|gen-key|gen aes 128|192|256 --slot SLOTID --pin PIN
58 --label LABEL --attr [PMRLSEDGVWUAXNT] --help | -h
59 Use the generate-key aes 128|192|256 command and key argument to gener‐
61 ate a AES key with 128, 192 or 256 bit length, respectively. The --slot
62 SLOTID and --pin PIN options are required to set the token to SLOTID
63 and the token PIN. The --label option allows the user to set the LABEL
64 attribute of the key and --attr [PMRLSEDGVWUAXNT] can be used to set
65 the binary attributes of the key (see below for detailed description of
66 the attributes).
67 Generating AES-XTS keys
69 p11sak generate-key|gen-key|gen aes-xts 128|256 --slot SLOTID --pin PIN
70 --label LABEL --attr [PMRLSEDGVWUAXNT] --help | -h
71 Use the generate-key aes-xts 128|256 command and key argument to gener‐
73 ate a AES-XTS key with 128 or 256 bit length, respectively. The --slot
74 SLOTID and --pin PIN options are required to set the token to SLOTID
75 and the token PIN. The --label option allows the user to set the LABEL
76 attribute of the key and --attr [PMRLSEDGVWUAXNT] can be used to set
77 the binary attributes of the key (see below for detailed description of
78 the attributes).
79 Generating RSA keys
81 p11sak generate-key|gen-key|gen rsa 1024|2048|4096 --slot SLOTID --pin
82 PIN --label LABEL --exponent EXP --attr [PMRLSEDGVWUAXNT] --help | -h
83 Use the generate-key rsa 1024|2048|4096 command and key argument to
85 generate a 1024, 2048 or 4096 bit RSA key, respectively. The --slot
86 SLOTID and --pin PIN options are required to set the token to SLOTID
87 and the token PIN. The --label option allows the user to set the LABEL
88 attribute of the key and --attr [PMRLSEDGVWUAXNT] can be used to set
89 the binary attributes of the key (see below for detailed description of
90 the attributes). Furthermore, the --exponent EXP options allows the
91 user to specify the exponent used for generating the RSA key. The de‐
92 fault is set to 65537 according to the PKCS #11 standard.
93 Generating EC keys
95 p11sak generate-key|gen-key|gen ec CURVE --slot SLOTID --pin PIN --la‐
96 bel LABEL --attr [PMRLSEDGVWUAXNT] --help | -h
97 Use the generate-key ec CURVE command and key argument to generate an
99 EC key, where CURVE specifies the eliptic curve used to create the EC
100 key. The following arguments can be used for respective curves:
101 prime256v1 | prime192 | secp224 | secp384r1 | secp521r1 | secp265k1 |
102 brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 | brainpoolP192t1 |
103 brainpoolP224r1 | brainpoolP224t1 | brainpoolP256r1 | brainpoolP256t1 |
104 brainpoolP320r1 | brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
105 brainpoolP512r1 | brainpoolP512t1 | curve25519 | curve448 | ed25519 |
106 ed448
107 Note: not all curves will be supported by all tokens and key generation
109 will fail when the specified CURVE is not supported. The --slot SLOTID
110 and --pin PIN options are required to set the token to SLOTID and the
111 token PIN. The --label option allows the user to set the LABEL attri‐
112 bute of the key and --attr [PMRLSEDGVWUAXNT] can be used to set the bi‐
113 nary attributes of the key (see below for detailed description of the
114 attributes).
115 Generating IBM Dilithium keys
117 p11sak generate-key|gen-key|gen ibm-dilithium VERSION --slot SLOTID
118 --pin PIN --label LABEL --attr [MRLSEDGVWUAXNT] --help | -h
119 Use the generate-key ibm-dilithium VERSION command and key argument to
121 generate an IBM Dilithium key, where VERSION specifies the version of
122 the IBM Dilithium keypair. The following arguments can be used for re‐
123 spective keys: r2_65 | r2_87 | r3_44 | r3_65 | r3_87
124 The --slot SLOTID and --pin PIN options are required to set the token
126 to SLOTID and the token PIN. The --label option allows the user to set
127 the LABEL attribute of the key and --attr [MRLSEDGVWUAXNT] can be used
128 to set the binary attributes of the key (see below for detailed de‐
129 scription of the attributes).
130 Generating IBM Kyber keys
132 p11sak generate-key|gen-key|gen ibm-kyber VERSION --slot SLOTID --pin
133 PIN --label LABEL --attr [M R L S E D G V W U A X N T] --help | -h
134 Use the generate-key ibm-kyber VERSION command and key argument to gen‐
136 erate an IBM Kyber key, where VERSION specifies the version of the IBM
137 Kyber keypair. The following arguments can be used for respective keys:
138 r2_768 | r2_1024
139 The --slot SLOTID and --pin PIN options are required to set the token
141 to SLOTID and the token PIN. The --label option allows the user to set
142 the LABEL attribute of the key and --attr [M R L S E D G V W U A X N T]
143 can be used to set the binary attributes of the key (see below for de‐
144 tailed description of the attributes).
145 Listing symmetric and asymmetric keys
147 p11sak list-key|ls-key|ls des|3des|aes|aes-xts|rsa|ec|ibm-
148 dilithium|ibm-kyber|public|private|secret|all --slot SLOTID --pin PIN
149 --label LABEL --long | -l --help | -h
150 Use the list-key | ls-key | ls command and key argument to list DES,
152 3DES, AES, AES-XTS, RSA, EC, IBM Dilithium, or IBM Kyber keys, respec‐
153 tively. Public, private, secret, or all keys can also be listed irre‐
154 spective of key type.
155 Deleting symmetric and asymmetric keys
157 p11sak remove-key|rm-key|rm des|3des|aes|aes-xts|rsa|ec|ibm-
158 dilithium|ibm-kyber --slot SLOTID --pin PIN --label LABEL --force | -f
159 --help | -h
160 Use the remove-key | rm-key | rm command and key argument to delete
162 DES, 3DES, AES, AES-XTS, RSA, EC, IBM Dilithium, or IBM Kyber keys, re‐
163 spectively. All specified cipher keys will be prompted to be deleted
164 unless a specific key with the --label LABEL argument is selected. The
165 user will be promted to confirm the deletion of the key. To suppress
166 the promt, use the --force | -f option.
167
169 des | 3des | aes | aes-xts | rsa | ec | ibm-dilithium | ibm-kyber | public
170 | private | secret | all
171 selects the respective symmetric or asymmetric key to be generated or
172 listed. The public|private|secret|all argument can only be used with
173 the list-key command to list either public, private, secret, or all
174 keys.
175 128|192|256
177 the aes argument has to be followed by either 128, 192 or 256 to set
178 the respective key bit length of the AES key.
179 128|256
181 the aes-xts argument has to be followed by either 128 or 256 to set the
182 respective key bit length of the AES-XTS key.
183 1024|2048|4096
185 the rsa argument has to be followed by either 1024, 2048 or 4096 to set
186 the respective key bit length of the RSA key.
187 prime256v1 | prime192 | secp224 | secp384r1 | secp521r1 | secp265k1 |
189 brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 | brainpoolP192t1 |
190 brainpoolP224r1 | brainpoolP224t1 | brainpoolP256r1 | brainpoolP256t1 |
191 brainpoolP320r1 | brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
192 brainpoolP512r1 | brainpoolP512t1 | curve25519 | curve448 | ed25519 |
193 ed448
194 the ec argument has to be followed by either of these CURVE to select
195 the EC curve used to generate the key.
196 r2_6|r2_87|r3_44|r3_65|r3_875
198 the ibm-dilithium argument has to be followed by either of these VER‐
199 SION to select the IBM dilithium version used to generate the key.
200 r2_768|r2_1024
202 the ibm-kyber argument has to be followed by either of these VERSION to
203 select the IBM kyber version used to generate the key.
204
206 --slot SLOTID
207 sets the token to SLOTID
208 --pin PIN
210 sets the token PIN to PIN
211 Alternatively the PKCS11_USER_PIN environment variable may be used to
213 provide the token PIN.
214 --force-pin-prompt
216 enforce p11sak to prompt for the token PIN (regardless if it has been
217 specified elsewhere)
218 --label LABEL
220 sets the key label attribute to LABEL
221 For asymmetric keys, the specified label is appended by :pub and .prv
223 for the public and private key objects. Optionally, a user can set dif‐
224 ferent labels for the public and private key objects by specifying them
225 separated by a colon (:), e.g. pub-label:priv-label. The label string
226 in front of the colon is used as label for the public key object, the
227 label string after the colon is used for the private key object. To
228 set the public and private key label the exact same, use pub-label:=.
229 The equal sign (=) means to use the same label string for the private
230 key objects as for the public key object. In case a colon character or
231 a equal sign is supposed to appear within a label string, it must be
232 escaped using a back slash (\), e.g. abc\:xyz results in abx:xyz where
233 the colon is not treated as separator character. Note that the shell
234 may interpret escape characters as well, so better quote the LABEL
235 specification.
236 --exponent EXP
238 sets the RSA exponent to EXP
239 --attr [P M R L S E D G V W U A X N T]
241 sets the binary attributes of a key.
242 Note: not all binary attributes are applicable to all keys and will be
244 omitted if not applicable.
245 The attributes are set to FALSE by default and switched to TRUE when
247 the letter that is associated with the given binary attribute is speci‐
248 fied. The following letters are associated with the respective CK_AT‐
249 TRIBUTE:
250 • P - CKA_PRIVATE
252 • M - CKA_MODIFIABLE
254 • R - CKA_DERIVE
256 • L - CKA_LOCAL
258 • S - CKA_SENSITIVE
260 • E - CKA_ENCRYPT
262 • D - CKA_DECRYPT
264 • G - CKA_SIGN
266 • V - CKA_VERIFY
268 • W - CKA_WRAP
270 • U - CKA_UNWRAP
272 • A - CKA_ALWAYS_SENSITIVE
274 • X - CKA_EXTRACTABLE
276 • N - CKA_NEVER_EXTRACTABLE
278 • * - if in p11sak_defined_attrs.conf additional attributes are de‐
280 fined.
281 CKA_TOKEN and CKA_PRIVATE are set by default to TRUE. For multiple at‐
283 tributes, combine the letters in a string without white space, e. g.
284 'MlD'. An uppercase letter means true, while an lowercase letter
285 equals false. From Example above: CKA_MODIFIABLE=true, CKA_LO‐
286 CAL=false, CKA_DECRYPT=true
287 For asymmetric keys a user can set different custom attributes for the
289 public and the private key. The separator is the symbol ":". The de‐
290 fined attributes in front of the separator are set for the public key
291 and the attributes defined after the separator are set for the private
292 key. When the separator is not in the string, the defined attribute set
293 is used for public and private key. To set a configuration for only the
294 public key, the string has to end with the separator and respectively,
295 to use a configuration for the private key only, the string has to
296 start with the separator.
297 --long | -l
299 prints the list-key output in long format. If omitted, the output is in
300 a short, tabular format.
301 --force | -f
303 to be used with the remove-key command to suppress the promt whether
304 the user wants to delete the specified keys.
305 --help | -h
307 prints help for the usage of p11sak and/or the respective command.
308
310 /usr/local/etc/opencryptoki/p11sak_defined_attrs.conf
311 In the output config file a user can define additional attributes,
312 which are not mentioned in the PKCS#11 standard. A custom filepath can
313 be set with an environment variable.
314
316 P11SAK_DEFAULT_CONF_FILE
317 A custom path for p11sak_defined_attrs.conf can be set with the envi‐
318 ronment variable P11SAK_DEFAULT_CONF_FILE. If none is set p11sak will
319 first look for the file in the user directory, followed by the standard
320 installation path.
321 PKCS11_USER_PIN
323 The token PIN can be specified via the environment variable
324 PKCS11_USER_PIN. If nothing is set and the option --pin is not speci‐
325 fied, p11sak will prompt for the token PIN interactively.
326
328 p11sak returns various error codes on fail:
329 CKR_ARGUMENTS_BAD (0x00000007):
331 The p11sak_defined_attrs.conf is not found.
332 CKR_DATA_INVALID (0x00000020):
334 The p11sak_defined_attrs.conf cannot be parsed or syntax is invalid.
335 CKR_ATTRIBUTE_TYPE_INVALID (0x00000012):
337 A given attribute type cannot be set for this key.
338
340 p11sak_defined_attrs.conf(5)
3413.20.0 May 2020 P11SAK(1)