1pki(1) pki CLI pki(1)
2
6 pki - Command-Line Interface for accessing PKI services.
7
10 pki [CLI-options] command [command-arguments]
11
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
20 -c NSS-database-password
21 Specifies the NSS database password (mutually exclusive to the -C
22 option).
23 -C NSS-database-password-file
26 Specifies the file which contains the NSS database password (mutu‐
27 ally exclusive to the -c option).
28 -d NSS-database-location
31 Specifies the NSS database location (default: #8764;/.dog‐
32 tag/nssdb).
33 -h hostname
36 Specifies the hostname (default: hostname of the local machine).
37 --help
40 Prints additional help information.
41 --ignore-cert-status list
44 Comma-separated list of ignored certificate validity statuses.
45 Valid values are:
46 · BAD_CERT_DOMAIN
49 · BAD_KEY
51 · BAD_SIGNATURE
53 · CA_CERT_INVALID
55 · CERT_BAD_ACCESS_LOCATION
57 · CERT_NOT_IN_NAME_SPACE
59 · CERT_STATUS_SERVER_ERROR
61 · EXPIRED_CERTIFICATE
63 · EXPIRED_ISSUER_CERTIFICATE
65 · INADEQUATE_CERT_TYPE
67 · INADEQUATE_KEY_USAGE
69 · INVALID_TIME
71 · OCSP_BAD_HTTP_RESPONSE
73 · OCSP_FUTURE_RESPONSE
75 · OCSP_MALFORMED_REQUEST
77 · OCSP_MALFORMED_RESPONSE
79 · OCSP_NO_DEFAULT_RESPONDER
81 · OCSP_NOT_ENABLED
83 · OCSP_OLD_RESPONSE
85 · OCSP_REQUEST_NEEDS_SIG
87 · OCSP_SERVER_ERROR
89 · OCSP_TRY_SERVER_LATER
91 · OCSP_UNAUTHORIZED_REQUEST
93 · OCSP_UNKNOWN_CERT
95 · OCSP_UNKNOWN_RESPONSE_STATUS
97 · OCSP_UNKNOWN_RESPONSE_TYPE
99 · OCSP_UNAUTHORIZED_RESPONSE
101 · PATH_LEN_CONSTRAINT_INVALID
103 · REVOKED_CERTIFICATE
105 · SEC_ERROR_CRL_BAD_SIGNATURE
107 · SEC_ERROR_CRL_EXPIRED
109 · SEC_ERROR_CRL_INVALID
111 · UNKNOWN_ISSUER
113 · UNKNOWN_SIGNER
115 · UNTRUSTED_CERT
117 · UNTRUSTED_ISSUER
119 --message-format format
123 Message format: xml (default), json.
124 -n client-certificate-nickname
127 Specifies the nickname for client certificate authentication (mutu‐
128 ally exclusive to the -u option).
129 --output folder
132 Folder to store HTTP messages.
133 -P protocol
136 Specifies the protocol (default: http).
137 -p port
140 Specifies the port (default: 8080).
141 --reject-cert-status list
144 Comma-separated list of rejected certificate validity statuses.
145 -t type
148 Subsystem type.
149 --token token
152 Security token name
153 -U URL
156 Specifies the server URL.
157 -u username
160 Specifies the username for basic authentication (mutually exclusive
161 to the -n option).
162 -v, --verbose
165 Displays verbose information.
166 --version
169 Displays CLI version information.
170 -w password
173 Specifies the user password (mutually exclusive to the -W option).
174 -W client-side-password-file
177 Specifies the file which contains the user password (mutually
178 exclusive to the -w option).
179
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 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 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 $ pki -P <protocol> -h <hostname> -p <port> <command>
200 Alternatively, the connection parameters can be specified as a URI:
204 $ pki -U <URI> <command>
207 where the URI is of the format protocol://hostname:port.
211
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 To execute a command without authentication:
221 $ pki <command>
224 To execute a command using basic authentication (i.e. username/pass‐
228 word), see the Basic Authentication section of this man page.
229 To execute a command using client authentication (i.e. client certifi‐
232 cate), see the Client Authentication section of this man page.
233 Basic Authentication
236 To authenticate with a username and password:
237 $ pki -u <username> -w <password> <command>
240 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 To authenticate with a username by obtaining the user password from a
249 client-side password file:
250 $ pki -u <username> -W <client-side password file> <command>
253 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 To authenticate with a username by interactively prompting for a pass‐
262 word:
263 $ pki -u <username> <command>
266 Note: Prompting for a user password is not suitable for automated batch
270 processing.
271 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 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 $ 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 The first command creates an NSS database, and asks the client user to
293 enter a password for this NSS database.
294 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 The third command shows the information about the imported client cer‐
306 tificate (including its nickname).
307 Note: When issuing the first pki command using the authentication
310 parameters (after completion of the setup of the NSS database), a user
311 may be greeted with a warning message which indicates that an untrusted
312 issuer was encountered. Simply reply 'Y' to import the CA certificate,
313 and, presuming that the displayed CA server URL is valid, press the
314 carriage return.
315 Client Authentication
318 To authenticate with a client certificate:
319 $ pki -d <NSS database location> -c <NSS database password> -n <client certificate nickname> <command>
322 Alternatively, to prevent exposure via the command-line, an NSS data‐
326 base may store their password in a file instead. See Client-side Pass‐
327 word Files for detailed information.
328 To authenticate with a client certificate by using the NSS database
331 password stored in a file:
332 $ pki -d <NSS database location> -C <NSS password file> -n <client certificate nickname> <command>
335 Finally, if a client certificate has been specified on the com‐
339 mand-line, and neither the -C NSS-database-password-file nor the -c
340 NSS-database-password options have been utilized, the NSS database
341 password will be prompted for.
342 To authenticate with a client certificate by interactively prompting
345 for an NSS database password:
346 $ pki -d <NSS database location> -n <client certificate nickname> <command>
349 Note: Prompting for an NSS database password is not suitable for auto‐
353 mated batch processing.
354 Client-side Password Files
357 Both the -C (client authentication) and the -W (basic authentication)
358 options require the use of a client-side password file.
359 For security purposes, client-side password files should be, at a mini‐
362 mum, operating system protected non-world readable files.
363 Client-side password files generally store a password in an
366 equals-sign-delimited plaintext format 'token=password' (e.g. 'inter‐
367 nal=foobar' where 'internal' is the token, '=' is the delimiter, and
368 'foobar' is the actual password). The token keyword 'internal' is the
369 default specification for a token, and refers to the "Internal Key
370 Storage Token". If a client-side password file is being used for the
371 sole purposes of the pki command-line tool, a client-side password file
372 also supports the format that merely consists of the plaintext password
373 on a single line (read the Caveats which follow).
374 Caveats:
377 Since client-side password files are allowed to use the 'token=pass‐
380 word' format, the first '=' character can only be used as a delimiter
381 (i.e. it cannot be used as a valid character within the 'token' name)
382 as escaping the '=' character within a token is not supported.
383 When specifying a password which contains an '=' character, always
386 specify an initial '=' prior to specifying the actual password (manda‐
387 tory when no token has been specified) as escaping the '=' character
388 within a password is not supported.
389 Tokens do not support leading or trailing whitespace since these char‐
392 acters are stripped prior to their use; however, all whitespace inside
393 tokens will be preserved.
394 Passwords preserve all leading, trailing, and internal whitespace since
397 passwords are not trimmed prior to their use.
398 TBD: Supply code to handle the case of a non-internal token (e.g.
401 'hardware-nethsm' utilized in the following examples) since the current
402 code ignores the specified token (i.e. it always utilizes the default
403 'internal' token no matter what is currently specified).
404 TBD: Allow numerous 'token=password' lines in a single client-side
407 password file to support the ability to authenticate against specified
408 tokens as well as multiple tokens.
409 Valid examples include:
412 internal=foobar
413 where token="internal" and password="foobar"
414 hardware-nethsm=foobar
417 where token="hardware-nethsm" (ignored - TBD) and password="foobar"
418 internal=ack=bar
421 where token="internal" and password="ack=bar"
422 hardware-nethsm=ack=bar
425 where and token="hardware-nethsm" (ignored - TBD) and pass‐
426 word="ack=bar"
427 =foobar
430 where token="internal" (default) and password="foobar"
431 =foo=bar
434 where token="internal" (default) and password="foo=bar"
435 (Since the password contains an '=' character, an initial '=' char‐
436 acter must be specified!)
437 foobar
440 where token="internal" (default) and password="foobar"
441 Results Paging
444 Some commands (e.g. cert-find) may return multiple results. Since the
445 number of results may be large, the results are split into multiple
446 pages. By default the command will return only the first page (e.g. the
447 first 20 results). To retrieve results from another page, additional
448 paging parameters can be specified:
449 · start: index of the first result to return (default: 0)
452 · size: number of results to return (default: 20)
454 For example, to retrieve the first page (index #0-#19):
458 $ pki cert-find --start 0 --size 20
461 To retrieve the second page (index #20-#39):
465 $ pki cert-find --start 20 --size 20
468 To retrieve the third page (index #40-#59):
472 $ pki cert-find --start 40 --size 20
475
479 /usr/bin/pki
480
483 pki-cert(1)
484 Certificate management commands
485 pki-client(1)
488 NSS database management commands
489 pki-group(1)
492 Group management commands
493 pki-group-member(1)
496 Group member management commands
497 pki-key(1)
500 Key management commands
501 pki-securitydomain(1)
504 Security domain management commands
505 pki-user(1)
508 User management commands
509 pki-user-cert(1)
512 User certificate management commands
513 pki-user-membership(1)
516 User membership management commands
517 pki-ca-profile(1)
520 Profile management commands
521
524 Ade Lee lt;alee@redhat.comgt;, Endi Dewata lt;edewata@redhat.comgt;,
525 and Matthew Harmsen lt;mharmsen@redhat.comgt;.
526
529 Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU Gen‐
530 eral Public License, version 2 (GPLv2). A copy of this license is
531 available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
532PKI February 1, 2019 pki(1)