pki-key(1)

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

NAME

6       pki-key - Command-Line Interface for managing Certificate System keys.
7
8

SYNOPSIS

10       pki [CLI options] <subsystem>-key
11       pki [CLI options] <subsystem>-key-find [command options]
12       pki [CLI options] <subsystem>-key-show <Key ID> [command options]
13       pki [CLI options] <subsystem>-key-request-find [command options]
14       pki [CLI options] <subsystem>-key-request-show <Request ID> [command options]
15       pki [CLI options] <subsystem>-key-mod <Key ID> [command options]
16       pki [CLI options] <subsystem>-key-template-find [command options]
17       pki [CLI options] <subsystem>-key-template-show <Template ID> [command options]
18       pki [CLI options] <subsystem>-key-archive [command options]
19       pki [CLI options] <subsystem>-key-retrieve [command options]
20       pki [CLI options] <subsystem>-key-generate <Client Key ID> --key-algorithm <algorithm> [command options]
21       pki [CLI options] <subsystem>-key-recover [command options]
22       pki [CLI options] <subsystem>-key-request-review <Request ID> --action <action>[command options]
23
24

DESCRIPTION

26       The  pki-key commands provide command-line interfaces to manage keys on
27       the KRA.
28
29       The only valid subsystem is kra. The kra- prefix may be omitted.
30
31       pki [CLI options] <subsystem>-key
32           This command is to list available key commands.
33
34       pki [CLI options] <subsystem>-key-find [command options]
35           This command is to list keys.
36
37       pki [CLI options] <subsystem>-key-show <Key ID> [command options]
38           This command is to view the details of a key in the KRA.
39
40       pki [CLI options] <subsystem>-key-request-find [command options]
41           This command is to list key requests.
42
43       pki [CLI options] <subsystem>-key-request-show  <Request  ID>  [command
44       options]
45           This  command  is to view the details of a key request submitted to
46           the KRA.
47
48       pki [CLI options] <subsystem>-key-mod <Key ID>  --status  <status>[com‐
49       mand options]
50           This  command  is  to  modify the status of a particular key in the
51           KRA.
52
53       pki [CLI options] <subsystem>-key-template-find [command options]
54           This command is to list the templates for all types of requests  in
55           the system.
56
57       pki  [CLI options] <subsystem>-key-template-show <Template ID> [command
58       options]
59           This command is to view details of the template of a  specific  key
60           request.
61
62       pki [CLI options] <subsystem>-key-archive [command options]
63           This command is to archive a secret in the DRM.
64
65       pki [CLI options] <subsystem>-key-retrieve [command options]
66           This command is to retrieve a secret stored in the DRM.
67
68       pki  [CLI options] <subsystem>-key-generate <Client Key ID> --key-algo‐
69       rithm <algorithm> [command options]
70           This command is to generate a key in the DRM.
71
72       pki [CLI options] <subsystem>-key-recover [command options]
73           This command is to recover details of a key in the DRM.
74
75       pki [CLI options] <subsystem>-key-request-review [command options]
76           This command is to review a key request submitted ot the DRM.
77
78

OPTIONS

80       The CLI options are described in pki(1).
81
82

OPERATIONS

84       To view available key commands, type pki <subsystem>-key. To view  each
85       command's usage, type  pki <subsystem>-key-<command> --help.
86
87       All the key commands require agent authentication.
88
89
90   Viewing the keys
91       To view the keys stored in DRM:
92
93       pki <agent authentication> key-find
94
95       To view all active keys for a specific client key ID:
96
97       pki  <agent  authentication>  key-find  --clientKeyID  <Client  Key ID>
98       --status active
99
100       To view details of a specific key:
101
102       pki <agent authentication> key-show <KeyID>
103
104
105   Archiving a key
106       To archive a passphrase in the DRM:
107
108       pki <agent authentication> key-archive --clientKeyID  <Client  Key  ID>
109       --passphrase <Passphrase>
110
111       A  symmetric  key  can  be archived using the "archiveKey" request tem‐
112       plate.
113
114       To archive a secret using the request template stored in a file:
115
116       pki <agent authentication> key-archive --input <path  to  the  template
117       file>
118
119
120   Retrieving a key
121       To retrieve a key using the key ID:
122
123       pki <agent authentication> key-retrieve --keyID <Key Identifier>
124
125       To retrieve a key using a recovery request template:
126
127       pki   <agent  authentication>  key-retrieve  --input  <path_to_the_tem‐
128       plate_file>
129
130       To retrieve a key encrypted in a custom password:
131
132       pki  <agent  authentication>  key-retrieve  --keyID  <Key   Identifier>
133       --passphrase <passphrase>
134
135       The  returned  output  contains  the  secret  wrapped  in  the provided
136       passphrase, using DES3 algorithm, and the nonce used for encryption.
137
138       To store the key information to an output file, use the --output option
139       for the command.
140
141
142   Recovering a key
143       To initiate a key recovery:
144
145       pki <agent authentication> key-recover --keyID <Key Identifier>
146
147       The  request  ID  returned by this operation must be approved using the
148       key-request-review command before the actual key retrieval.
149
150       This step is performed internally by the key-retrieve command.
151
152
153   Generating a Symmetric Key
154       To generate a symmetric key using the DES3 algorithm:
155
156       pki <agent authentication> key-generate <Client Key ID> --key-algorithm
157       DES3 --usages wrap,unwrap
158
159       There  are other algorithms to generate symmetric keys such as the AES,
160       DES, DESede, RC2, RC4.
161
162       In case of using any of the AES/RC2/RC4 algorithms, the key size has to
163       be specified using the key-size option of the command.
164
165       Generation of asymmetric keys is currently not implemented.
166
167
168   Reviewing a key request
169       To approve a key request:
170
171       pki  <agent  authentication>  key-request-review  <Request ID> --action
172       approve
173
174       On successful authentication, the request with  the  given  request  ID
175       will be approved.
176
177       There  other  actions that can be performed by an agent are reject/can‐
178       cel.
179
180
181   Viewing a request template
182       To list all the key request templates:
183
184       pki <agent authentication> key-template-find
185
186       To view a key archival request template:
187
188       pki <agent authentication> key-template-show archiveKey
189
190

EXAMPLES

192       The following pki client examples show the usage of  the  above  opera‐
193       tions for a basic CA and KRA server installation.
194
195       A  basic  installation  of  CA  and  KRA servers can be done by running
196       pkispawn in interactive mode and selecting the default parameters  (see
197       the section INTERACTIVE MODE in pkispawn(8))
198
199       or  using  a  configuration  file with basic parameters(see the section
200       EXAMPLES in pkispawn(8)).
201
202       Only an agent can perform operations on the key resource. An agent cer‐
203       tificate must be used for authentication. This can be done by importing
204       an agent certificate into an NSS database and  passing  the  values  to
205       relevant options provided by the pki CLI framework.
206
207       Running  the following commands will set up the NSS database for use by
208       a pki client and import the agent's certificate into the  database  and
209       list  information( including the nickname) of the certificate stored in
210       the database.
211
212           - certutil -N -d <CERT_DB_DIR_PATH>
213
214           - pk12util -i <Agent_Cert_P12_FILE_PATH> -d <CERT_DB_DIR_PATH>
215
216           - certutil -L -d <CERT_DB_DIR_PATH>
217
218       The first command creates an NSS database. It asks to enter a  password
219       for  the database.  The second command imports the agent certificate in
220       a PKCS12 format into the database. It prompts for the passwords of  the
221       PKCS12 file and the NSS database.  The third command shows the informa‐
222       tion about the imported certificate.(including the nickname)
223
224       For demonstration purposes, the administrator certificate can  be  used
225       to  perform  agent  authentication.  In a basic installation setup, the
226       admin cert can be found at  /root/.dogtag/pki-tomcat/ca_admin_cert.p12.
227       Since  the installation can only be performed by a root user, this file
228       must be copied to a location where other  users  can  access  it,  with
229       valid permissions.
230
231       On  completion  of the setup, and, when issuing the first command using
232       the authentication parameters, a user may be  greeted  with  a  warning
233       message which indicates that an untrusted issuer was encountered.  Sim‐
234       ply reply 'Y' to import the CA certificate,  and,  presuming  that  the
235       displayed CA server URI is valid, press the carriage return.
236
237       To list all the keys and key requests stored in KRA:
238
239       pki  -d  <CERT_DB_DIR_PATH>  -c <CERT_DB_PWD> -n <Certificate_Nickname>
240       key-find
241
242       pki -d <CERT_DB_DIR_PATH> -c  <CERT_DB_PWD>  -n  <Certificate_Nickname>
243       key-request-find
244
245       To view information of a specific key or a key request stored in KRA:
246
247       pki  -d  <CERT_DB_DIR_PATH>  -c <CERT_DB_PWD> -n <Certificate_Nickname>
248       key-show <Key ID>
249
250       pki -d <CERT_DB_DIR_PATH> -c  <CERT_DB_PWD>  -n  <Certificate_Nickname>
251       key-request-show <Request ID>
252
253       Creating a request for archiving/retrieving/recovering a key
254
255       pki  -d  <CERT_DB_DIR_PATH>  -c <CERT_DB_PWD> -n <Certificate_Nickname>
256       key-archive --clientKeyID vek12345 --passphrase SampleSecret
257
258       pki -d <CERT_DB_DIR_PATH> -c  <CERT_DB_PWD>  -n  <Certificate_Nickname>
259       key-retrieve --keyID <Key ID of the archived secret>
260
261       pki  -d  <CERT_DB_DIR_PATH>  -c <CERT_DB_PWD> -n <Certificate_Nickname>
262       key-recover --keyID <Key ID of the archived secret>
263
264       Generating a symmetric key
265
266       pki -d <CERT_DB_DIR_PATH> -c  <CERT_DB_PWD>  -n  <Certificate_Nickname>
267       key-generate vek123456 --key-algorithm DES3 --usages encrypt,decrypt
268
269       Reviewing a key request
270
271       pki  -d  <CERT_DB_DIR_PATH>  -c <CERT_DB_PWD> -n <Certificate_Nickname>
272       key-request-review <Request ID> --action <approve/reject/cancel>
273
274

Using templates for creating requests (for advanced users)

276       The messages for communication between the CLI framework  and  KRA  for
277       accessing the key resource are always encrypted.
278
279       In the case of the above mentioned examples, the encryption and decryp‐
280       tion of the secrets is done internally by the Dogtag client API.
281
282       But, applications using the CLI framework to  create  various  requests
283       and also use local encryption, so the xml templates can be used to sup‐
284       ply data to the create a request.
285
286       All the templates can be listed by executing:
287
288       pki key-template-find
289
290
291   Creating a key-archival request
292       To fetch the template for key archival:
293
294       pki key-template-show archiveKey --output <output file>
295
296       This command gets the template for a key archival request and stores it
297       in an output file.
298
299       Following  is  the  description  of  the  various parameters in the key
300       archival template:
301
302           -- clientKeyID - Unique identifier for the secret.
303           -- dataType  -  Type  of  the  data  to  be  stored  which  can  be
304       passphrase/symmetricKey/asymmetricKey.
305           --  keyAlgorithm  -  Algorithm used to create a symmetric key. (Not
306       required if the dataType is passphrase)
307           -- keySize - Size used to generate the symmetric key. (Not required
308       if the dataType is passphrase)
309           -- algorithmOID - Key Algorithm object identifier
310           -- symmetricAlgorithmParams - Base64 encoded nonce data. Nonce used
311       while encrypting the secret.
312           -- wrappedPrivateData - Secret encrypted using a session key(A sym‐
313       metric key) encoded using Base64. This entity contains the secret which
314       is encrypted using a session key.
315           -- transWrappedSessionKey - The session key  used  to  encrypt  the
316       secret, wrapped using the DRM transport key, and encoded in Base64 for‐
317       mat.
318           -- pkiArchiveOptions - An object of type PKIArchiveOptions provided
319       by the NSS/JSS library to securely transport a secret encoded in Base64
320       format.
321
322       To create an archival request using the template file:
323
324       pki -d <CERT_DB_DIR_PATH> -c  <CERT_DB_PWD>  -n  <Certificate_Nickname>
325       key-archive --input <Path_to_template_file>
326
327
328   Creating a key-retrieval request
329       To fetch the template for key retrieval:
330
331       pki key-template-show retrieveKey --output <output file>
332
333       This  command  gets the template for a key retrieval request and stores
334       it in an output file.
335
336       Following is the description of  the  various  parameters  in  the  key
337       retrieval template:
338
339           -- keyID - Key identifier
340           -- requestID - Key request identifier
341           --  nonceData  - Base64 encoded string of nonce used during encryp‐
342       tion
343           -- passphrase - passphrase to encrypt the secret  with/  passphrase
344       for the PKCS12 file returned
345           -- sessionWrappedpassphrase - Base64 encoded string of - Passphrase
346       encrypted with a session key.
347           -- transWrapedSessionKey - Base64 encoded string of -  session  key
348       encrypted with KRA's transport key.
349           -- certificate - Base64 encoded certificate for recovering the key.
350
351       To create a retrieval request using the template file:
352
353       pki  -d  <CERT_DB_DIR_PATH>  -c <CERT_DB_PWD> -n <Certificate_Nickname>
354       key-retrieve --input <Path_to_template_file>
355
356
357   Creating a symmetric key generation request
358       To fetch the template for symmetric key generation:
359
360       pki key-template-show generateKey --output <output file>
361
362       This command gets the template for a symmetric key  generation  request
363       and stores it in an output file.
364
365       Following  is  the  description  of  the  various parameters in the key
366       retrieval template:
367
368           -- clientKeyID - Client specified unique key identifier
369           --  keyAlgorithm  -  Algorithm  to  be   used   to   generate   key
370       (AES/DES/DES3/DESede/RC2/RC4)
371           -- keySize - Value for the size of the key to be generated.
372           -- keyUsage - usages of the generated key
373               useful       for       Symmetric       Keys      (DES3,AES,etc)
374       (wrap,unwrap,encrypt,decrypt)
375               useful     for     Asymmetric      Keys      (RSA,      EC,etc)
376       (wrap,unwrap,encrypt,decrypt,sign,verify,sign_recover,verify_recover)
377
378       To create a key generation request using the template file:
379
380       pki  -d  <CERT_DB_DIR_PATH>  -c <CERT_DB_PWD> -n <Certificate_Nickname>
381       key-generate --input <Path_to_template_file>
382
383
384

AUTHORS

386       Ade Lee <alee@redhat.com>, Endi  Dewata  <edewata@redhat.com>,  Matthew
387       Harmsen <mharmsen@redhat.com> and Abhishek Koneru <akoneru@redhat.com>.
388
389

COPYRIGHT

391       Copyright (c) 2014 Red Hat, Inc. This is licensed under the GNU General
392       Public License, version 2 (GPLv2). A copy of this license is  available
393       at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
394
395