1pki-kra-key(1)          PKI KRA Key Management Commands         pki-kra-key(1)
2
3
4

NAME

6       pki-key - Command-line interface for managing keys in PKI KRA.
7
8

SYNOPSIS

10       pki [CLI-options] kra-key
11       pki [CLI-options] kra-key-find [command-options]
12       pki [CLI-options] kra-key-show key-ID [command-options]
13       pki [CLI-options] kra-key-request-find [command-options]
14       pki [CLI-options] kra-key-request-show request-ID [command-options]
15       pki [CLI-options] kra-key-mod key-ID --status status [command-options]
16       pki [CLI-options] kra-key-template-find [command-options]
17       pki [CLI-options] kra-key-template-show template-ID [command-options]
18       pki [CLI-options] kra-key-archive [command-options]
19       pki [CLI-options] kra-key-retrieve [command-options]
20       pki  [CLI-options] kra-key-generate client-key-ID --key-algorithm algo‐
21       rithm [command-options]
22       pki [CLI-options] kra-key-recover [command-options]
23       pki [CLI-options]  kra-key-request-review  request-ID  --action  action
24       [command-options]
25
26

DESCRIPTION

28       The pki kra-key commands provide command-line interfaces to manage keys
29       on the KRA.
30
31
32       pki [CLI-options] kra-key
33           This command is to list available key commands.
34
35
36       pki [CLI-options] kra-key-find [command-options]
37           This command is to list keys.
38
39
40       pki [CLI-options] kra-key-show key-ID [command-options]
41           This command is to view the details of a key in the KRA.
42
43
44       pki [CLI-options] kra-key-request-find [command-options]
45           This command is to list key requests.
46
47
48       pki [CLI-options] kra-key-request-show request-ID [command-options]
49           This command is to view the details of a key request  submitted  to
50       the KRA.
51
52
53       pki [CLI-options] kra-key-mod key-ID --status status [command-options]
54           This  command  is  to  modify the status of a particular key in the
55       KRA.
56
57
58       pki [CLI-options] kra-key-template-find [command-options]
59           This command is to list the templates for all types of requests  in
60       the system.
61
62
63       pki [CLI-options] kra-key-template-show template-ID [command-options]
64           This  command  is to view details of the template of a specific key
65       request.
66
67
68       pki [CLI-options] kra-key-archive [command-options]
69           This command is to archive a secret in the KRA.
70
71
72       pki [CLI-options] kra-key-retrieve [command-options]
73           This command is to retrieve a secret stored in the KRA.
74
75
76       pki [CLI-options] kra-key-generate client-key-ID --key-algorithm  algo‐
77       rithm [command-options]
78           This command is to generate a key in the KRA.
79
80
81       pki [CLI-options] kra-key-recover [command-options]
82           This command is to recover details of a key in the KRA.
83
84
85       pki   [CLI-options]   kra-key-request-review   --action   action  [com‐
86       mand-options]
87           This command is to review a key request submitted ot the KRA.
88
89

OPTIONS

91       The CLI options are described in pki(1).
92
93

OPERATIONS

95       To view available key commands, type pki kra-key.  To  view  each  com‐
96       mand's usage, type pki kra-key-lt;commandgt; --help.
97
98
99       All the key commands require agent authentication.
100
101
102   Viewing the keys
103       To view the keys stored in KRA:
104
105
106              $ pki <agent authentication> kra-key-find
107
108
109
110       To view all active keys for a specific client key ID:
111
112
113              $ pki <agent authentication> kra-key-find --clientKeyID <Client Key ID> --status active
114
115
116
117       To view details of a specific key:
118
119
120              $ pki <agent authentication> kra-key-show <KeyID>
121
122
123
124   Archiving a key
125       To archive a passphrase in the KRA:
126
127
128              $ pki <agent authentication> kra-key-archive --clientKeyID <Client Key ID> \
129                  --passphrase <Passphrase>
130
131
132
133       A  symmetric  key  can  be archived using the "archiveKey" request tem‐
134       plate.
135
136
137       To archive a secret using the request template stored in a file:
138
139
140              $ pki <agent authentication> kra-key-archive --input <path to the template file>
141
142
143
144   Retrieving a key
145       To retrieve a key using the key ID:
146
147
148              $ pki <agent authentication> kra-key-retrieve --keyID <Key Identifier>
149
150
151
152       To retrieve a key using a recovery request template:
153
154
155              $ pki <agent authentication> kra-key-retrieve --input <template_file>
156
157
158
159       To retrieve a key encrypted in a custom password:
160
161
162              $ pki <agent authentication> kra-key-retrieve --keyID <Key Identifier> --passphrase <passphrase>
163
164
165
166       The returned  output  contains  the  secret  wrapped  in  the  provided
167       passphrase, using DES3 algorithm, and the nonce used for encryption.
168
169
170       To store the key information to an output file, use the --output option
171       for the command.
172
173
174   Recovering a key
175       To initiate a key recovery:
176
177
178              $ pki <agent authentication> kra-key-recover --keyID <Key Identifier>
179
180
181
182       The request ID returned by this operation must be  approved  using  the
183       key-request-review command before the actual key retrieval.
184
185
186       This step is performed internally by the kra-key-retrieve command.
187
188
189   Generating a Symmetric Key
190       To generate a symmetric key using the DES3 algorithm:
191
192
193              $ pki <agent authentication> kra-key-generate <Client Key ID> \
194                  --key-algorithm DES3 --usages wrap,unwrap
195
196
197
198       There  are other algorithms to generate symmetric keys such as the AES,
199       DES, DESede, RC2, RC4.
200
201
202       In case of using any of the AES/RC2/RC4 algorithms, the key size has to
203       be specified using the kra-key-size option of the command.
204
205
206       Generation of asymmetric keys is currently not implemented.
207
208
209   Reviewing a key request
210       To approve a key request:
211
212
213              $ pki <agent authentication> kra-key-request-review <Request ID> --action approve
214
215
216
217       On  successful  authentication,  the  request with the given request ID
218       will be approved.
219
220
221       There other actions that can be performed by an agent  are  reject/can‐
222       cel.
223
224
225   Viewing a request template
226       To list all the key request templates:
227
228
229              $ pki <agent authentication> kra-key-template-find
230
231
232
233       To view a key archival request template:
234
235
236              $ pki <agent authentication> kra-key-template-show archiveKey
237
238
239

EXAMPLES

241       The  following  pki  client examples show the usage of the above opera‐
242       tions for a basic CA and KRA server installation.
243
244
245       Only an agent can perform operations on the key resource. An agent cer‐
246       tificate  must be used for authentication.  This can be done by import‐
247       ing an agent certificate into an NSS database and passing the values to
248       relevant options provided by the pki CLI framework.
249
250
251       Running  the following commands will set up the NSS database for use by
252       a pki client and import the agent's certificate into the  database  and
253       list  information( including the nickname) of the certificate stored in
254       the database.
255
256
257              $ certutil -N -d <CERT_DB>
258              $ pk12util -i <Agent_Cert_P12_FILE> -d <CERT_DB>
259              $ certutil -L -d <CERT_DB>
260
261
262
263       The first command creates an NSS database. It asks to enter a  password
264       for  the database.  The second command imports the agent certificate in
265       a PKCS12 format into the database.  It prompts for the passwords of the
266       PKCS12 file and the NSS database.  The third command shows the informa‐
267       tion about the imported certificate.(including the nickname)
268
269
270       For demonstration purposes, the administrator certificate can  be  used
271       to  perform  agent  authentication.  In a basic installation setup, the
272       admin cert can be found at  /root/.dogtag/pki-tomcat/ca_admin_cert.p12.
273       Since  the installation can only be performed by a root user, this file
274       must be copied to a location where other  users  can  access  it,  with
275       valid permissions.
276
277
278       On  completion  of the setup, and, when issuing the first command using
279       the authentication parameters, a user may be  greeted  with  a  warning
280       message which indicates that an untrusted issuer was encountered.  Sim‐
281       ply reply 'Y' to import the CA certificate,  and,  presuming  that  the
282       displayed CA server URL is valid, press the carriage return.
283
284
285       To list all the keys and key requests stored in KRA:
286
287
288              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-find
289              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-request-find
290
291
292
293       To view information of a specific key or a key request stored in KRA:
294
295
296              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-show *key-ID*
297              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-request-show <Request ID>
298
299
300
301       Creating a request for archiving/retrieving/recovering a key
302
303
304              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-archive \
305                  --clientKeyID "vek12345" --passphrase "SampleSecret"
306              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-retrieve \
307                  --keyID <Key ID of the archived secret>
308              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-recover \
309                  --keyID <Key ID of the archived secret>
310
311
312
313       Generating a symmetric key
314
315
316              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-generate \
317                  "vek123456" --key-algorithm DES3 --usages "encrypt,decrypt"
318
319
320
321       Reviewing a key request
322
323
324              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-request-review <Request ID> \
325                  --action <approve/reject/cancel>
326
327
328

Using templates for creating requests (for advanced users)

330       The  messages  for  communication between the CLI framework and KRA for
331       accessing the key resource are always encrypted.
332
333
334       In the case of the above mentioned examples, the encryption and decryp‐
335       tion of the secrets is done internally by the PKI client API.
336
337
338       But,  applications  using  the CLI framework to create various requests
339       and also use local encryption, so the xml templates can be used to sup‐
340       ply data to the create a request.
341
342
343       All the templates can be listed by executing:
344
345
346              $ pki kra-key-template-find
347
348
349
350   Creating a kra-key-archival request
351       To fetch the template for key archival:
352
353
354              $ pki kra-key-template-show archiveKey --output <output file>
355
356
357
358       This command gets the template for a key archival request and stores it
359       in an output file.
360
361
362       Following is the description of  the  various  parameters  in  the  key
363       archival template:
364
365
366              · clientKeyID - Unique identifier for the secret.
367
368              · dataType  -  Type  of  the  data  to  be  stored  which can be
369                passphrase/symmetricKey/asymmetricKey.
370
371              · keyAlgorithm - Algorithm used to create a symmetric key.  (Not
372                required if the dataType is passphrase)
373
374              · keySize  -  Size  used  to  generate  the  symmetric key. (Not
375                required if the dataType is passphrase)
376
377              · algorithmOID - Key Algorithm object identifier
378
379              · symmetricAlgorithmParams - Base64 encoded  nonce  data.  Nonce
380                used while encrypting the secret.
381
382              · wrappedPrivateData  -  Secret  encrypted using a session key(A
383                symmetric key) encoded using Base64.  This entity contains the
384                secret which is encrypted using a session key.
385
386              · transWrappedSessionKey  -  The session key used to encrypt the
387                secret, wrapped using the KRA transport key,  and  encoded  in
388                Base64 format.
389
390              · pkiArchiveOptions  -  An object of type PKIArchiveOptions pro‐
391                vided by the NSS/JSS library to securely  transport  a  secret
392                encoded in Base64 format.
393
394
395
396       To create an archival request using the template file:
397
398
399              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-archive \
400                  --input <template_file>
401
402
403
404   Creating a kra-key-retrieval request
405       To fetch the template for key retrieval:
406
407
408              $ pki kra-key-template-show retrieveKey --output <output file>
409
410
411
412       This  command  gets the template for a key retrieval request and stores
413       it in an output file.
414
415
416       Following is the description of  the  various  parameters  in  the  key
417       retrieval template:
418
419
420              · keyID - Key identifier
421
422              · requestID - Key request identifier
423
424              · nonceData - Base64 encoded string of nonce used during encryp‐
425                tion
426
427              · passphrase - passphrase to encrypt the secret with/ passphrase
428                for the PKCS12 file returned
429
430              · sessionWrappedpassphrase   -   Base64   encoded  string  of  -
431                Passphrase encrypted with a session key.
432
433              · transWrapedSessionKey - Base64 encoded string of - session key
434                encrypted with KRA's transport key.
435
436              · certificate  -  Base64  encoded certificate for recovering the
437                key.
438
439
440
441       To create a retrieval request using the template file:
442
443
444              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-retrieve \
445                  --input <template_file>
446
447
448
449   Creating a symmetric key generation request
450       To fetch the template for symmetric key generation:
451
452
453              $ pki kra-key-template-show generateKey --output <output file>
454
455
456
457       This command gets the template for a symmetric key  generation  request
458       and stores it in an output file.
459
460
461       Following  is  the  description  of  the  various parameters in the key
462       retrieval template:
463
464
465              · clientKeyID - Client specified unique key identifier
466
467              · keyAlgorithm  -  Algorithm  to  be  used   to   generate   key
468                (AES/DES/DES3/DESede/RC2/RC4)
469
470              · keySize - Value for the size of the key to be generated.
471
472              · keyUsage  - usages of the generated key.  Useful for Symmetric
473                Keys (DES3,AES,etc) (wrap,unwrap,encrypt,decrypt).  Useful for
474                Asymmetric            Keys            (RSA,            EC,etc)
475                (wrap,unwrap,encrypt,decrypt,sign,verify,sign_recover,ver‐
476                ify_recover).
477
478
479
480       To create a key generation request using the template file:
481
482
483              $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-generate \
484                  --input <template_file>
485
486
487

SEE ALSO

489       pkispawn(8), pki(1)
490
491

AUTHORS

493       Ade Lee lt;alee@redhat.comgt;, Endi S. Dewata lt;edewata@redhat.comgt;,
494       Matthew  Harmsen   lt;mharmsen@redhat.comgt;,   and   Abhishek   Koneru
495       lt;akoneru@redhat.comgt;.
496
497
499       Copyright  (c)  2014 Red Hat, Inc.  This is licensed under the GNU Gen‐
500       eral Public License, version 2 (GPLv2).  A  copy  of  this  license  is
501       available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
502
503
504
505PKI                               May 5, 2014                   pki-kra-key(1)
Impressum