1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH pki 1 "December 13, 2012" "version 1.0" "PKI Command-Line Interface (CLI) Tools" Ade Lee
.\" Please adjust this date whenever revising the man page.
.\"
.\" Some roff macros, for reference:
.\" .nh disable hyphenation
.\" .hy enable hyphenation
.\" .ad l left justify
.\" .ad b justify to both left and right margins
.\" .nf disable filling
.\" .fi enable filling
.\" .br insert line break
.\" .sp <n> insert n+1 empty lines
.\" for man page specific macros, see man(7)
.SH NAME
pki \- Command-Line Interface Tool for accessing Certificate System Servers.
.SH SYNOPSIS
pki [CLI options] <command> [command arguments]
.SH DESCRIPTION
.PP
\fBpki\fR provides a command-line interface to Certificate System Servers, allowing administrators to manage certificates, groups, keys, security domains, and users.
.SH OPTIONS
.TP
.B -c <database password>
Specifies the certificate database password.
.TP
.B -d <database>
Specifies the certificate database to be used.
.TP
.B -h <hostname>
Specifies the hostname (default: localhost).
.TP
.B --help
Prints additional help information.
.TP
.B -n <nickname>
Specifies the certificate nickname.
.TP
.B -P <protocol>
Specifies the protocol (default: http).
.TP
.B -p <port>
Specifies the port (default: 8080).
.TP
.B -t <type>
Specifies the type of subsystem (default: ca).
.TP
.B -U <uri>
Specifies the server URI.
.TP
.B -u <username>
Specifies the username.
.TP
.B -v
Displays verbose information.
.TP
.B --version
Displays 'pki' CLI version information.
.TP
.B -w <password>
Specifies the user password.
.SH OPERATIONS
To view available commands and options, simply type \fBpki\fP. Some commands have sub-commands. To view the sub-commands, type \fBpki <command>\fP. To view each command's usage, type \fB pki <command> --help\fP.
.SS Connection
By default, \fBpki\fP connects to the non-secure (HTTP) port of a CA server running on localhost on port 8080. To specify a different server location, use the appropriate arguements to give a different host (\fB-h\fP), port (\fB-p\fP), connection protocol (\fB-P\fP), or subsystem type (\fB-t\fP).
.B pki -P <protocol> -h <hostname> -p <port> -t <subsystem> <command>
Alternatively, the connection parameters can be specified as a URL:
.B pki -U <subsystem URL> <command>
where the URL is of the format \fIhttps://<hostname>:<port>/<subsystem>\fP.
.SS Authentication
Some commands require authentication. These are commands that are restricted to particular sets of users (such as agents or admins) or those operations involving certificate profiles that require authentication.
To execute a command without authentication:
.B pki <command>
To authenticate with a username and password:
.B pki -u <username> -w <password> <command>
To authenticate with a client certificate:
.B pki -d <certificate database directory> -c <certificate database password> -n "<certificate nickname>" <command>
.SS Viewing Certificates
Certificates can be viewed anonymously.
To list all certificates:
.B pki cert-find
It is also possible to search for and list specific certificates by adding a search filter. Use \fBpki cert-find --help\fP to see options. For example, to search based on issuance date:
.B pki cert-find --issuedOnFrom 2012-06-15
To view a particular certificate:
.B pki cert-show <certificate ID>
.SS Revoking Certificates
Revoking, holding, or releasing a certificate must be executed as an agent user.
To revoke a certificate:
.B pki <agent authentication> cert-revoke <certificate ID>
To place a certificate on hold temporarily:
.B pki <agent authentication> cert-hold <certificate ID>
To release a certificate that has been placed on hold:
.B pki <agent authentication> cert-release-hold <certificate ID>
.SS Certificate Requests
To request a certificate, first generate a certificate request in PKCS #10 or CRMF, and store this request in the XML template file, of the profile type the request relates to.
The list of profiles can be viewed using the CLI command:
.B pki ca-cert-request-profile-find
The XML template file for a profile type can be created by calling the ca-cert-request-profile-show CLI command. For example:
\fBpki ca-cert-request-profile-show <profileID> --output <file to store the XML template>\fP ,
will store the XML template of the request in the specified output file.
Then, fill in the values in the XML file and submit the request for review. This can be done without authentication.
.B pki cert-request-submit <request file>
Then, an agent needs to review the request by running the following command:
.B pki <agent authentication> cert-request-review <request ID> --file <file to store the certificate request>
The certificate request, as well as the defaults and constraints of the enrollment profile, will be stored in the output file provided by the --file option. The agent can examine the file and override any values if necessary. To process the request, enter the appropriate action when prompted:
.B Action (approve/reject/cancel/update/validate/assign/unassign):
Alternatively, the agent can process the request in a single step with the following command:
.B pki <agent authentication> cert-request-review <request ID> --action <action>
.SS Group Management Commands
All group commands must be executed as an administrator. Some representative commands are shown below. Type \fBpki group\fP to get a list of additional commands.
To list groups, use \fBpki group-find\fP. It is possible to select the page size to limit the number of entries returned. To list all groups:
.B pki <admin authentication> group-find
To view a particular group:
.B pki <admin authentication> group-show <group ID>
To add a group:
.B pki <admin authentication> group-add <group ID> --description "description"
To delete a group:
.B pki <admin authentication> group-del <group ID>
To add a user to a group:
.B pki <admin authentication> group-add-member <group ID> <Member ID>
To delete a user from a group:
.B pki <admin authentication> group-remove-member <group ID> <Member ID>
.\".SS Key Management Commands
.\"\fBpki\fP can be used with a KRA to find specific keys and key requests. This will be documented in more detail at a later time.
.SS Security Domain Commands
\fBpki\fP can be used to access certain information from the security domain.
To get an installation token (used when installing a new subsystem within a security domain):
\fBpki <security domain admin authentication> securitydomain-get-install-token --hostname <hostname> --subsystem <subsystem>\fP
To show the contents of the security domain:
\fBpki <security domain admin authentication> securitydomain-show\fP
.SS User Management Commands
All user commands must be executed as an administrator. Some representative commands are shown below. Type \fBpki user\fP to get a list of additional commands.
To list users, use \fBpki user-find\fP. It is possible to select the page size to limit the size of the results. To list all users:
.B pki <admin authentication> user-find
To view a particular user:
.B pki <admin authentication> user-show <user ID>
To add a user:
.B pki <admin authentication> user-add <user ID> --fullName "<full name>"
To delete a user:
.B pki <admin authentication> user-del <user ID>
.SH FILES
.I /usr/bin/pki
.SH AUTHORS
Ade Lee <alee@redhat.com>, Endi Dewata <edewata@redhat.com>, and Matthew Harmsen <mharmsen@redhat.com>. \fBpki\fP was written by the Dogtag project.
.SH COPYRIGHT
Copyright (c) 2012 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt.
|
