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