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