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