1pki-kra-key(1) PKI KRA Key Management Commands pki-kra-key(1)
2
6 pki-key - Command-line interface for managing keys in PKI KRA.
7
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
28 The pki kra-key commands provide command-line interfaces to manage keys
29 on the KRA.
30 pki [CLI-options] kra-key
33 This command is to list available key commands.
34 pki [CLI-options] kra-key-find [command-options]
37 This command is to list keys.
38 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 pki [CLI-options] kra-key-request-find [command-options]
45 This command is to list key requests.
46 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 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 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 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 pki [CLI-options] kra-key-archive [command-options]
69 This command is to archive a secret in the KRA.
70 pki [CLI-options] kra-key-retrieve [command-options]
73 This command is to retrieve a secret stored in the KRA.
74 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 pki [CLI-options] kra-key-recover [command-options]
82 This command is to recover details of a key in the KRA.
83 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
91 The CLI options are described in pki(1).
92
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 All the key commands require agent authentication.
100 Viewing the keys
103 To view the keys stored in KRA:
104 $ pki <agent authentication> kra-key-find
107 To view all active keys for a specific client key ID:
111 $ pki <agent authentication> kra-key-find --clientKeyID <Client Key ID> --status active
114 To view details of a specific key:
118 $ pki <agent authentication> kra-key-show <KeyID>
121 Archiving a key
125 To archive a passphrase in the KRA:
126 $ pki <agent authentication> kra-key-archive --clientKeyID <Client Key ID> \
129 --passphrase <Passphrase>
130 A symmetric key can be archived using the "archiveKey" request tem‐
134 plate.
135 To archive a secret using the request template stored in a file:
138 $ pki <agent authentication> kra-key-archive --input <path to the template file>
141 Retrieving a key
145 To retrieve a key using the key ID:
146 $ pki <agent authentication> kra-key-retrieve --keyID <Key Identifier>
149 To retrieve a key using a recovery request template:
153 $ pki <agent authentication> kra-key-retrieve --input <template_file>
156 To retrieve a key encrypted in a custom password:
160 $ pki <agent authentication> kra-key-retrieve --keyID <Key Identifier> --passphrase <passphrase>
163 The returned output contains the secret wrapped in the provided
167 passphrase, using DES3 algorithm, and the nonce used for encryption.
168 To store the key information to an output file, use the --output option
171 for the command.
172 Recovering a key
175 To initiate a key recovery:
176 $ pki <agent authentication> kra-key-recover --keyID <Key Identifier>
179 The request ID returned by this operation must be approved using the
183 key-request-review command before the actual key retrieval.
184 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 Generating a Symmetric Key
192 To generate a symmetric key using the DES3 algorithm:
193 $ pki <agent authentication> kra-key-generate <Client Key ID> \
196 --key-algorithm DES3 --usages wrap,unwrap
197 There are other algorithms to generate symmetric keys such as the AES,
201 DES, DESede, RC2, RC4.
202 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 Generation of asymmetric keys is currently not implemented.
209 Reviewing a key request
212 To approve a key request:
213 $ pki <agent authentication> kra-key-request-review <Request ID> --action approve
216 On successful authentication, the request with the given request ID
220 will be approved.
221 There other actions that can be performed by an agent are reject/can‐
224 cel.
225 Viewing a request template
228 To list all the key request templates:
229 $ pki <agent authentication> kra-key-template-find
232 To view a key archival request template:
236 $ pki <agent authentication> kra-key-template-show archiveKey
239
243 The following pki client examples show the usage of the above opera‐
244 tions for a basic CA and KRA server installation.
245 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 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 $ certutil -N -d <CERT_DB>
260 $ pk12util -i <Agent_Cert_P12_FILE> -d <CERT_DB>
261 $ certutil -L -d <CERT_DB>
262 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 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 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 To list all the keys and key requests stored in KRA:
288 $ 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 To view information of a specific key or a key request stored in KRA:
296 $ 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 Creating a request for archiving/retrieving/recovering a key
304 $ 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 Generating a symmetric key
316 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-generate \
319 "vek123456" --key-algorithm DES3 --usages "encrypt,decrypt"
320 Reviewing a key request
324 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-request-review <Request ID> \
327 --action <approve/reject/cancel>
328
332 The messages for communication between the CLI framework and KRA for
333 accessing the key resource are always encrypted.
334 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 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 All the templates can be listed by executing:
346 $ pki kra-key-template-find
349 Creating a kra-key-archival request
353 To fetch the template for key archival:
354 $ pki kra-key-template-show archiveKey --output <output file>
357 This command gets the template for a key archival request and stores it
361 in an output file.
362 Following is the description of the various parameters in the key
365 archival template:
366 · clientKeyID - Unique identifier for the secret.
369 · dataType - Type of the data to be stored which can be
371 passphrase/symmetricKey/asymmetricKey.
372 · keyAlgorithm - Algorithm used to create a symmetric key. (Not
374 required if the dataType is passphrase)
375 · keySize - Size used to generate the symmetric key. (Not
377 required if the dataType is passphrase)
378 · algorithmOID - Key Algorithm object identifier
380 · symmetricAlgorithmParams - Base64 encoded nonce data. Nonce
382 used while encrypting the secret.
383 · 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 · transWrappedSessionKey - The session key used to encrypt the
389 secret, wrapped using the KRA transport key, and encoded in
390 Base64 format.
391 · 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 To create an archival request using the template file:
399 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-archive \
402 --input <template_file>
403 Creating a kra-key-retrieval request
407 To fetch the template for key retrieval:
408 $ pki kra-key-template-show retrieveKey --output <output file>
411 This command gets the template for a key retrieval request and stores
415 it in an output file.
416 Following is the description of the various parameters in the key
419 retrieval template:
420 · keyID - Key identifier
423 · requestID - Key request identifier
425 · nonceData - Base64 encoded string of nonce used during encryp‐
427 tion (unused for PKCS12 key recovery)
428 · passphrase - passphrase to encrypt the secret with/ passphrase
430 for the PKCS12 file returned
431 · sessionWrappedpassphrase - Base64 encoded string of -
433 Passphrase encrypted with a session key. (unused for PKCS12
434 key recovery)
435 · transWrapedSessionKey - Base64 encoded string of - session key
437 encrypted with KRA's transport key. (unused for PKCS12 key
438 recovery)
439 · certificate - Base64 encoded certificate for recovering the
441 key.
442 To retrieve (recover) keys using the template file (note: key recovery
446 into PKCS12 can only use a template file):
447 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-retrieve \
450 --input <template_file>
451 Creating a symmetric key generation request
455 To fetch the template for symmetric key generation:
456 $ pki kra-key-template-show generateKey --output <output file>
459 This command gets the template for a symmetric key generation request
463 and stores it in an output file.
464 Following is the description of the various parameters in the key
467 retrieval template:
468 · clientKeyID - Client specified unique key identifier
471 · keyAlgorithm - Algorithm to be used to generate key
473 (AES/DES/DES3/DESede/RC2/RC4)
474 · keySize - Value for the size of the key to be generated.
476 · 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 To create a key generation request using the template file:
486 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-generate \
489 --input <template_file>
490
494 pkispawn(8), pki(1)
495
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
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.
507PKI May 5, 2014 pki-kra-key(1)