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 This step is performed internally by the kra-key-retrieve command.
187 Generating a Symmetric Key
190 To generate a symmetric key using the DES3 algorithm:
191 $ pki <agent authentication> kra-key-generate <Client Key ID> \
194 --key-algorithm DES3 --usages wrap,unwrap
195 There are other algorithms to generate symmetric keys such as the AES,
199 DES, DESede, RC2, RC4.
200 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 Generation of asymmetric keys is currently not implemented.
207 Reviewing a key request
210 To approve a key request:
211 $ pki <agent authentication> kra-key-request-review <Request ID> --action approve
214 On successful authentication, the request with the given request ID
218 will be approved.
219 There other actions that can be performed by an agent are reject/can‐
222 cel.
223 Viewing a request template
226 To list all the key request templates:
227 $ pki <agent authentication> kra-key-template-find
230 To view a key archival request template:
234 $ pki <agent authentication> kra-key-template-show archiveKey
237
241 The following pki client examples show the usage of the above opera‐
242 tions for a basic CA and KRA server installation.
243 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 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 $ certutil -N -d <CERT_DB>
258 $ pk12util -i <Agent_Cert_P12_FILE> -d <CERT_DB>
259 $ certutil -L -d <CERT_DB>
260 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 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 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 To list all the keys and key requests stored in KRA:
286 $ 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 To view information of a specific key or a key request stored in KRA:
294 $ 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 Creating a request for archiving/retrieving/recovering a key
302 $ 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 Generating a symmetric key
314 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-generate \
317 "vek123456" --key-algorithm DES3 --usages "encrypt,decrypt"
318 Reviewing a key request
322 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-request-review <Request ID> \
325 --action <approve/reject/cancel>
326
330 The messages for communication between the CLI framework and KRA for
331 accessing the key resource are always encrypted.
332 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 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 All the templates can be listed by executing:
344 $ pki kra-key-template-find
347 Creating a kra-key-archival request
351 To fetch the template for key archival:
352 $ pki kra-key-template-show archiveKey --output <output file>
355 This command gets the template for a key archival request and stores it
359 in an output file.
360 Following is the description of the various parameters in the key
363 archival template:
364 · clientKeyID - Unique identifier for the secret.
367 · dataType - Type of the data to be stored which can be
369 passphrase/symmetricKey/asymmetricKey.
370 · keyAlgorithm - Algorithm used to create a symmetric key. (Not
372 required if the dataType is passphrase)
373 · keySize - Size used to generate the symmetric key. (Not
375 required if the dataType is passphrase)
376 · algorithmOID - Key Algorithm object identifier
378 · symmetricAlgorithmParams - Base64 encoded nonce data. Nonce
380 used while encrypting the secret.
381 · 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 · transWrappedSessionKey - The session key used to encrypt the
387 secret, wrapped using the KRA transport key, and encoded in
388 Base64 format.
389 · 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 To create an archival request using the template file:
397 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-archive \
400 --input <template_file>
401 Creating a kra-key-retrieval request
405 To fetch the template for key retrieval:
406 $ pki kra-key-template-show retrieveKey --output <output file>
409 This command gets the template for a key retrieval request and stores
413 it in an output file.
414 Following is the description of the various parameters in the key
417 retrieval template:
418 · keyID - Key identifier
421 · requestID - Key request identifier
423 · nonceData - Base64 encoded string of nonce used during encryp‐
425 tion
426 · passphrase - passphrase to encrypt the secret with/ passphrase
428 for the PKCS12 file returned
429 · sessionWrappedpassphrase - Base64 encoded string of -
431 Passphrase encrypted with a session key.
432 · transWrapedSessionKey - Base64 encoded string of - session key
434 encrypted with KRA's transport key.
435 · certificate - Base64 encoded certificate for recovering the
437 key.
438 To create a retrieval request using the template file:
442 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-retrieve \
445 --input <template_file>
446 Creating a symmetric key generation request
450 To fetch the template for symmetric key generation:
451 $ pki kra-key-template-show generateKey --output <output file>
454 This command gets the template for a symmetric key generation request
458 and stores it in an output file.
459 Following is the description of the various parameters in the key
462 retrieval template:
463 · clientKeyID - Client specified unique key identifier
466 · keyAlgorithm - Algorithm to be used to generate key
468 (AES/DES/DES3/DESede/RC2/RC4)
469 · keySize - Value for the size of the key to be generated.
471 · 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 To create a key generation request using the template file:
481 $ pki -d <CERT_DB> -c <CERT_DB_PWD> -n <Certificate_Nickname> kra-key-generate \
484 --input <template_file>
485
489 pkispawn(8), pki(1)
490
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
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.
502PKI May 5, 2014 pki-kra-key(1)