1 Configuring Open vSwitch for SSL
2 ================================
4 If you plan to configure Open vSwitch to connect across the network to
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.
9 This file explains how to configure an Open vSwitch to connect to an
10 OpenFlow controller over SSL. Refer to INSTALL for instructions on
11 building Open vSwitch with SSL support.
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
18 This document assumes basic familiarity with public-key cryptography
19 and public-key infrastructure.
21 SSL Concepts for OpenFlow
22 -------------------------
24 This section is an introduction to the public-key infrastructure
25 architectures that Open vSwitch supports for SSL authentication.
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:
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.
37 This is the only switch PKI model currently supported by NOX
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.
45 This is the only switch PKI model supported by the simple
46 OpenFlow controller included with Open vSwitch.
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:
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.
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
65 Establishing a Public Key Infrastructure
66 ----------------------------------------
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
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").
81 The pki directory contains two important subdirectories. The
82 controllerca subdirectory contains controller CA files, including the
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.
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.
93 The switchca subdirectory contains switch CA files, analogous to those
94 in the controllerca subdirectory:
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.
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.
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
109 CONTROLLER KEY GENERATION
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:
115 % ovs-pki req+sign ctl controller
117 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
118 controller for its use at runtime. If you were to use test-controller,
119 the simple OpenFlow controller included with Open vSwitch, then the
120 --private-key and --certificate options, respectively, would point to
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
127 SWITCH KEY GENERATION WITH SELF-SIGNED CERTIFICATES
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.
133 1. Run the following command on the Open vSwitch itself:
135 % ovs-pki self-sign sc
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
142 The "ovs-pki self-sign" command has the following output:
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.
148 * sc-cert.pem, the switch certificate, signed by the switch's
149 own private key. Its contents are not a secret.
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.)
156 3. Configure Open vSwitch to use the keys and certificates (see
157 "Configuring SSL Support", below).
159 SWITCH KEY GENERATION WITH A SWITCH PKI (EASY METHOD)
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.
167 1. Run the following on the machine that contains the PKI structure:
169 % ovs-pki req+sign sc switch
171 This command has the following output:
173 * sc-privkey.pem, the switch private key file. For
174 security, the contents of this file must remain secret.
176 * sc-cert.pem, the switch certificate. Its contents are
179 2. Copy sc-privkey.pem and sc-cert.pem, plus controllerca/cacert.pem,
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
188 (Don't delete controllerca/cacert.pem! It is not
189 security-sensitive and you will need it to configure additional
192 4. Configure Open vSwitch to use the keys and certificates (see
193 "Configuring SSL Support", below).
195 SWITCH KEY GENERATION WITH A SWITCH PKI (MORE SECURE)
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
203 1. Run the following command on the Open vSwitch itself:
205 % ovs-pki req sc switch
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
212 The "ovs-pki req" command has the following output:
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.
218 * sc-req.pem, the switch "certificate request", which is
219 essentially the switch's public key. Its contents are not a
222 * A fingerprint, on stdout.
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.
227 3. On the machine that contains the PKI structure, run:
229 % ovs-pki sign sc switch
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".
235 "ovs-pki sign" creates a file named sc-cert.pem, which is the
236 switch certificate. Its contents are not a secret.
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
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.)
247 5. Configure Open vSwitch to use the keys and certificates (see
248 "Configuring SSL Support", below).
250 Configuring SSL Support
251 -----------------------
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:
258 - A private key file, which contains the private half of an RSA or
261 This file can be generated on the Open vSwitch itself, for the
262 greatest security, or it can be generated elsewhere and copied
265 The contents of the private key file are secret and must not be
268 - A certificate file, which certifies that the private key is that
269 of a trustworthy Open vSwitch.
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
276 The certificate file itself is not a secret.
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
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
288 Once you have these files, configure ovs-vswitchd to use them using
289 the ovs-vsctl "set-ssl" command, e.g.:
291 ovs-vsctl set-ssl /etc/openvswitch/sc-privkey.pem /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem
293 Substitute the correct file names, of course, if they differ from the
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.
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
300 machine to the Open vSwitch, then add the --bootstrap option, e.g.:
302 ovs-vsctl -- --bootstrap set-ssl /etc/openvswitch/sc-privkey.pem /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem
304 After you have added all of these configuration keys, you may specify
305 "ssl:" connection methods elsewhere in the configuration database.
306 "tcp:" connection methods are still allowed even after SSL has been
307 configured, so for security you should use only "ssl:" connections.
312 Please report problems to bugs@openvswitch.org.