]>
Commit | Line | Data |
---|---|---|
064af421 BP |
1 | .TH ovs\-pki 8 "May 2008" "Open vSwitch" "Open vSwitch Manual" |
2 | ||
3 | .SH NAME | |
4 | ovs\-pki \- OpenFlow public key infrastructure management utility | |
5 | ||
6 | .SH SYNOPSIS | |
7 | \fBovs\-pki\fR [\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS\fR] | |
8 | .sp | |
9 | Stand\-alone commands with their arguments: | |
10 | .br | |
11 | \fBovs\-pki\fR \fBinit\fR | |
12 | .br | |
13 | \fBovs\-pki\fR \fBreq\fR \fINAME\fR | |
14 | .br | |
15 | \fBovs\-pki\fR \fBsign\fR \fINAME\fR [\fITYPE\fR] | |
16 | .br | |
17 | \fBovs\-pki\fR \fBreq+sign\fR \fINAME\fR [\fITYPE\fR] | |
18 | .br | |
19 | \fBovs\-pki\fR \fBverify\fR \fINAME\fR [\fITYPE\fR] | |
20 | .br | |
21 | \fBovs\-pki\fR \fBfingerprint\fR \fIFILE\fR | |
22 | .br | |
4e312e69 | 23 | \fBovs\-pki\fR \fBself\-sign\fR \fINAME\fR |
064af421 BP |
24 | .sp |
25 | The following additional commands manage an online PKI: | |
26 | .br | |
27 | \fBovs\-pki\fR \fBls\fR [\fIPREFIX\fR] [\fITYPE\fR] | |
28 | .br | |
29 | \fBovs\-pki\fR \fBflush\fR [\fITYPE\fR] | |
30 | .br | |
31 | \fBovs\-pki\fR \fBreject\fR \fIPREFIX\fR [\fITYPE\fR] | |
32 | .br | |
33 | \fBovs\-pki\fR \fBapprove\fR \fIPREFIX\fR [\fITYPE\fR] | |
34 | .br | |
35 | \fBovs\-pki\fR \fBprompt\fR [\fITYPE\fR] | |
36 | .br | |
37 | \fBovs\-pki\fR \fBexpire\fR [\fIAGE\fR] | |
38 | .sp | |
39 | Each \fITYPE\fR above is a certificate type, either \fBswitch\fR | |
40 | (default) or \fBcontroller\fR. | |
41 | .sp | |
42 | The available options are: | |
43 | .br | |
44 | [\fB\-k\fR \fItype\fR | \fB\-\^\-key=\fItype\fR] | |
c8ab9375 | 45 | .br |
064af421 | 46 | [\fB\-B\fR \fInbits\fR | \fB\-\^\-bits=\fInbits\fR] |
c8ab9375 | 47 | .br |
064af421 | 48 | [\fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR] |
c8ab9375 | 49 | .br |
064af421 | 50 | [\fB\-b\fR | \fB\-\^\-batch\fR] |
c8ab9375 | 51 | .br |
064af421 | 52 | [\fB\-f\fR | \fB\-\^\-force\fR] |
c8ab9375 | 53 | .br |
064af421 | 54 | [\fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR] |
c8ab9375 | 55 | .br |
064af421 | 56 | [\fB\-l\fR \fIfile\fR | \fB\-\^\-log=\fIfile\fR] |
064af421 | 57 | .br |
c8ab9375 BP |
58 | [\fB\-h\fR | \fB\-\^\-help\fR] |
59 | .sp | |
064af421 BP |
60 | Some options do not apply to every command. |
61 | ||
62 | .SH DESCRIPTION | |
63 | The \fBovs\-pki\fR program sets up and manages a public key | |
64 | infrastructure for use with OpenFlow. It is intended to be a simple | |
65 | interface for organizations that do not have an established public key | |
66 | infrastructure. Other PKI tools can substitute for or supplement the | |
67 | use of \fBovs\-pki\fR. | |
68 | ||
69 | \fBovs\-pki\fR uses \fBopenssl\fR(1) for certificate management and key | |
70 | generation. | |
71 | ||
72 | .SH "OFFLINE COMMANDS" | |
73 | ||
74 | The following \fBovs\-pki\fR commands support manual PKI | |
75 | administration: | |
76 | ||
77 | .TP | |
78 | \fBinit\fR | |
79 | Initializes a new PKI (by default in directory \fB@PKIDIR@\fR) and populates | |
80 | it with a pair of certificate authorities for controllers and | |
81 | switches. | |
82 | ||
83 | This command should ideally be run on a high\-security machine separate | |
84 | from any OpenFlow controller or switch, called the CA machine. The | |
85 | files \fBpki/controllerca/cacert.pem\fR and | |
86 | \fBpki/switchca/cacert.pem\fR that it produces will need to be copied | |
87 | over to the OpenFlow switches and controllers, respectively. Their | |
88 | contents may safely be made public. | |
89 | ||
90 | By default, \fBovs\-pki\fR generates 2048\-bit RSA keys. The \fB\-B\fR | |
91 | or \fB\-\^\-bits\fR option (see below) may be used to override the key | |
92 | length. The \fB\-k dsa\fR or \fB\-\^\-key=dsa\fR option may be used to use | |
93 | DSA in place of RSA. If DSA is selected, the \fBdsaparam.pem\fR file | |
94 | generated in the new PKI hierarchy must be copied to any machine on | |
95 | which the \fBreq\fR command (see below) will be executed. Its | |
96 | contents may safely be made public. | |
97 | ||
98 | Other files generated by \fBinit\fR may remain on the CA machine. | |
99 | The files \fBpki/controllerca/private/cakey.pem\fR and | |
100 | \fBpki/switchca/private/cakey.pem\fR have particularly sensitive | |
101 | contents that should not be exposed. | |
102 | ||
103 | .TP | |
104 | \fBreq\fR \fINAME\fR | |
105 | Generates a new private key named \fINAME\fR\fB\-privkey.pem\fR and | |
106 | corresponding certificate request named \fINAME\fR\fB\-req.pem\fR. | |
107 | The private key can be intended for use by a switch or a controller. | |
108 | ||
109 | This command should ideally be run on the switch or controller that | |
110 | will use the private key to identify itself. The file | |
111 | \fINAME\fR\fB\-req.pem\fR must be copied to the CA machine for signing | |
112 | with the \fBsign\fR command (below). | |
113 | ||
114 | This command will output a fingerprint to stdout as its final step. | |
115 | Write down the fingerprint and take it to the CA machine before | |
116 | continuing with the \fBsign\fR step. | |
117 | ||
118 | When RSA keys are in use (as is the default), \fBreq\fR, unlike the | |
119 | rest of \fBovs\-pki\fR's commands, does not need access to a PKI | |
120 | hierarchy created by \fBovs\-pki init\fR. The \fB\-B\fR or | |
121 | \fB\-\^\-bits\fR option (see below) may be used to specify the number of | |
122 | bits in the generated RSA key. | |
123 | ||
124 | When DSA keys are used (as specified with \fB\-\^\-key=dsa\fR), \fBreq\fR | |
125 | needs access to the \fBdsaparam.pem\fR file created as part of the PKI | |
126 | hierarchy (but not to other files in that tree). By default, | |
127 | \fBovs\-pki\fR looks for this file in \fB@PKIDIR@/dsaparam.pem\fR, but | |
128 | the \fB\-D\fR or \fB\-\^\-dsaparam\fR option (see below) may be used to | |
129 | specify an alternate location. | |
130 | ||
131 | \fINAME\fR\fB\-privkey.pem\fR has sensitive contents that should not be | |
132 | exposed. \fINAME\fR\fB\-req.pem\fR may be safely made public. | |
133 | ||
134 | .TP | |
135 | \fBsign\fR \fINAME\fR [\fITYPE\fR] | |
136 | Signs the certificate request named \fINAME\fR\fB\-req.pem\fR that was | |
137 | produced in the previous step, producing a certificate named | |
138 | \fINAME\fR\fB\-cert.pem\fR. \fITYPE\fR, either \fBswitch\fR (default) or | |
139 | \fBcontroller\fR, indicates the use for which the key is being | |
140 | certified. | |
141 | ||
142 | This command must be run on the CA machine. | |
143 | ||
144 | The command will output a fingerprint to stdout and request that you | |
145 | verify that it is the same fingerprint output by the \fBreq\fR | |
146 | command. This ensures that the request being signed is the same one | |
147 | produced by \fBreq\fR. (The \fB\-b\fR or \fB\-\^\-batch\fR option | |
148 | suppresses the verification step.) | |
149 | ||
150 | The file \fINAME\fR\fB\-cert.pem\fR will need to be copied back to the | |
151 | switch or controller for which it is intended. Its contents may | |
152 | safely be made public. | |
153 | ||
154 | .TP | |
155 | \fBreq+sign\fR \fINAME\fR [\fITYPE\fR] | |
156 | Combines the \fBreq\fR and \fBsign\fR commands into a single step, | |
157 | outputting all the files produced by each. The | |
158 | \fINAME\fR\fB\-privkey.pem\fR and \fINAME\fR\fB\-cert.pem\fR files must | |
159 | be copied securely to the switch or controller. | |
160 | \fINAME\fR\fB\-privkey.pem\fR has sensitive contents and must not be | |
161 | exposed in transit. Afterward, it should be deleted from the CA | |
162 | machine. | |
163 | ||
164 | This combined method is, theoretically, less secure than the | |
165 | individual steps performed separately on two different machines, | |
166 | because there is additional potential for exposure of the private | |
167 | key. However, it is also more convenient. | |
168 | ||
169 | .TP | |
170 | \fBverify\fR \fINAME\fR [\fITYPE\fR] | |
171 | Verifies that \fINAME\fR\fB\-cert.pem\fR is a valid certificate for the | |
172 | given \fITYPE\fR of use, either \fBswitch\fR (default) or | |
173 | \fBcontroller\fR. If the certificate is valid for this use, it prints | |
174 | the message ``\fINAME\fR\fB\-cert.pem\fR: OK''; otherwise, it prints an | |
175 | error message. | |
176 | ||
177 | .TP | |
178 | \fBfingerprint\fR \fIFILE\fR | |
179 | Prints the fingerprint for \fIFILE\fR. If \fIFILE\fR is a | |
180 | certificate, then this is the SHA\-1 digest of the DER encoded version | |
181 | of the certificate; otherwise, it is the SHA\-1 digest of the entire | |
182 | file. | |
183 | ||
184 | .TP | |
4e312e69 | 185 | \fBself\-sign\fR \fINAME\fR |
064af421 | 186 | Signs the certificate request named \fINAME\fB\-req.pem\fR using the |
4e312e69 | 187 | private key \fINAME\fB\-privkey.pem\fR, producing a self-signed |
8b830828 | 188 | certificate named \fINAME\fB\-cert.pem\fR. The input files should have |
064af421 BP |
189 | been produced with \fBovs\-pki req\fR. |
190 | ||
191 | Some controllers accept such self-signed certificates. | |
192 | ||
193 | .SH "ONLINE COMMANDS" | |
194 | ||
195 | An OpenFlow PKI can be administered online, in conjunction with | |
196 | .BR ovs\-pki\-cgi (8) | |
197 | and a web server such as Apache: | |
198 | ||
199 | .IP \(bu | |
200 | The web server exports the contents of the PKI via HTTP. All files in | |
201 | a PKI hierarchy files may be made public, except for the files | |
202 | \fBpki/controllerca/private/cakey.pem\fR and | |
203 | \fBpki/switchca/private/cakey.pem\fR, which must not be exposed. | |
204 | ||
205 | .IP \(bu | |
206 | \fBovs\-pki\-cgi\fR allows newly generated certificate requests for | |
207 | controllers and switches to be uploaded into the | |
208 | \fBpki/controllerca/incoming\fR and \fBpki/switchca/incoming\fR | |
209 | directories, respectively. Uploaded certificate requests are stored | |
210 | in those directories under names of the form | |
211 | \fIFINGERPRINT\fB\-req.pem\fR, which \fIFINGERPRINT\fR is the SHA\-1 | |
212 | hash of the file. | |
213 | ||
214 | .IP \(bu | |
215 | These \fBovs\-pki\fR commands allow incoming certificate requests to | |
216 | be approved or rejected, in a form are suitable for use by humans or | |
217 | other software. | |
218 | ||
219 | .PP | |
220 | The following \fBovs\-pki\fR commands support online administration: | |
221 | ||
222 | .TP | |
223 | \fBovs\-pki\fR \fBls\fR [\fIPREFIX\fR] [\fITYPE\fR] | |
224 | Lists all of the incoming certificate requests of the given \fITYPE\fR | |
225 | (either \fBswitch\fR, the default, or \fBcontroller\fR). If | |
226 | \fIPREFIX\fR, which must be at least 4 characters long, is specified, | |
227 | it causes the list to be limited to files whose names begin with | |
228 | \fIPREFIX\fR. This is useful, for example, to avoid typing in an | |
229 | entire fingerprint when checking that a specific certificate request | |
230 | has been received. | |
231 | ||
232 | .TP | |
233 | \fBovs\-pki\fR \fBflush\fR [\fITYPE\fR] | |
234 | Deletes all certificate requests of the given \fITYPE\fR. | |
235 | ||
236 | .TP | |
237 | \fBovs\-pki\fR \fBreject\fR \fIPREFIX\fR [\fITYPE\fR] | |
238 | Rejects the certificate request whose name begins with \fIPREFIX\fR, | |
239 | which must be at least 4 characters long, of the given type (either | |
240 | \fBswitch\fR, the default, or \fBcontroller\fR). \fIPREFIX\fR must | |
241 | match exactly one certificate request; its purpose is to allow the | |
242 | user to type fewer characters, not to match multiple certificate | |
243 | requests. | |
244 | ||
245 | .TP | |
246 | \fBovs\-pki\fR \fBapprove\fR \fIPREFIX\fR [\fITYPE\fR] | |
247 | Approves the certificate request whose name begins with \fIPREFIX\fR, | |
248 | which must be at least 4 characters long, of the given \fITYPE\fR | |
249 | (either \fBswitch\fR, the default, or \fBcontroller\fR). \fIPREFIX\fR | |
250 | must match exactly one certificate request; its purpose is to allow | |
251 | the user to type fewer characters, not to match multiple certificate | |
252 | requests. | |
253 | ||
254 | The command will output a fingerprint to stdout and request that you | |
255 | verify that it is correct. (The \fB\-b\fR or \fB\-\^\-batch\fR option | |
256 | suppresses the verification step.) | |
257 | ||
258 | .TP | |
259 | \fBovs\-pki\fR \fBprompt\fR [\fITYPE\fR] | |
260 | Prompts the user for each incoming certificate request of the given | |
261 | \fITYPE\fR (either \fBswitch\fR, the default, or \fBcontroller\fR). | |
262 | Based on the certificate request's fingerprint, the user is given the | |
263 | option of approving, rejecting, or skipping the certificate request. | |
264 | ||
265 | .TP | |
266 | \fBovs\-pki\fR \fBexpire\fR [\fIAGE\fR] | |
267 | ||
268 | Rejects all the incoming certificate requests, of either type, that is | |
269 | older than \fIAGE\fR, which must in one of the forms \fIN\fBs\fR, | |
270 | \fIN\fBmin\fR, \fIN\fBh\fR, \fIN\fBday\fR. The default is \fB1day\fR. | |
271 | ||
272 | .SH OPTIONS | |
273 | .TP | |
274 | \fB\-k\fR \fItype\fR | \fB\-\^\-key=\fItype\fR | |
275 | For the \fBinit\fR command, sets the public key algorithm to use for | |
276 | the new PKI hierarchy. For the \fBreq\fR and \fBreq+sign\fR commands, | |
277 | sets the public key algorithm to use for the key to be generated, | |
278 | which must match the value specified on \fBinit\fR. With other | |
279 | commands, the value has no effect. | |
280 | ||
281 | The \fItype\fR may be \fBrsa\fR (the default) or \fBdsa\fR. | |
282 | ||
283 | .TP | |
284 | \fB\-B\fR \fInbits\fR | \fB\-\^\-bits=\fInbits\fR | |
285 | Sets the number of bits in the key to be generated. When RSA keys are | |
286 | in use, this option affects only the \fBinit\fR, \fBreq\fR, and | |
287 | \fBreq+sign\fR commands, and the same value should be given each time. | |
288 | With DSA keys are in use, this option affects only the \fBinit\fR | |
289 | command. | |
290 | ||
291 | The value must be at least 1024. The default is 2048. | |
292 | ||
293 | .TP | |
294 | \fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR | |
295 | Specifies an alternate location for the \fBdsaparam.pem\fR file | |
296 | required by the \fBreq\fR and \fBreq+sign\fR commands. This option | |
297 | affects only these commands, and only when DSA keys are used. | |
298 | ||
299 | The default is \fBdsaparam.pem\fR under the PKI hierarchy. | |
300 | ||
301 | .TP | |
302 | \fB\-b\fR | \fB\-\^\-batch\fR | |
303 | Suppresses the interactive verification of fingerprints that the | |
304 | \fBsign\fR and \fBapprove\fR commands by default require. | |
305 | ||
306 | .TP | |
307 | \fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR | |
308 | Specifies the location of the PKI hierarchy to be used or created by | |
309 | the command (default: \fB@PKIDIR@\fR). All commands, except \fBreq\fR, | |
310 | need access to a PKI hierarchy. | |
311 | ||
312 | .TP | |
313 | \fB\-f\fR | \fB\-\^\-force\fR | |
314 | By default, \fBovs\-pki\fR will not overwrite existing files or | |
315 | directories. This option overrides this behavior. | |
316 | ||
317 | .TP | |
318 | \fB\-l\fR \fIfile\fR | \fB\-\^\-log=\fIfile\fR | |
319 | Sets the log file to \fIfile\fR. Default: | |
320 | \fB@LOGDIR@/ovs\-pki.log\fR. | |
321 | ||
322 | .TP | |
323 | \fB\-h\fR | \fB\-\^\-help\fR | |
324 | Prints a help usage message and exits. | |
325 | ||
326 | .SH "SEE ALSO" | |
327 | ||
8cd4882f | 328 | .BR ovs\-controller (8), |
8cd4882f | 329 | .BR ovs\-pki\-cgi (8) |