1pki(1) PKI Command-Line Interface (CLI) pki(1)
2
6 pki - Command-Line Interface for accessing Certificate System 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 Certificate System server. These ser‐
16 vices include certificates, groups, keys, security domains, and users.
17
20 -c <client security database password>
21 Specifies the client security database password (mutually exclu‐
22 sive to the '-C' option).
23 -C <client-side password file>
25 Specifies the file which contains the client security database
26 password (mutually exclusive to the '-c' option).
27 -d <client security database location>
29 Specifies the client security database location (default:
30 ~/.dogtag/nssdb).
31 -h <hostname>
33 Specifies the hostname (default: hostname of the local machine).
34 --help Prints additional help information.
36 --ignore-cert-status <list>
38 Comma-separated list of ignored certificate validity statuses.
39 --message-format <format>
41 Message format: xml (default), json.
42 -n <client certificate nickname>
44 Specifies the nickname for client certificate authentication
45 (mutually exclusive to the '-u' option). This authentication
46 requires a security database password.
47 --output <folder>
49 Folder to store HTTP messages.
50 -P <protocol>
52 Specifies the protocol (default: http).
53 -p <port>
55 Specifies the port (default: 8080).
56 --reject-cert-status <list>
58 Comma-separated list of rejected certificate validity statuses.
59 PKI subsystem type - [CA, KRA, OCSP, TKS, or TPS] (non-case-sen‐
60 sitive).
61 -t <type>
63 Subsystem type.
64 --token
66 Security token name
67 -U <URI>
69 Specifies the server URI.
70 -u <username>
72 Specifies the username for basic authentication (mutually exclu‐
73 sive to the '-n' option). This authentication requires a user
74 password.
75 -v, --verbose
77 Displays verbose information.
78 --version
80 Displays CLI version information.
81 -w <password>
83 Specifies the user password (mutually exclusive to the '-W'
84 option).
85 -W <client-side password file>
87 Specifies the file which contains the user password (mutually
88 exclusive to the '-w' option).
89
92 To view available commands and options, simply type pki. Some commands
93 have sub-commands. To view the sub-commands, type pki <command>. To
94 view each command's usage, type pki <command> --help.
95 A client security database is needed to execute commands that require
97 SSL connection or client certificate for authentication. See pki-
98 client(1) for more information.
99 Connection
102 By default, the CLI connects to a server running on the local machine
103 via the non-secure HTTP port 8080. To specify a different server loca‐
104 tion, use the appropriate arguments to give a different host (-h), port
105 (-p), or connection protocol (-P).
106 pki -P <protocol> -h <hostname> -p <port> <command>
108 Alternatively, the connection parameters can be specified as a URI:
110 pki -U <URI> <command>
112 where the URI is of the format <protocol>://<hostname>:<port>.
114 Authentication
117 Some commands require authentication. These are commands that are
118 restricted to particular sets of users (such as agents or admins) or
119 those operations involving certificate profiles that require authenti‐
120 cation.
121 To execute a command without authentication:
123 pki <command>
125 To execute a command using basic authentication (i. e. - username/pass‐
127 word), see the Basic Authentication section of this man page.
128 To execute a command using client authentication (i. e. - client cer‐
130 tificate), see the Client Authentication section of this man page.
131 Basic Authentication
134 To authenticate with a username and password:
135 pki -u <username> -w <password> <command>
137 Rather than being exposed in plaintext on the command-line, user pass‐
139 words may be stored in a file instead. See Client-side Password Files
140 for detailed information.
141 To authenticate with a username by obtaining the user password from a
143 client-side password file:
144 pki -u <username> -W <client-side password file> <command>
146 Finally, if a username has been specified on the command-line, and nei‐
148 ther the '-W <client-side password file>' nor the '-w <password>'
149 options have been utilized, the password will be prompted for.
150 To authenticate with a username by interactively prompting for a pass‐
152 word:
153 pki -u <username> <command>
155 Note: Prompting for a user password is not suitable for automated batch
157 processing.
158 Client Authentication Setup
161 A client certificate associated with the desired PKI server must be
162 used for client authentication. This can be done by importing the
163 client certificate into an NSS security database and passing the values
164 to the relevant options provided by the pki CLI framework.
165 To achieve this, execute the following commands to set up an NSS secu‐
167 rity database for use by the pki client, import the client certificate
168 into the NSS database, and list information (including the nickname of
169 the client certificate) stored in the NSS database:
170 - certutil -N -d <CERT_DB_DIR_PATH>
172 - pk12util -i <Agent_Cert_P12_FILE_PATH> -d <CERT_DB_DIR_PATH>
174 - certutil -L -d <CERT_DB_DIR_PATH>
176 The first command creates a client security database, and asks the
178 client user to enter a password for this NSS database.
179 The second command imports a client certificate stored in a PKCS12 for‐
181 mat into this NSS database; it prompts for the passwords of the PKCS12
182 file and the client security database. The simplist example of such a
183 client certificate is to obtain the administrator certificate created
184 during the configuration portion of the basic PKI installation of the
185 associated PKI server (e. g. - located at /root/.dogtag/pki-tom‐
186 cat/ca_admin_cert.p12 on the PKI server machine).
187 The third command shows the information about the imported client cer‐
189 tificate (including its nickname).
190 Note: When issuing the first pki command using the authentication
192 parameters (after completion of the setup of the client security data‐
193 base), a user may be greeted with a warning message which indicates
194 that an untrusted issuer was encountered. Simply reply 'Y' to import
195 the CA certificate, and, presuming that the displayed CA server URL is
196 valid, press the carriage return.
197 Client Authentication
200 To authenticate with a client certificate:
201 pki -d <client security database location> -c <client security database
203 password> -n <client certificate nickname> <command>
204 Alternatively, to prevent exposure via the command-line, a client secu‐
206 rity database may store their password in a file instead. See Client-
207 side Password Files for detailed information.
208 To authenticate with a client certificate by obtaining the client secu‐
210 rity database password from a client-side password file:
211 pki -d <client security database location> -C <client-side password
213 file> -n <client certificate nickname> <command>
214 Finally, if a client certificate has been specified on the command-
216 line, and neither the '-C <client-side password file>' nor the '-c
217 <client security database password>' options have been utilized, the
218 client security database password will be prompted for.
219 To authenticate with a client certificate by interactively prompting
221 for a client security database password:
222 pki -d <client security database location> -n <client certificate nick‐
224 name> <command>
225 Note: Prompting for a client security database password is not suitable
227 for automated batch processing.
228 Client-side Password Files
231 Both the '-C' (client authentication) and the '-W' (basic authentica‐
232 tion) options require the use of a client-side password file.
233 For security purposes, client-side password files should be, at a mini‐
235 mum, operating system protected non-world readable files.
236 Client-side password files generally store a password in an equals-
238 sign-delimited plaintext format 'token=password' (e. g. - 'inter‐
239 nal=foobar' where 'internal' is the token, '=' is the delimiter, and
240 'foobar' is the actual password). The token keyword 'internal' is the
241 default specification for a token, and refers to the "Internal Key
242 Storage Token". If a client-side password file is being used for the
243 sole purposes of the pki command-line tool, a client-side password file
244 also supports the format that merely consists of the plaintext password
245 on a single line (read the Caveats which follow).
246 Caveats:
248 · Since client-side password files are allowed to use the
250 'token=password' format, the first '=' character can only be
251 used as a delimiter (i. e. - it cannot be used as a valid char‐
252 acter within the 'token' name) as escaping the '=' character
253 within a token is not supported.
254 · When specifying a password which contains an '=' character,
256 always specify an initial '=' prior to specifying the actual
257 password (mandatory when no token has been specified) as escap‐
258 ing the '=' character within a password is not supported.
259 · Tokens do not support leading or trailing whitespace since
261 these characters are stripped prior to their use; however, all
262 whitespace inside tokens will be preserved.
263 · Passwords preserve all leading, trailing, and internal white‐
265 space since passwords are not trimmed prior to their use.
266 · TBD: Supply code to handle the case of a non-internal token
268 (e. g. - 'hardware-nethsm' utilized in the following examples)
269 since the current code ignores the specified token (i. e. - it
270 always utilizes the default 'internal' token no matter what is
271 currently specified).
272 · TBD: Allow numerous 'token=password' lines in a single client-
274 side password file to support the ability to authenticate
275 against specified tokens as well as multiple tokens.
276 Valid examples include:
279 internal=foobar
281 where: token="internal", password="foobar"
282 hardware-nethsm=foobar
284 where: token="hardware-nethsm" (ignored - TBD), password="foobar"
285 internal=ack=bar
287 where: token="internal", password="ack=bar"
288 hardware-nethsm=ack=bar
290 where: token="hardware-nethsm" (ignored - TBD), password="ack=bar"
291 =foobar
293 where: token="internal" (default), password="foobar"
294 =foo=bar
296 where: token="internal" (default), password="foo=bar"
297 (Since the password contains an '=' character,
298 an initial '=' character must be specified!)
299 foobar
301 where: token="internal" (default), password="foobar"
302 Results Paging
305 Some commands (e.g. cert-find) may return multiple results. Since the
306 number of results may be large, the results are split into multiple
307 pages. By default the command will return only the first page (e.g. the
308 first 20 results). To retrieve results from another page, additional
309 paging parameters can be specified:
310 * start: index of the first result to return (default: 0)
312 * size: number of results to return (default: 20)
313 For example, to retrieve the first page (index #0-#19):
315 pki cert-find --start 0 --size 20
317 To retrieve the second page (index #20-#39):
319 pki cert-find --start 20 --size 20
321 To retrieve the third page (index #40-#59):
323 pki cert-find --start 40 --size 20
325
328 /usr/bin/pki
329
332 pki-cert(1)
333 Certificate management commands
334 pki-client(1)
337 Client security database management commands
338 pki-group(1)
341 Group management commands
342 pki-group-member(1)
345 Group member management commands
346 pki-key(1)
349 Key management commands
350 pki-securitydomain(1)
353 Security domain management commands
354 pki-user(1)
357 User management commands
358 pki-user-cert(1)
361 User certificate management commands
362 pki-user-membership(1)
365 User membership management commands
366 pki-ca-profile(1)
369 Profile management commands
370
373 Ade Lee <alee@redhat.com>, Endi Dewata <edewata@redhat.com>, and
374 Matthew Harmsen <mharmsen@redhat.com>.
375
378 Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU General
379 Public License, version 2 (GPLv2). A copy of this license is available
380 at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
381version 10.2 May 5, 2014 pki(1)