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: ∼/.dogtag/nssdb).
32 -h hostname
35 Specifies the hostname (default: hostname of the local machine).
36 --help
39 Prints additional help information.
40 --ignore-cert-status list
43 Comma-separated list of ignored certificate validity statuses.
44 Valid values are:
45 · BAD_CERT_DOMAIN
48 · BAD_KEY
50 · BAD_SIGNATURE
52 · CA_CERT_INVALID
54 · CERT_BAD_ACCESS_LOCATION
56 · CERT_NOT_IN_NAME_SPACE
58 · CERT_STATUS_SERVER_ERROR
60 · EXPIRED_CERTIFICATE
62 · EXPIRED_ISSUER_CERTIFICATE
64 · INADEQUATE_CERT_TYPE
66 · INADEQUATE_KEY_USAGE
68 · INVALID_TIME
70 · OCSP_BAD_HTTP_RESPONSE
72 · OCSP_FUTURE_RESPONSE
74 · OCSP_MALFORMED_REQUEST
76 · OCSP_MALFORMED_RESPONSE
78 · OCSP_NO_DEFAULT_RESPONDER
80 · OCSP_NOT_ENABLED
82 · OCSP_OLD_RESPONSE
84 · OCSP_REQUEST_NEEDS_SIG
86 · OCSP_SERVER_ERROR
88 · OCSP_TRY_SERVER_LATER
90 · OCSP_UNAUTHORIZED_REQUEST
92 · OCSP_UNKNOWN_CERT
94 · OCSP_UNKNOWN_RESPONSE_STATUS
96 · OCSP_UNKNOWN_RESPONSE_TYPE
98 · OCSP_UNAUTHORIZED_RESPONSE
100 · PATH_LEN_CONSTRAINT_INVALID
102 · REVOKED_CERTIFICATE
104 · SEC_ERROR_CRL_BAD_SIGNATURE
106 · SEC_ERROR_CRL_EXPIRED
108 · SEC_ERROR_CRL_INVALID
110 · UNKNOWN_ISSUER
112 · UNKNOWN_SIGNER
114 · UNTRUSTED_CERT
116 · UNTRUSTED_ISSUER
118 --message-format format
122 Message format: xml (default), json.
123 -n client-certificate-nickname
126 Specifies the nickname for client certificate authentication (mutu‐
127 ally exclusive to the -u option).
128 --output folder
131 Folder to store HTTP messages.
132 -P protocol
135 Specifies the protocol (default: http).
136 -p port
139 Specifies the port (default: 8080).
140 --reject-cert-status list
143 Comma-separated list of rejected certificate validity statuses.
144 -t type
147 Subsystem type.
148 --token token
151 Security token name
152 -U URL
155 Specifies the server URL.
156 -u username
159 Specifies the username for basic authentication (mutually exclusive
160 to the -n option).
161 -v, --verbose
164 Displays verbose information.
165 --version
168 Displays CLI version information.
169 -w password
172 Specifies the user password (mutually exclusive to the -W option).
173 -W client-side-password-file
176 Specifies the file which contains the user password (mutually
177 exclusive to the -w option).
178
181 To view available commands and options, simply type pki. Some commands
182 have sub-commands. To view the sub-commands, type pki *command*. To
183 view each command's usage, type pki command --help.
184 An NSS database is needed to execute commands that require crypto oper‐
187 ations such as establishing SSL connection. See pki-client(1) for more
188 information.
189 Connection
192 By default, the CLI connects to a server running on the local machine
193 via the non-secure HTTP port 8080. To specify a different server loca‐
194 tion, use the appropriate arguments to give a different host (-h), port
195 (-p), or connection protocol (-P).
196 $ pki -P <protocol> -h <hostname> -p <port> <command>
199 Alternatively, the connection parameters can be specified as a URI:
203 $ pki -U <URI> <command>
206 where the URI is of the format protocol://hostname:port.
210
213 Some commands require authentication. These are commands that are
214 restricted to particular sets of users (such as agents or admins) or
215 those operations involving certificate profiles that require authenti‐
216 cation.
217 To execute a command without authentication:
220 $ pki <command>
223 To execute a command using basic authentication (i.e. username/pass‐
227 word), see the Basic Authentication section of this man page.
228 To execute a command using client authentication (i.e. client certifi‐
231 cate), see the Client Authentication section of this man page.
232 Basic Authentication
235 To authenticate with a username and password:
236 $ pki -u <username> -w <password> <command>
239 Rather than being exposed in plaintext on the command-line, user pass‐
243 words may be stored in a file instead. See Client-side Password Files
244 for detailed information.
245 To authenticate with a username by obtaining the user password from a
248 client-side password file:
249 $ pki -u <username> -W <client-side password file> <command>
252 Finally, if a username has been specified on the command-line, and nei‐
256 ther the -W client-side-password-file nor the -w password options have
257 been utilized, the password will be prompted for.
258 To authenticate with a username by interactively prompting for a pass‐
261 word:
262 $ pki -u <username> <command>
265 Note: Prompting for a user password is not suitable for automated batch
269 processing.
270 Client Authentication Setup
273 A client certificate associated with the desired PKI server must be
274 used for client authentication. This can be done by importing the
275 client certificate into an NSS security database and passing the values
276 to the relevant options provided by the pki CLI framework.
277 To achieve this, execute the following commands to set up an NSS data‐
280 base for use by the pki client, import the client certificate into the
281 NSS database, and list information (including the nickname of the
282 client certificate) stored in the NSS database:
283 $ certutil -N -d <NSS database location>
286 $ pk12util -i <client's PKCS #12 file> -d <NSS database location>
287 $ certutil -L -d <NSS database location>
288 The first command creates an NSS database, and asks the client user to
292 enter a password for this NSS database.
293 The second command imports a client certificate stored in a PKCS #12
296 format into this NSS database; it prompts for the passwords of the
297 PKCS12 file and the NSS database. The simplest example of such a
298 client certificate is to obtain the administrator certificate created
299 during the configuration portion of the basic PKI installation of the
300 associated PKI server (e.g. located at /root/.dogtag/pki-tom‐
301 cat/ca_admin_cert.p12 on the PKI server machine).
302 The third command shows the information about the imported client cer‐
305 tificate (including its nickname).
306 Note: When issuing the first pki command using the authentication
309 parameters (after completion of the setup of the NSS database), a user
310 may be greeted with a warning message which indicates that an untrusted
311 issuer was encountered. Simply reply 'Y' to import the CA certificate,
312 and, presuming that the displayed CA server URL is valid, press the
313 carriage return.
314 Client Authentication
317 To authenticate with a client certificate:
318 $ pki -d <NSS database location> -c <NSS database password> -n <client certificate nickname> <command>
321 Alternatively, to prevent exposure via the command-line, an NSS data‐
325 base may store their password in a file instead. See Client-side Pass‐
326 word Files for detailed information.
327 To authenticate with a client certificate by using the NSS database
330 password stored in a file:
331 $ pki -d <NSS database location> -C <NSS password file> -n <client certificate nickname> <command>
334 Finally, if a client certificate has been specified on the com‐
338 mand-line, and neither the -C NSS-database-password-file nor the -c
339 NSS-database-password options have been utilized, the NSS database
340 password will be prompted for.
341 To authenticate with a client certificate by interactively prompting
344 for an NSS database password:
345 $ pki -d <NSS database location> -n <client certificate nickname> <command>
348 Note: Prompting for an NSS database password is not suitable for auto‐
352 mated batch processing.
353 Client-side Password Files
356 Both the -C (client authentication) and the -W (basic authentication)
357 options require the use of a client-side password file.
358 For security purposes, client-side password files should be, at a mini‐
361 mum, operating system protected non-world readable files.
362 Client-side password files generally store a password in an
365 equals-sign-delimited plaintext format 'token=password' (e.g. 'inter‐
366 nal=foobar' where 'internal' is the token, '=' is the delimiter, and
367 'foobar' is the actual password). The token keyword 'internal' is the
368 default specification for a token, and refers to the "Internal Key
369 Storage Token". If a client-side password file is being used for the
370 sole purposes of the pki command-line tool, a client-side password file
371 also supports the format that merely consists of the plaintext password
372 on a single line (read the Caveats which follow).
373 Caveats:
376 Since client-side password files are allowed to use the 'token=pass‐
379 word' format, the first '=' character can only be used as a delimiter
380 (i.e. it cannot be used as a valid character within the 'token' name)
381 as escaping the '=' character within a token is not supported.
382 When specifying a password which contains an '=' character, always
385 specify an initial '=' prior to specifying the actual password (manda‐
386 tory when no token has been specified) as escaping the '=' character
387 within a password is not supported.
388 Tokens do not support leading or trailing whitespace since these char‐
391 acters are stripped prior to their use; however, all whitespace inside
392 tokens will be preserved.
393 Passwords preserve all leading, trailing, and internal whitespace since
396 passwords are not trimmed prior to their use.
397 TBD: Supply code to handle the case of a non-internal token (e.g.
400 'hardware-nethsm' utilized in the following examples) since the current
401 code ignores the specified token (i.e. it always utilizes the default
402 'internal' token no matter what is currently specified).
403 TBD: Allow numerous 'token=password' lines in a single client-side
406 password file to support the ability to authenticate against specified
407 tokens as well as multiple tokens.
408 Valid examples include:
411 internal=foobar
412 where token="internal" and password="foobar"
413 hardware-nethsm=foobar
416 where token="hardware-nethsm" (ignored - TBD) and password="foobar"
417 internal=ack=bar
420 where token="internal" and password="ack=bar"
421 hardware-nethsm=ack=bar
424 where and token="hardware-nethsm" (ignored - TBD) and pass‐
425 word="ack=bar"
426 =foobar
429 where token="internal" (default) and password="foobar"
430 =foo=bar
433 where token="internal" (default) and password="foo=bar"
434 (Since the password contains an '=' character, an initial '=' char‐
435 acter must be specified!)
436 foobar
439 where token="internal" (default) and password="foobar"
440 Results Paging
443 Some commands (e.g. cert-find) may return multiple results. Since the
444 number of results may be large, the results are split into multiple
445 pages. By default the command will return only the first page (e.g. the
446 first 20 results). To retrieve results from another page, additional
447 paging parameters can be specified:
448 · start: index of the first result to return (default: 0)
451 · size: number of results to return (default: 20)
453 For example, to retrieve the first page (index #0-#19):
457 $ pki cert-find --start 0 --size 20
460 To retrieve the second page (index #20-#39):
464 $ pki cert-find --start 20 --size 20
467 To retrieve the third page (index #40-#59):
471 $ pki cert-find --start 40 --size 20
474
478 /usr/bin/pki
479
482 pki-cert(1)
483 Certificate management commands
484 pki-client(1)
487 NSS database management commands
488 pki-group(1)
491 Group management commands
492 pki-group-member(1)
495 Group member management commands
496 pki-key(1)
499 Key management commands
500 pki-securitydomain(1)
503 Security domain management commands
504 pki-user(1)
507 User management commands
508 pki-user-cert(1)
511 User certificate management commands
512 pki-user-membership(1)
515 User membership management commands
516 pki-ca-profile(1)
519 Profile management commands
520
523 Ade Lee <alee@redhat.com>, Endi Dewata <edewata@redhat.com>, and
524 Matthew Harmsen <mharmsen@redhat.com>.
525
528 Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU Gen‐
529 eral Public License, version 2 (GPLv2). A copy of this license is
530 available at ⟨http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt⟩.
531PKI February 1, 2019 pki(1)