p11sak(1)

1P11SAK(1)                        openCryptoki                        P11SAK(1)
2
3
4

NAME

6       p11sak  - generate and list token keys in an openCryptoki token reposi‐
7       tory.
8

SYNOPSIS

10       p11sak command [ARGS] [OPTIONS]
11
12       p11sak --help|-h
13
14

DESCRIPTION

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) and asymetric (RSA, EC) keys.  This tool is especially capa‐
20       ble of a well defined listing of keys with their PKCS #11 attributes.
21

COMMANDS

23       The p11sak tool can operate in three modes: when  command  generate-key
24       is  specified,  it  operates in the mode to generate a token key in the
25       openCryptoki token repository.  If command list-key is given, it  lists
26       the  keys  specified in the arguments.  If command remove-key is given,
27       it removes the keys specified in the arguments.
28
29   generate-key
30       Use the generate-key|gen-key|gen command and key argument to generate a
31       token  key with the respective [ARGS] and [OPTIONS].  The --help|-h op‐
32       tion will show the arguments and options available.
33
34   list-key
35       Use the list-key|ls-key|ls command and key argument to list token  keys
36       given  the  respective [ARGS] and [OPTIONS].  The --help|-h option will
37       show the arguments and options available.
38
39   remove-key
40       Use the remove-key|rm-key|rm command and key argument to  delete  token
41       keys  given  the respective [ARGS] and [OPTIONS].  The --help|-h option
42       will show the arguments and options available.
43
44   Generating DES/3DES keys
45       p11sak generate-key|gen-key|gen des|3des --slot SLOTID --pin PIN  --la‐
46       bel LABEL --attr [PMRLSEDGVWUAXNT] --help | -h
47
48       Use the generate-key command with the des|3des key argument to generate
49       a DES or 3DES key. The --slot SLOTID and --pin PIN options are required
50       to set the token to SLOTID and the token PIN. The --label option allows
51       the user to set  the  LABEL  attribute  of  the  key  and  --attr  [PM‐
52       RLSEDGVWUAXNT] can be used to set the binary attributes of the key (see
53       below for detailed description of the attributes).
54
55   Generating AES keys
56       p11sak generate-key|gen-key|gen aes 128|192|256 --slot SLOTID --pin PIN
57       --label LABEL --attr [PMRLSEDGVWUAXNT] --help | -h
58
59       Use the generate-key aes 128|192|256 command and key argument to gener‐
60       ate a AES key with 128, 192 or 256 bit length, respectively. The --slot
61       SLOTID  and  --pin  PIN options are required to set the token to SLOTID
62       and the token PIN. The --label option allows the user to set the  LABEL
63       attribute  of  the  key and --attr [PMRLSEDGVWUAXNT] can be used to set
64       the binary attributes of the key (see below for detailed description of
65       the attributes).
66
67   Generating RSA keys
68       p11sak  generate-key|gen-key|gen rsa 1024|2048|4096 --slot SLOTID --pin
69       PIN --label LABEL --exponent EXP --attr [PMRLSEDGVWUAXNT] --help | -h
70
71       Use the generate-key rsa 1024|2048|4096 command  and  key  argument  to
72       generate  a  1024,  2048  or 4096 bit RSA key, respectively. The --slot
73       SLOTID and --pin PIN options are required to set the  token  to  SLOTID
74       and  the token PIN. The --label option allows the user to set the LABEL
75       attribute of the key and --attr [PMRLSEDGVWUAXNT] can be  used  to  set
76       the binary attributes of the key (see below for detailed description of
77       the attributes). Furthermore, the --exponent  EXP  options  allows  the
78       user  to  specify the exponent used for generating the RSA key. The de‐
79       fault is set to 65537 according to the PKCS #11 standard.
80
81   Generating EC keys
82       p11sak generate-key|gen-key|gen ec CURVE --slot SLOTID --pin PIN  --la‐
83       bel LABEL --attr [PMRLSEDGVWUAXNT] --help | -h
84
85       Use  the  generate-key ec CURVE command and key argument to generate an
86       EC key, where CURVE specifies the eliptic curve used to create  the  EC
87       key.  The  following  arguments  can  be  used  for  respective curves:
88       prime256v1 | prime192 | secp224 | secp384r1 | secp521r1 |  secp265k1  |
89       brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 | brainpoolP192t1 |
90       brainpoolP224r1 | brainpoolP224t1 | brainpoolP256r1 | brainpoolP256t1 |
91       brainpoolP320r1 | brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
92       brainpoolP512r1 | brainpoolP512t1
93
94       Note: not all curves will be supported by all tokens and key generation
95       will  fail when the specified CURVE is not supported. The --slot SLOTID
96       and --pin PIN options are required to set the token to SLOTID  and  the
97       token  PIN.  The --label option allows the user to set the LABEL attri‐
98       bute of the key and --attr [PMRLSEDGVWUAXNT] can be used to set the bi‐
99       nary  attributes  of the key (see below for detailed description of the
100       attributes).
101
102   Listing symmetric and asymmetric keys
103       p11sak list-key|ls-key|ls des|3des|aes|rsa|ec|public|private|secret|all
104       --slot SLOTID --pin PIN --long | -l --help | -h
105
106       Use  the  list-key  | ls-key | ls command and key argument to list DES,
107       3DES, AES, RSA or EC keys, respectively. Public,  private,  secret,  or
108       all keys can also be listed irrespective of key type.
109
110   Deleting symmetric and asymmetric keys
111       p11sak remove-key|rm-key|rm des|3des|aes|rsa|ec --slot SLOTID --pin PIN
112       --label LABEL --force | -f --help | -h
113
114       Use the remove-key | rm-key | rm command and  key  argument  to  delete
115       DES,  3DES,  AES,  RSA,  or EC keys, respectively. All specified cipher
116       keys will be promted to be deleted unless a specific key with the --la‐
117       bel LABEL argument is selected. The user will be promted to confirm the
118       deletion of the key. To suppress the promt, use the --force  |  -f  op‐
119       tion.
120

ARGS

122   des | 3des | aes | rsa | ec | public | private | secret | all
123       selects  the  respective  symmetric or asymetric key to be generated or
124       listed. The public|private|secret|all argument can only  be  used  with
125       the  list-key  command  to  list either public, private, secret, or all
126       keys.
127
128   128|192|256
129       the aes argument has to be followed by either 128, 192 or  256  to  set
130       the respective key bit length of the AES key.
131
132   1024|2048|4096
133       the rsa argument has to be followed by either 1024, 2048 or 4096 to set
134       the respective key bit length of the RSA key.
135
136   prime256v1 | prime192 | secp224 |  secp384r1  |  secp521r1  |  secp265k1  |
137       brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 | brainpoolP192t1 |
138       brainpoolP224r1 | brainpoolP224t1 | brainpoolP256r1 | brainpoolP256t1 |
139       brainpoolP320r1 | brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
140       brainpoolP512r1 | brainpoolP512t1
141       the ec argument has to be followed by either of these CURVE  to  select
142       the EC curve used to generate the key.
143

OPTIONS

145   --slot SLOTID
146       sets the token to SLOTID
147
148   --pin PIN
149       sets the token PIN to PIN
150
151   --label LABEL
152       sets the key label attribute to LABEL
153
154   --exponent EXP
155       sets the RSA exponent to EXP
156
157   --attr [P M R L S E D G V W U A X N T]
158       sets the binary attributes of a key.
159
160       Note:  not all binary attributes are applicable to all keys and will be
161       omitted if not applicable.
162
163       The attributes are set to FALSE by default and switched  to  TRUE  when
164       the letter that is associated with the given binary attribute is speci‐
165       fied. The following letters are associated with the  respective  CK_AT‐
166       TRIBUTE:
167
168       • P - CKA_PRIVATE
169
170       • M - CKA_MODIFIABLE
171
172       • R - CKA_DERIVE
173
174       • L - CKA_LOCAL
175
176       • S - CKA_SENSITIVE
177
178       • E - CKA_ENCRYPT
179
180       • D - CKA_DECRYPT
181
182       • G - CKA_SIGN
183
184       • V - CKA_VERIFY
185
186       • W - CKA_WRAP
187
188       • U - CKA_UNWRAP
189
190       • A - CKA_ALWAYS_SENSITIVE
191
192       • X - CKA_EXTRACTABLE
193
194       • N - CKA_NEVER_EXTRACTABLE
195
196       • *  -  if  in  p11sak_defined_attrs.conf additional attributes are de‐
197         fined.
198
199       CKA_TOKEN and CKA_PRIVATE are set by default to TRUE.  For multiple at‐
200       tributes,  combine  the  letters in a string without white space, e. g.
201       'MlD'.  An uppercase letter  means  true,  while  an  lowercase  letter
202       equals   false.    From  Example  above:  CKA_MODIFIABLE=true,  CKA_LO‐
203       CAL=false, CKA_DECRYPT=true
204
205       For asymmetric keys a user can set different custom attributes for  the
206       public  and  the private key.  The separator is the symbol ":". The de‐
207       fined attributes in front of the separator are set for the  public  key
208       and  the attributes defined after the separator are set for the private
209       key. When the separator is not in the string, the defined attribute set
210       is used for public and private key. To set a configuration for only the
211       public key, the string has to end with the separator and  respectively,
212       to  use  a  configuration  for  the private key only, the string has to
213       start with the separator.
214
215   --long | -l
216       prints the list-key output in long format. If omitted, the output is in
217       a short, tabular format.
218
219   --force | -f
220       to  be  used  with the remove-key command to suppress the promt whether
221       the user wants to delete the specified keys.
222
223   --help | -h
224       prints help for the usage of p11sak and/or the respective command.
225

FILES

227   /usr/local/etc/opencryptoki/p11sak_defined_attrs.conf
228       In the output config file a  user  can  define  additional  attributes,
229       which  are not mentioned in the PKCS#11 standard. A custom filepath can
230       be set with an environment variable.
231

ENVIRONMENT VARIABLES

233   P11SAK_DEFAULT_CONF_FILE
234       A custom path for p11sak_defined_attrs.conf can be set with  the  envi‐
235       ronment  variable  P11SAK_DEFAULT_CONF_FILE. If none is set p11sak will
236       first look for the file in the user directory, followed by the standard
237       installation path.
238

EXIT STATUS

240       p11sak returns various error codes on fail:
241
242   CKR_ARGUMENTS_BAD (0x00000007):
243       The p11sak_defined_attrs.conf is not found.
244
245   CKR_DATA_INVALID (0x00000020):
246       The p11sak_defined_attrs.conf cannot be parsed or syntax is invalid.
247
248   CKR_ATTRIBUTE_TYPE_INVALID (0x00000012):
249       A given attribute type cannot be set for this key.
250