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       To  actually  recover (retrieve) the PKCS12 of the private key, use the
187       "recovery request template" method listed  above  under  "Retrieving  a
188       key"
189
190
191   Generating a Symmetric Key
192       To generate a symmetric key using the DES3 algorithm:
193
194
195              $ pki <agent authentication> kra-key-generate <Client Key ID> \
196                  --key-algorithm DES3 --usages wrap,unwrap
197
198
199
200       There  are other algorithms to generate symmetric keys such as the AES,
201       DES, DESede, RC2, RC4.
202
203
204       In case of using any of the AES/RC2/RC4 algorithms, the key size has to
205       be specified using the kra-key-size option of the command.
206
207
208       Generation of asymmetric keys is currently not implemented.
209
210
211   Reviewing a key request
212       To approve a key request:
213
214
215              $ pki <agent authentication> kra-key-request-review <Request ID> --action approve
216
217
218
219       On  successful  authentication,  the  request with the given request ID
220       will be approved.
221
222
223       There other actions that can be performed by an agent  are  reject/can‐
224       cel.
225
226
227   Viewing a request template
228       To list all the key request templates:
229
230
231              $ pki <agent authentication> kra-key-template-find
232
233
234
235       To view a key archival request template:
236
237
238              $ pki <agent authentication> kra-key-template-show archiveKey
239
240
241

EXAMPLES

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

Using templates for creating requests (for advanced users)

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

SEE ALSO

494       pkispawn(8), pki(1)
495
496

AUTHORS

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