1pki(1) pki CLI pki(1)
2
3
4
6 pki - Command-Line Interface for accessing PKI services.
7
8
10 pki [CLI-options] command [command-arguments]
11
12
14 The pki command provides a command-line interface allowing clients to
15 access various services on the PKI server. These services include cer‐
16 tificates, groups, keys, security domains, and users.
17
18
20 -c NSS-database-password
21 Specifies the NSS database password (mutually exclusive to the -C
22 option).
23
24
25 -C NSS-database-password-file
26 Specifies the file which contains the NSS database password (mutu‐
27 ally exclusive to the -c option).
28
29
30 -d NSS-database-location
31 Specifies the NSS database location (default: #8764;/.dog‐
32 tag/nssdb).
33
34
35 -h hostname
36 Specifies the hostname (default: hostname of the local machine).
37
38
39 --help
40 Prints additional help information.
41
42
43 --ignore-cert-status list
44 Comma-separated list of ignored certificate validity statuses.
45 Valid values are:
46
47
48 · BAD_CERT_DOMAIN
49
50 · BAD_KEY
51
52 · BAD_SIGNATURE
53
54 · CA_CERT_INVALID
55
56 · CERT_BAD_ACCESS_LOCATION
57
58 · CERT_NOT_IN_NAME_SPACE
59
60 · CERT_STATUS_SERVER_ERROR
61
62 · EXPIRED_CERTIFICATE
63
64 · EXPIRED_ISSUER_CERTIFICATE
65
66 · INADEQUATE_CERT_TYPE
67
68 · INADEQUATE_KEY_USAGE
69
70 · INVALID_TIME
71
72 · OCSP_BAD_HTTP_RESPONSE
73
74 · OCSP_FUTURE_RESPONSE
75
76 · OCSP_MALFORMED_REQUEST
77
78 · OCSP_MALFORMED_RESPONSE
79
80 · OCSP_NO_DEFAULT_RESPONDER
81
82 · OCSP_NOT_ENABLED
83
84 · OCSP_OLD_RESPONSE
85
86 · OCSP_REQUEST_NEEDS_SIG
87
88 · OCSP_SERVER_ERROR
89
90 · OCSP_TRY_SERVER_LATER
91
92 · OCSP_UNAUTHORIZED_REQUEST
93
94 · OCSP_UNKNOWN_CERT
95
96 · OCSP_UNKNOWN_RESPONSE_STATUS
97
98 · OCSP_UNKNOWN_RESPONSE_TYPE
99
100 · OCSP_UNAUTHORIZED_RESPONSE
101
102 · PATH_LEN_CONSTRAINT_INVALID
103
104 · REVOKED_CERTIFICATE
105
106 · SEC_ERROR_CRL_BAD_SIGNATURE
107
108 · SEC_ERROR_CRL_EXPIRED
109
110 · SEC_ERROR_CRL_INVALID
111
112 · UNKNOWN_ISSUER
113
114 · UNKNOWN_SIGNER
115
116 · UNTRUSTED_CERT
117
118 · UNTRUSTED_ISSUER
119
120
121
122 --message-format format
123 Message format: xml (default), json.
124
125
126 -n client-certificate-nickname
127 Specifies the nickname for client certificate authentication (mutu‐
128 ally exclusive to the -u option).
129
130
131 --output folder
132 Folder to store HTTP messages.
133
134
135 -P protocol
136 Specifies the protocol (default: http).
137
138
139 -p port
140 Specifies the port (default: 8080).
141
142
143 --reject-cert-status list
144 Comma-separated list of rejected certificate validity statuses.
145
146
147 -t type
148 Subsystem type.
149
150
151 --token token
152 Security token name
153
154
155 -U URL
156 Specifies the server URL.
157
158
159 -u username
160 Specifies the username for basic authentication (mutually exclusive
161 to the -n option).
162
163
164 -v, --verbose
165 Displays verbose information.
166
167
168 --version
169 Displays CLI version information.
170
171
172 -w password
173 Specifies the user password (mutually exclusive to the -W option).
174
175
176 -W client-side-password-file
177 Specifies the file which contains the user password (mutually
178 exclusive to the -w option).
179
180
182 To view available commands and options, simply type pki. Some commands
183 have sub-commands. To view the sub-commands, type pki *command*. To
184 view each command's usage, type pki command --help.
185
186
187 An NSS database is needed to execute commands that require crypto oper‐
188 ations such as establishing SSL connection. See pki-client(1) for more
189 information.
190
191
192 Connection
193 By default, the CLI connects to a server running on the local machine
194 via the non-secure HTTP port 8080. To specify a different server loca‐
195 tion, use the appropriate arguments to give a different host (-h), port
196 (-p), or connection protocol (-P).
197
198
199 $ pki -P <protocol> -h <hostname> -p <port> <command>
200
201
202
203 Alternatively, the connection parameters can be specified as a URI:
204
205
206 $ pki -U <URI> <command>
207
208
209
210 where the URI is of the format protocol://hostname:port.
211
212
214 Some commands require authentication. These are commands that are
215 restricted to particular sets of users (such as agents or admins) or
216 those operations involving certificate profiles that require authenti‐
217 cation.
218
219
220 To execute a command without authentication:
221
222
223 $ pki <command>
224
225
226
227 To execute a command using basic authentication (i.e. username/pass‐
228 word), see the Basic Authentication section of this man page.
229
230
231 To execute a command using client authentication (i.e. client certifi‐
232 cate), see the Client Authentication section of this man page.
233
234
235 Basic Authentication
236 To authenticate with a username and password:
237
238
239 $ pki -u <username> -w <password> <command>
240
241
242
243 Rather than being exposed in plaintext on the command-line, user pass‐
244 words may be stored in a file instead. See Client-side Password Files
245 for detailed information.
246
247
248 To authenticate with a username by obtaining the user password from a
249 client-side password file:
250
251
252 $ pki -u <username> -W <client-side password file> <command>
253
254
255
256 Finally, if a username has been specified on the command-line, and nei‐
257 ther the -W client-side-password-file nor the -w password options have
258 been utilized, the password will be prompted for.
259
260
261 To authenticate with a username by interactively prompting for a pass‐
262 word:
263
264
265 $ pki -u <username> <command>
266
267
268
269 Note: Prompting for a user password is not suitable for automated batch
270 processing.
271
272
273 Client Authentication Setup
274 A client certificate associated with the desired PKI server must be
275 used for client authentication. This can be done by importing the
276 client certificate into an NSS security database and passing the values
277 to the relevant options provided by the pki CLI framework.
278
279
280 To achieve this, execute the following commands to set up an NSS data‐
281 base for use by the pki client, import the client certificate into the
282 NSS database, and list information (including the nickname of the
283 client certificate) stored in the NSS database:
284
285
286 $ certutil -N -d <NSS database location>
287 $ pk12util -i <client's PKCS #12 file> -d <NSS database location>
288 $ certutil -L -d <NSS database location>
289
290
291
292 The first command creates an NSS database, and asks the client user to
293 enter a password for this NSS database.
294
295
296 The second command imports a client certificate stored in a PKCS #12
297 format into this NSS database; it prompts for the passwords of the
298 PKCS12 file and the NSS database. The simplest example of such a
299 client certificate is to obtain the administrator certificate created
300 during the configuration portion of the basic PKI installation of the
301 associated PKI server (e.g. located at /root/.dogtag/pki-tom‐
302 cat/ca_admin_cert.p12 on the PKI server machine).
303
304
305 The third command shows the information about the imported client cer‐
306 tificate (including its nickname).
307
308
309 Additionally, provision the root CA certificate into this NSS DB. This
310 certificate must be imported into the NSS DB and copied as a PEM format
311 certificate into the NSS DB directory, named 'ca.crt'. To do so:
312
313
314 $ certutil -A -d <NSS database location> -n "CA Root Certificate" -a -i /path/to/ca.crt
315 $ cp /path/to/ca.crt <NSS database location>/ca.crt
316
317
318
319 This will ensure all parts of the client can successfully connect with
320 the PKI instance and validate the certificate used to sign the web UI.
321 If an external CA certificate was used to approve the sslserver cer‐
322 tificate, import that certificate instead.
323
324
325 Client Authentication
326 To authenticate with a client certificate:
327
328
329 $ pki -d <NSS database location> -c <NSS database password> -n <client certificate nickname> <command>
330
331
332
333 Alternatively, to prevent exposure via the command-line, an NSS data‐
334 base may store their password in a file instead. See Client-side Pass‐
335 word Files for detailed information.
336
337
338 To authenticate with a client certificate by using the NSS database
339 password stored in a file:
340
341
342 $ pki -d <NSS database location> -C <NSS password file> -n <client certificate nickname> <command>
343
344
345
346 Finally, if a client certificate has been specified on the com‐
347 mand-line, and neither the -C NSS-database-password-file nor the -c
348 NSS-database-password options have been utilized, the NSS database
349 password will be prompted for.
350
351
352 To authenticate with a client certificate by interactively prompting
353 for an NSS database password:
354
355
356 $ pki -d <NSS database location> -n <client certificate nickname> <command>
357
358
359
360 Note: Prompting for an NSS database password is not suitable for auto‐
361 mated batch processing.
362
363
364 Client-side Password Files
365 Both the -C (client authentication) and the -W (basic authentication)
366 options require the use of a client-side password file.
367
368
369 For security purposes, client-side password files should be, at a mini‐
370 mum, operating system protected non-world readable files.
371
372
373 Client-side password files generally store a password in an
374 equals-sign-delimited plaintext format 'token=password' (e.g. 'inter‐
375 nal=foobar' where 'internal' is the token, '=' is the delimiter, and
376 'foobar' is the actual password). The token keyword 'internal' is the
377 default specification for a token, and refers to the "Internal Key
378 Storage Token". If a client-side password file is being used for the
379 sole purposes of the pki command-line tool, a client-side password file
380 also supports the format that merely consists of the plaintext password
381 on a single line (read the Caveats which follow).
382
383
384 Caveats:
385
386
387 Since client-side password files are allowed to use the 'token=pass‐
388 word' format, the first '=' character can only be used as a delimiter
389 (i.e. it cannot be used as a valid character within the 'token' name)
390 as escaping the '=' character within a token is not supported.
391
392
393 When specifying a password which contains an '=' character, always
394 specify an initial '=' prior to specifying the actual password (manda‐
395 tory when no token has been specified) as escaping the '=' character
396 within a password is not supported.
397
398
399 Tokens do not support leading or trailing whitespace since these char‐
400 acters are stripped prior to their use; however, all whitespace inside
401 tokens will be preserved.
402
403
404 Passwords preserve all leading, trailing, and internal whitespace since
405 passwords are not trimmed prior to their use.
406
407
408 TBD: Supply code to handle the case of a non-internal token (e.g.
409 'hardware-nethsm' utilized in the following examples) since the current
410 code ignores the specified token (i.e. it always utilizes the default
411 'internal' token no matter what is currently specified).
412
413
414 TBD: Allow numerous 'token=password' lines in a single client-side
415 password file to support the ability to authenticate against specified
416 tokens as well as multiple tokens.
417
418
419 Valid examples include:
420 internal=foobar
421 where token="internal" and password="foobar"
422
423
424 hardware-nethsm=foobar
425 where token="hardware-nethsm" (ignored - TBD) and password="foobar"
426
427
428 internal=ack=bar
429 where token="internal" and password="ack=bar"
430
431
432 hardware-nethsm=ack=bar
433 where and token="hardware-nethsm" (ignored - TBD) and pass‐
434 word="ack=bar"
435
436
437 =foobar
438 where token="internal" (default) and password="foobar"
439
440
441 =foo=bar
442 where token="internal" (default) and password="foo=bar"
443 (Since the password contains an '=' character, an initial '=' char‐
444 acter must be specified!)
445
446
447 foobar
448 where token="internal" (default) and password="foobar"
449
450
451 Results Paging
452 Some commands (e.g. cert-find) may return multiple results. Since the
453 number of results may be large, the results are split into multiple
454 pages. By default the command will return only the first page (e.g. the
455 first 20 results). To retrieve results from another page, additional
456 paging parameters can be specified:
457
458
459 · start: index of the first result to return (default: 0)
460
461 · size: number of results to return (default: 20)
462
463
464
465 For example, to retrieve the first page (index #0-#19):
466
467
468 $ pki cert-find --start 0 --size 20
469
470
471
472 To retrieve the second page (index #20-#39):
473
474
475 $ pki cert-find --start 20 --size 20
476
477
478
479 To retrieve the third page (index #40-#59):
480
481
482 $ pki cert-find --start 40 --size 20
483
484
485
487 /usr/bin/pki
488
489
491 pki-cert(1)
492 Certificate management commands
493
494
495 pki-client(1)
496 NSS database management commands
497
498
499 pki-group(1)
500 Group management commands
501
502
503 pki-group-member(1)
504 Group member management commands
505
506
507 pki-key(1)
508 Key management commands
509
510
511 pki-securitydomain(1)
512 Security domain management commands
513
514
515 pki-user(1)
516 User management commands
517
518
519 pki-user-cert(1)
520 User certificate management commands
521
522
523 pki-user-membership(1)
524 User membership management commands
525
526
527 pki-ca-profile(1)
528 Profile management commands
529
530
532 Ade Lee lt;alee@redhat.comgt;, Endi Dewata lt;edewata@redhat.comgt;,
533 and Matthew Harmsen lt;mharmsen@redhat.comgt;.
534
535
537 Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU Gen‐
538 eral Public License, version 2 (GPLv2). A copy of this license is
539 available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
540
541
542
543PKI February 1, 2019 pki(1)