]>
Commit | Line | Data |
---|---|---|
542cc9bb TG |
1 | Configuring Open vSwitch for SSL |
2 | ================================ | |
4b11d5e8 BP |
3 | |
4 | If you plan to configure Open vSwitch to connect across the network to | |
f272ec73 BP |
5 | an OpenFlow controller, then we recommend that you build Open vSwitch |
6 | with OpenSSL. SSL support ensures integrity and confidentiality of | |
7 | the OpenFlow connections, increasing network security. | |
4b11d5e8 BP |
8 | |
9 | This file explains how to configure an Open vSwitch to connect to an | |
9feb1017 TG |
10 | OpenFlow controller over SSL. Refer to [INSTALL.md] for instructions |
11 | on building Open vSwitch with SSL support. | |
4b11d5e8 BP |
12 | |
13 | Open vSwitch uses TLS version 1.0 or later (TLSv1), as specified by | |
14 | RFC 2246, which is very similar to SSL version 3.0. TLSv1 was | |
15 | released in January 1999, so all current software and hardware should | |
16 | implement it. | |
17 | ||
18 | This document assumes basic familiarity with public-key cryptography | |
19 | and public-key infrastructure. | |
20 | ||
21 | SSL Concepts for OpenFlow | |
22 | ------------------------- | |
23 | ||
24 | This section is an introduction to the public-key infrastructure | |
25 | architectures that Open vSwitch supports for SSL authentication. | |
26 | ||
27 | To connect over SSL, every Open vSwitch must have a unique | |
28 | private/public key pair and a certificate that signs that public key. | |
29 | Typically, the Open vSwitch generates its own public/private key pair. | |
30 | There are two common ways to obtain a certificate for a switch: | |
31 | ||
542cc9bb TG |
32 | * Self-signed certificates: The Open vSwitch signs its certificate |
33 | with its own private key. In this case, each switch must be | |
34 | individually approved by the OpenFlow controller(s), since there | |
35 | is no central authority. | |
4b11d5e8 | 36 | |
542cc9bb TG |
37 | This is the only switch PKI model currently supported by NOX |
38 | (http://noxrepo.org). | |
4b11d5e8 | 39 | |
542cc9bb TG |
40 | * Switch certificate authority: A certificate authority (the |
41 | "switch CA") signs each Open vSwitch's public key. The OpenFlow | |
42 | controllers then check that any connecting switches' | |
43 | certificates are signed by that certificate authority. | |
4b11d5e8 | 44 | |
542cc9bb TG |
45 | This is the only switch PKI model supported by the simple |
46 | OpenFlow controller included with Open vSwitch. | |
4b11d5e8 BP |
47 | |
48 | Each Open vSwitch must also have a copy of the CA certificate for the | |
49 | certificate authority that signs OpenFlow controllers' keys (the | |
50 | "controller CA" certificate). Typically, the same controller CA | |
51 | certificate is installed on all of the switches within a given | |
52 | administrative unit. There are two common ways for a switch to obtain | |
53 | the controller CA certificate: | |
54 | ||
542cc9bb TG |
55 | * Manually copy the certificate to the switch through some secure |
56 | means, e.g. using a USB flash drive, or over the network with | |
57 | "scp", or even FTP or HTTP followed by manual verification. | |
4b11d5e8 | 58 | |
542cc9bb TG |
59 | * Open vSwitch "bootstrap" mode, in which Open vSwitch accepts and |
60 | saves the controller CA certificate that it obtains from the | |
61 | OpenFlow controller on its first connection. Thereafter the | |
62 | switch will only connect to controllers signed by the same CA | |
63 | certificate. | |
4b11d5e8 BP |
64 | |
65 | Establishing a Public Key Infrastructure | |
66 | ---------------------------------------- | |
67 | ||
68 | Open vSwitch can make use of your existing public key infrastructure. | |
69 | If you already have a PKI, you may skip forward to the next section. | |
70 | Otherwise, if you do not have a PKI, the ovs-pki script included with | |
71 | Open vSwitch can help. To create an initial PKI structure, invoke it | |
72 | as: | |
73 | ||
74 | % ovs-pki init | |
75 | ||
76 | to create and populate a new PKI directory. The default location for | |
77 | the PKI directory depends on how the Open vSwitch tree was configured | |
78 | (to see the configured default, look for the --dir option description | |
79 | in the output of "ovs-pki --help"). | |
80 | ||
81 | The pki directory contains two important subdirectories. The | |
82 | controllerca subdirectory contains controller CA files, including the | |
83 | following: | |
84 | ||
542cc9bb TG |
85 | - cacert.pem: Root certificate for the controller certificate |
86 | authority. Each Open vSwitch must have a copy of this file to | |
87 | allow it to authenticate valid controllers. | |
4b11d5e8 | 88 | |
542cc9bb TG |
89 | - private/cakey.pem: Private signing key for the controller |
90 | certificate authority. This file must be kept secret. There is | |
91 | no need for switches or controllers to have a copy of it. | |
4b11d5e8 BP |
92 | |
93 | The switchca subdirectory contains switch CA files, analogous to those | |
94 | in the controllerca subdirectory: | |
95 | ||
542cc9bb TG |
96 | - cacert.pem: Root certificate for the switch certificate |
97 | authority. The OpenFlow controller must have this file to | |
98 | enable it to authenticate valid switches. | |
4b11d5e8 | 99 | |
542cc9bb TG |
100 | - private/cakey.pem: Private signing key for the switch |
101 | certificate authority. This file must be kept secret. There is | |
102 | no need for switches or controllers to have a copy of it. | |
4b11d5e8 BP |
103 | |
104 | After you create the initial structure, you can create keys and | |
105 | certificates for switches and controllers with ovs-pki. Refer to the | |
106 | ovs-pki(8) manage for complete details. A few examples of its use | |
107 | follow: | |
108 | ||
109 | CONTROLLER KEY GENERATION | |
110 | ||
111 | To create a controller private key and certificate in files named | |
112 | ctl-privkey.pem and ctl-cert.pem, run the following on the machine | |
113 | that contains the PKI structure: | |
114 | ||
115 | % ovs-pki req+sign ctl controller | |
116 | ||
117 | ctl-privkey.pem and ctl-cert.pem would need to be copied to the | |
0bc1b46a BP |
118 | controller for its use at runtime. If, for testing purposes, you were |
119 | to use ovs-testcontroller, the simple OpenFlow controller included | |
120 | with Open vSwitch, then the --private-key and --certificate options, | |
121 | respectively, would point to these files. | |
4b11d5e8 BP |
122 | |
123 | It is very important to make sure that no stray copies of | |
124 | ctl-privkey.pem are created, because they could be used to impersonate | |
125 | the controller. | |
126 | ||
127 | SWITCH KEY GENERATION WITH SELF-SIGNED CERTIFICATES | |
128 | ||
129 | If you are using self-signed certificates (see "SSL Concepts for | |
130 | OpenFlow"), this is one way to create an acceptable certificate for | |
131 | your controller to approve. | |
132 | ||
133 | 1. Run the following command on the Open vSwitch itself: | |
134 | ||
135 | % ovs-pki self-sign sc | |
136 | ||
137 | (This command does not require a copy of any of the PKI files | |
138 | generated by "ovs-pki init", and you should not copy them to the | |
139 | switch because some of them have contents that must remain secret | |
140 | for security.) | |
141 | ||
142 | The "ovs-pki self-sign" command has the following output: | |
143 | ||
542cc9bb TG |
144 | * sc-privkey.pem, the switch private key file. For security, |
145 | the contents of this file must remain secret. There is | |
146 | ordinarily no need to copy this file off the Open vSwitch. | |
4b11d5e8 | 147 | |
542cc9bb TG |
148 | * sc-cert.pem, the switch certificate, signed by the switch's |
149 | own private key. Its contents are not a secret. | |
4b11d5e8 BP |
150 | |
151 | 2. Optionally, copy controllerca/cacert.pem from the machine that has | |
152 | the OpenFlow PKI structure and verify that it is correct. | |
153 | (Otherwise, you will have to use CA certificate bootstrapping when | |
154 | you configure Open vSwitch in the next step.) | |
155 | ||
156 | 3. Configure Open vSwitch to use the keys and certificates (see | |
157 | "Configuring SSL Support", below). | |
158 | ||
159 | SWITCH KEY GENERATION WITH A SWITCH PKI (EASY METHOD) | |
160 | ||
161 | If you are using a switch PKI (see "SSL Concepts for OpenFlow", | |
162 | above), this method of switch key generation is a little easier than | |
163 | the alternate method described below, but it is also a little less | |
164 | secure because it requires copying a sensitive private key from file | |
165 | from the machine hosting the PKI to the switch. | |
166 | ||
167 | 1. Run the following on the machine that contains the PKI structure: | |
168 | ||
169 | % ovs-pki req+sign sc switch | |
170 | ||
171 | This command has the following output: | |
172 | ||
542cc9bb TG |
173 | * sc-privkey.pem, the switch private key file. For |
174 | security, the contents of this file must remain secret. | |
4b11d5e8 | 175 | |
542cc9bb TG |
176 | * sc-cert.pem, the switch certificate. Its contents are |
177 | not a secret. | |
4b11d5e8 BP |
178 | |
179 | 2. Copy sc-privkey.pem and sc-cert.pem, plus controllerca/cacert.pem, | |
180 | to the Open vSwitch. | |
181 | ||
182 | 3. Delete the copies of sc-privkey.pem and sc-cert.pem on the PKI | |
183 | machine and any other copies that may have been made in transit. | |
184 | It is very important to make sure that there are no stray copies of | |
185 | sc-privkey.pem, because they could be used to impersonate the | |
186 | switch. | |
187 | ||
188 | (Don't delete controllerca/cacert.pem! It is not | |
189 | security-sensitive and you will need it to configure additional | |
190 | switches.) | |
191 | ||
192 | 4. Configure Open vSwitch to use the keys and certificates (see | |
193 | "Configuring SSL Support", below). | |
194 | ||
195 | SWITCH KEY GENERATION WITH A SWITCH PKI (MORE SECURE) | |
196 | ||
197 | If you are using a switch PKI (see "SSL Concepts for OpenFlow", | |
198 | above), then, compared to the previous method, the method described | |
199 | here takes a little more work, but it does not involve copying the | |
200 | private key from one machine to another, so it may also be a little | |
201 | more secure. | |
202 | ||
203 | 1. Run the following command on the Open vSwitch itself: | |
204 | ||
5680a1a5 | 205 | % ovs-pki req sc |
4b11d5e8 BP |
206 | |
207 | (This command does not require a copy of any of the PKI files | |
208 | generated by "ovs-pki init", and you should not copy them to the | |
209 | switch because some of them have contents that must remain secret | |
210 | for security.) | |
211 | ||
212 | The "ovs-pki req" command has the following output: | |
213 | ||
542cc9bb TG |
214 | * sc-privkey.pem, the switch private key file. For security, |
215 | the contents of this file must remain secret. There is | |
216 | ordinarily no need to copy this file off the Open vSwitch. | |
4b11d5e8 | 217 | |
542cc9bb TG |
218 | * sc-req.pem, the switch "certificate request", which is |
219 | essentially the switch's public key. Its contents are not a | |
220 | secret. | |
4b11d5e8 | 221 | |
542cc9bb | 222 | * A fingerprint, on stdout. |
4b11d5e8 BP |
223 | |
224 | 2. Write the fingerprint down on a slip of paper and copy sc-req.pem | |
225 | to the machine that contains the PKI structure. | |
226 | ||
227 | 3. On the machine that contains the PKI structure, run: | |
228 | ||
229 | % ovs-pki sign sc switch | |
230 | ||
231 | This command will output a fingerprint to stdout and request that | |
232 | you verify it. Check that it is the same as the fingerprint that | |
233 | you wrote down on the slip of paper before you answer "yes". | |
234 | ||
235 | "ovs-pki sign" creates a file named sc-cert.pem, which is the | |
236 | switch certificate. Its contents are not a secret. | |
237 | ||
238 | 4. Copy the generated sc-cert.pem, plus controllerca/cacert.pem from | |
239 | the PKI structure, to the Open vSwitch, and verify that they were | |
240 | copied correctly. | |
241 | ||
242 | You may delete sc-cert.pem from the machine that hosts the PKI | |
243 | structure now, although it is not important that you do so. (Don't | |
244 | delete controllerca/cacert.pem! It is not security-sensitive and | |
245 | you will need it to configure additional switches.) | |
246 | ||
247 | 5. Configure Open vSwitch to use the keys and certificates (see | |
248 | "Configuring SSL Support", below). | |
249 | ||
250 | Configuring SSL Support | |
251 | ----------------------- | |
252 | ||
253 | SSL configuration requires three additional configuration files. The | |
254 | first two of these are unique to each Open vSwitch. If you used the | |
255 | instructions above to build your PKI, then these files will be named | |
256 | sc-privkey.pem and sc-cert.pem, respectively: | |
257 | ||
258 | - A private key file, which contains the private half of an RSA or | |
259 | DSA key. | |
260 | ||
261 | This file can be generated on the Open vSwitch itself, for the | |
262 | greatest security, or it can be generated elsewhere and copied | |
263 | to the Open vSwitch. | |
264 | ||
265 | The contents of the private key file are secret and must not be | |
266 | exposed. | |
267 | ||
268 | - A certificate file, which certifies that the private key is that | |
269 | of a trustworthy Open vSwitch. | |
270 | ||
271 | This file has to be generated on a machine that has the private | |
272 | key for the switch certification authority, which should not be | |
273 | an Open vSwitch; ideally, it should be a machine that is not | |
274 | networked at all. | |
275 | ||
276 | The certificate file itself is not a secret. | |
277 | ||
278 | The third configuration file is typically the same across all the | |
279 | switches in a given administrative unit. If you used the | |
280 | instructions above to build your PKI, then this file will be named | |
281 | cacert.pem: | |
282 | ||
542cc9bb TG |
283 | - The root certificate for the controller certificate authority. |
284 | The Open vSwitch verifies it that is authorized to connect to an | |
285 | OpenFlow controller by verifying a signature against this CA | |
286 | certificate. | |
4b11d5e8 | 287 | |
3b12adda BP |
288 | Once you have these files, configure ovs-vswitchd to use them using |
289 | the ovs-vsctl "set-ssl" command, e.g.: | |
4b11d5e8 | 290 | |
bc391960 | 291 | ovs-vsctl set-ssl /etc/openvswitch/sc-privkey.pem /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem |
4b11d5e8 BP |
292 | |
293 | Substitute the correct file names, of course, if they differ from the | |
3b12adda BP |
294 | ones used above. You should use absolute file names (ones that begin |
295 | with "/"), because ovs-vswitchd's current directory is unrelated to | |
296 | the one from which you run ovs-vsctl. | |
4b11d5e8 BP |
297 | |
298 | If you are using self-signed certificates (see "SSL Concepts for | |
299 | OpenFlow") and you did not copy controllerca/cacert.pem from the PKI | |
3b12adda | 300 | machine to the Open vSwitch, then add the --bootstrap option, e.g.: |
4b11d5e8 | 301 | |
bc391960 | 302 | ovs-vsctl -- --bootstrap set-ssl /etc/openvswitch/sc-privkey.pem /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem |
4b11d5e8 BP |
303 | |
304 | After you have added all of these configuration keys, you may specify | |
3b12adda | 305 | "ssl:" connection methods elsewhere in the configuration database. |
4b11d5e8 BP |
306 | "tcp:" connection methods are still allowed even after SSL has been |
307 | configured, so for security you should use only "ssl:" connections. | |
308 | ||
309 | Reporting Bugs | |
310 | -------------- | |
311 | ||
37ea6436 | 312 | Please report problems to bugs@openvswitch.org. |
9feb1017 TG |
313 | |
314 | [INSTALL.md]:INSTALL.md |