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: ∼/.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 ex‐
178 clusive 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 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 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-tomcat/ca_ad‐
302 min_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 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 $ 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 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 Client Authentication
326 To authenticate with a client certificate:
327 $ pki -d <NSS database location> -c <NSS database password> -n <client certificate nickname> <command>
330 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 To authenticate with a client certificate by using the NSS database
339 password stored in a file:
340 $ pki -d <NSS database location> -C <NSS password file> -n <client certificate nickname> <command>
343 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 To authenticate with a client certificate by interactively prompting
353 for an NSS database password:
354 $ pki -d <NSS database location> -n <client certificate nickname> <command>
357 Note: Prompting for an NSS database password is not suitable for auto‐
361 mated batch processing.
362 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 For security purposes, client-side password files should be, at a mini‐
370 mum, operating system protected non-world readable files.
371 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 Caveats:
385 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 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 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 Passwords preserve all leading, trailing, and internal whitespace since
405 passwords are not trimmed prior to their use.
406 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 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 Valid examples include:
420 internal=foobar
421 where token="internal" and password="foobar"
422 hardware-nethsm=foobar
425 where token="hardware-nethsm" (ignored - TBD) and password="foobar"
426 internal=ack=bar
429 where token="internal" and password="ack=bar"
430 hardware-nethsm=ack=bar
433 where and token="hardware-nethsm" (ignored - TBD) and pass‐
434 word="ack=bar"
435 =foobar
438 where token="internal" (default) and password="foobar"
439 =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 foobar
448 where token="internal" (default) and password="foobar"
449 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 • start: index of the first result to return (default: 0)
460 • size: number of results to return (default: 20)
462 For example, to retrieve the first page (index #0-#19):
466 $ pki cert-find --start 0 --size 20
469 To retrieve the second page (index #20-#39):
473 $ pki cert-find --start 20 --size 20
476 To retrieve the third page (index #40-#59):
480 $ pki cert-find --start 40 --size 20
483
487 /usr/bin/pki
488
491 pki-cert(1)
492 Certificate management commands
493 pki-client(1)
496 NSS database management commands
497 pki-group(1)
500 Group management commands
501 pki-group-member(1)
504 Group member management commands
505 pki-key(1)
508 Key management commands
509 pki-securitydomain(1)
512 Security domain management commands
513 pki-user(1)
516 User management commands
517 pki-user-cert(1)
520 User certificate management commands
521 pki-user-membership(1)
524 User membership management commands
525 pki-ca-profile(1)
528 Profile management commands
529
532 Ade Lee <alee@redhat.com>, Endi Dewata <edewata@red‐
533 hat.com>, and Matthew Harmsen <mharmsen@redhat.com>.
534
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.
540PKI February 1, 2019 pki(1)