1pki(1)                              pki CLI                             pki(1)
2
3
4

NAME

6       pki - Command-Line Interface for accessing PKI services.
7
8

SYNOPSIS

10       pki [CLI-options] command [command-arguments]
11
12

DESCRIPTION

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

CLI OPTIONS

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:  ∼/.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 ex‐
178       clusive to the -w option).
179
180

OPERATIONS

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

Authentication

214       Some  commands  require authentication. These are commands that are re‐
215       stricted 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-tomcat/ca_ad‐
302       min_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 command-
347       line, and neither the -C NSS-database-password-file  nor  the  -c  NSS-
348       database-password options have been utilized, the NSS database password
349       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  equals-
374       sign-delimited  plaintext  format 'token=password' (e.g. 'internal=foo‐
375       bar' where 'internal' is the token, '=' is the delimiter, and  'foobar'
376       is  the  actual password).  The token keyword 'internal' is the default
377       specification for a token, and refers to the "Internal Key Storage  To‐
378       ken".   If  a client-side password file is being used for the sole pur‐
379       poses of the pki command-line tool, a client-side  password  file  also
380       supports the format that merely consists of the plaintext password on a
381       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

FILES

487       /usr/bin/pki
488
489

SEE ALSO

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

AUTHORS

532       Ade   Lee   &lt;alee@redhat.com&gt;,   Endi   Dewata   &lt;edewata@red‐
533       hat.com&gt;, and Matthew Harmsen &lt;mharmsen@redhat.com&gt;.
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)
Impressum