]>
Commit | Line | Data |
---|---|---|
91005f03 BP |
1 | .de IQ |
2 | . br | |
3 | . ns | |
4 | . IP "\\$1" | |
5 | .. | |
064af421 BP |
6 | .TH ovs\-pki 8 "May 2008" "Open vSwitch" "Open vSwitch Manual" |
7 | ||
8 | .SH NAME | |
9 | ovs\-pki \- OpenFlow public key infrastructure management utility | |
10 | ||
11 | .SH SYNOPSIS | |
2562714a BP |
12 | Each command takes the form: |
13 | .sp | |
2f446d10 | 14 | \fBovs\-pki\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR] |
064af421 | 15 | .sp |
2562714a | 16 | The implemented commands and their arguments are: |
064af421 BP |
17 | .br |
18 | \fBovs\-pki\fR \fBinit\fR | |
19 | .br | |
2f446d10 | 20 | \fBovs\-pki\fR \fBreq\fR \fIname\fR |
064af421 | 21 | .br |
2f446d10 | 22 | \fBovs\-pki\fR \fBsign\fR \fIname\fR [\fItype\fR] |
064af421 | 23 | .br |
2f446d10 | 24 | \fBovs\-pki\fR \fBreq+sign\fR \fIname\fR [\fItype\fR] |
064af421 | 25 | .br |
2f446d10 | 26 | \fBovs\-pki\fR \fBverify\fR \fIname\fR [\fItype\fR] |
064af421 | 27 | .br |
2f446d10 | 28 | \fBovs\-pki\fR \fBfingerprint\fR \fIfile\fR |
064af421 | 29 | .br |
2f446d10 | 30 | \fBovs\-pki\fR \fBself\-sign\fR \fIname\fR |
064af421 | 31 | .sp |
2f446d10 | 32 | Each \fItype\fR above is a certificate type, either \fBswitch\fR |
064af421 BP |
33 | (default) or \fBcontroller\fR. |
34 | .sp | |
35 | The available options are: | |
36 | .br | |
37 | [\fB\-k\fR \fItype\fR | \fB\-\^\-key=\fItype\fR] | |
c8ab9375 | 38 | .br |
064af421 | 39 | [\fB\-B\fR \fInbits\fR | \fB\-\^\-bits=\fInbits\fR] |
c8ab9375 | 40 | .br |
064af421 | 41 | [\fB\-D\fR \fIfile\fR | \fB\-\^\-dsaparam=\fIfile\fR] |
c8ab9375 | 42 | .br |
064af421 | 43 | [\fB\-b\fR | \fB\-\^\-batch\fR] |
c8ab9375 | 44 | .br |
064af421 | 45 | [\fB\-f\fR | \fB\-\^\-force\fR] |
c8ab9375 | 46 | .br |
064af421 | 47 | [\fB\-d\fR \fIdir\fR | \fB\-\^\-dir=\fR\fIdir\fR] |
c8ab9375 | 48 | .br |
064af421 | 49 | [\fB\-l\fR \fIfile\fR | \fB\-\^\-log=\fIfile\fR] |
064af421 | 50 | .br |
c8ab9375 BP |
51 | [\fB\-h\fR | \fB\-\^\-help\fR] |
52 | .sp | |
064af421 BP |
53 | Some options do not apply to every command. |
54 | ||
55 | .SH DESCRIPTION | |
56 | The \fBovs\-pki\fR program sets up and manages a public key | |
57 | infrastructure for use with OpenFlow. It is intended to be a simple | |
58 | interface for organizations that do not have an established public key | |
59 | infrastructure. Other PKI tools can substitute for or supplement the | |
60 | use of \fBovs\-pki\fR. | |
61 | ||
62 | \fBovs\-pki\fR uses \fBopenssl\fR(1) for certificate management and key | |
63 | generation. | |
64 | ||
65 | .SH "OFFLINE COMMANDS" | |
66 | ||
67 | The following \fBovs\-pki\fR commands support manual PKI | |
68 | administration: | |
69 | ||
70 | .TP | |
71 | \fBinit\fR | |
72 | Initializes a new PKI (by default in directory \fB@PKIDIR@\fR) and populates | |
73 | it with a pair of certificate authorities for controllers and | |
74 | switches. | |
75 | ||
76 | This command should ideally be run on a high\-security machine separate | |
77 | from any OpenFlow controller or switch, called the CA machine. The | |
78 | files \fBpki/controllerca/cacert.pem\fR and | |
79 | \fBpki/switchca/cacert.pem\fR that it produces will need to be copied | |
80 | over to the OpenFlow switches and controllers, respectively. Their | |
81 | contents may safely be made public. | |
82 | ||
83 | By default, \fBovs\-pki\fR generates 2048\-bit RSA keys. The \fB\-B\fR | |
84 | or \fB\-\^\-bits\fR option (see below) may be used to override the key | |
85 | length. The \fB\-k dsa\fR or \fB\-\^\-key=dsa\fR option may be used to use | |
86 | DSA in place of RSA. If DSA is selected, the \fBdsaparam.pem\fR file | |
87 | generated in the new PKI hierarchy must be copied to any machine on | |
88 | which the \fBreq\fR command (see below) will be executed. Its | |
89 | contents may safely be made public. | |
90 | ||
91 | Other files generated by \fBinit\fR may remain on the CA machine. | |
92 | The files \fBpki/controllerca/private/cakey.pem\fR and | |
93 | \fBpki/switchca/private/cakey.pem\fR have particularly sensitive | |
94 | contents that should not be exposed. | |
95 | ||
96 | .TP | |
2f446d10 BP |
97 | \fBreq\fR \fIname\fR |
98 | Generates a new private key named \fIname\fR\fB\-privkey.pem\fR and | |
99 | corresponding certificate request named \fIname\fR\fB\-req.pem\fR. | |
064af421 BP |
100 | The private key can be intended for use by a switch or a controller. |
101 | ||
102 | This command should ideally be run on the switch or controller that | |
103 | will use the private key to identify itself. The file | |
2f446d10 | 104 | \fIname\fR\fB\-req.pem\fR must be copied to the CA machine for signing |
064af421 BP |
105 | with the \fBsign\fR command (below). |
106 | ||
107 | This command will output a fingerprint to stdout as its final step. | |
108 | Write down the fingerprint and take it to the CA machine before | |
109 | continuing with the \fBsign\fR step. | |
110 | ||
111 | When RSA keys are in use (as is the default), \fBreq\fR, unlike the | |
112 | rest of \fBovs\-pki\fR's commands, does not need access to a PKI | |
113 | hierarchy created by \fBovs\-pki init\fR. The \fB\-B\fR or | |
114 | \fB\-\^\-bits\fR option (see below) may be used to specify the number of | |
115 | bits in the generated RSA key. | |
116 | ||
117 | When DSA keys are used (as specified with \fB\-\^\-key=dsa\fR), \fBreq\fR | |
118 | needs access to the \fBdsaparam.pem\fR file created as part of the PKI | |
119 | hierarchy (but not to other files in that tree). By default, | |
120 | \fBovs\-pki\fR looks for this file in \fB@PKIDIR@/dsaparam.pem\fR, but | |
121 | the \fB\-D\fR or \fB\-\^\-dsaparam\fR option (see below) may be used to | |
122 | specify an alternate location. | |
123 | ||
2f446d10 BP |
124 | \fIname\fR\fB\-privkey.pem\fR has sensitive contents that should not be |
125 | exposed. \fIname\fR\fB\-req.pem\fR may be safely made public. | |
064af421 BP |
126 | |
127 | .TP | |
2f446d10 BP |
128 | \fBsign\fR \fIname\fR [\fItype\fR] |
129 | Signs the certificate request named \fIname\fR\fB\-req.pem\fR that was | |
064af421 | 130 | produced in the previous step, producing a certificate named |
2f446d10 | 131 | \fIname\fR\fB\-cert.pem\fR. \fItype\fR, either \fBswitch\fR (default) or |
064af421 BP |
132 | \fBcontroller\fR, indicates the use for which the key is being |
133 | certified. | |
134 | ||
135 | This command must be run on the CA machine. | |
136 | ||
137 | The command will output a fingerprint to stdout and request that you | |
138 | verify that it is the same fingerprint output by the \fBreq\fR | |
139 | command. This ensures that the request being signed is the same one | |
140 | produced by \fBreq\fR. (The \fB\-b\fR or \fB\-\^\-batch\fR option | |
141 | suppresses the verification step.) | |
142 | ||
2f446d10 | 143 | The file \fIname\fR\fB\-cert.pem\fR will need to be copied back to the |
064af421 BP |
144 | switch or controller for which it is intended. Its contents may |
145 | safely be made public. | |
146 | ||
147 | .TP | |
2f446d10 | 148 | \fBreq+sign\fR \fIname\fR [\fItype\fR] |
064af421 BP |
149 | Combines the \fBreq\fR and \fBsign\fR commands into a single step, |
150 | outputting all the files produced by each. The | |
2f446d10 | 151 | \fIname\fR\fB\-privkey.pem\fR and \fIname\fR\fB\-cert.pem\fR files must |
064af421 | 152 | be copied securely to the switch or controller. |
2f446d10 | 153 | \fIname\fR\fB\-privkey.pem\fR has sensitive contents and must not be |
064af421 BP |
154 | exposed in transit. Afterward, it should be deleted from the CA |
155 | machine. | |
156 | ||
157 | This combined method is, theoretically, less secure than the | |
158 | individual steps performed separately on two different machines, | |
159 | because there is additional potential for exposure of the private | |
160 | key. However, it is also more convenient. | |
161 | ||
162 | .TP | |
2f446d10 BP |
163 | \fBverify\fR \fIname\fR [\fItype\fR] |
164 | Verifies that \fIname\fR\fB\-cert.pem\fR is a valid certificate for the | |
165 | given \fItype\fR of use, either \fBswitch\fR (default) or | |
064af421 | 166 | \fBcontroller\fR. If the certificate is valid for this use, it prints |
2f446d10 | 167 | the message ``\fIname\fR\fB\-cert.pem\fR: OK''; otherwise, it prints an |
064af421 BP |
168 | error message. |
169 | ||
170 | .TP | |
2f446d10 BP |
171 | \fBfingerprint\fR \fIfile\fR |
172 | Prints the fingerprint for \fIfile\fR. If \fIfile\fR is a | |
064af421 BP |
173 | certificate, then this is the SHA\-1 digest of the DER encoded version |
174 | of the certificate; otherwise, it is the SHA\-1 digest of the entire | |
175 | file. | |
176 | ||
177 | .TP | |
2f446d10 BP |
178 | \fBself\-sign\fR \fIname\fR |
179 | Signs the certificate request named \fIname\fB\-req.pem\fR using the | |
180 | private key \fIname\fB\-privkey.pem\fR, producing a self-signed | |
181 | certificate named \fIname\fB\-cert.pem\fR. The input files should have | |
064af421 BP |
182 | been produced with \fBovs\-pki req\fR. |
183 | ||
184 | Some controllers accept such self-signed certificates. | |
185 | ||
064af421 | 186 | .SH OPTIONS |
91005f03 BP |
187 | .IP "\fB\-k\fR \fItype\fR" |
188 | .IQ "\fB\-\^\-key=\fItype\fR" | |
064af421 BP |
189 | For the \fBinit\fR command, sets the public key algorithm to use for |
190 | the new PKI hierarchy. For the \fBreq\fR and \fBreq+sign\fR commands, | |
191 | sets the public key algorithm to use for the key to be generated, | |
192 | which must match the value specified on \fBinit\fR. With other | |
193 | commands, the value has no effect. | |
194 | ||
195 | The \fItype\fR may be \fBrsa\fR (the default) or \fBdsa\fR. | |
196 | ||
91005f03 BP |
197 | .IP "\fB\-B\fR \fInbits\fR" |
198 | .IQ "\fB\-\^\-bits=\fInbits\fR" | |
064af421 BP |
199 | Sets the number of bits in the key to be generated. When RSA keys are |
200 | in use, this option affects only the \fBinit\fR, \fBreq\fR, and | |
201 | \fBreq+sign\fR commands, and the same value should be given each time. | |
202 | With DSA keys are in use, this option affects only the \fBinit\fR | |
203 | command. | |
204 | ||
205 | The value must be at least 1024. The default is 2048. | |
206 | ||
91005f03 BP |
207 | .IP "\fB\-D\fR \fIfile\fR" |
208 | .IQ "\fB\-\^\-dsaparam=\fIfile\fR" | |
064af421 BP |
209 | Specifies an alternate location for the \fBdsaparam.pem\fR file |
210 | required by the \fBreq\fR and \fBreq+sign\fR commands. This option | |
211 | affects only these commands, and only when DSA keys are used. | |
212 | ||
213 | The default is \fBdsaparam.pem\fR under the PKI hierarchy. | |
214 | ||
91005f03 BP |
215 | .IP "\fB\-b\fR" |
216 | .IQ "\fB\-\^\-batch\fR" | |
064af421 | 217 | Suppresses the interactive verification of fingerprints that the |
2562714a | 218 | \fBsign\fR command by default requires. |
064af421 | 219 | |
91005f03 BP |
220 | .IP "\fB\-d\fR \fIdir\fR" |
221 | .IQ "\fB\-\^\-dir=\fR\fIdir\fR" | |
064af421 BP |
222 | Specifies the location of the PKI hierarchy to be used or created by |
223 | the command (default: \fB@PKIDIR@\fR). All commands, except \fBreq\fR, | |
224 | need access to a PKI hierarchy. | |
225 | ||
91005f03 BP |
226 | .IP "\fB\-f\fR" |
227 | .IQ "\fB\-\^\-force\fR" | |
064af421 BP |
228 | By default, \fBovs\-pki\fR will not overwrite existing files or |
229 | directories. This option overrides this behavior. | |
230 | ||
91005f03 BP |
231 | .IP "\fB\-l\fR \fIfile\fR" |
232 | .IQ "\fB\-\^\-log=\fIfile\fR" | |
064af421 BP |
233 | Sets the log file to \fIfile\fR. Default: |
234 | \fB@LOGDIR@/ovs\-pki.log\fR. | |
235 | ||
91005f03 BP |
236 | .IP "\fB\-h\fR" |
237 | .IQ "\fB\-\^\-help\fR" | |
064af421 BP |
238 | Prints a help usage message and exits. |
239 | ||
240 | .SH "SEE ALSO" | |
241 | ||
2562714a | 242 | .BR ovs\-controller (8). |