INSTALL.SSL.md

   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 build Open vSwitch
   6 with OpenSSL.  SSL support ensures integrity and confidentiality of
   7 the OpenFlow connections, increasing network security.
   8
   9 This file explains how to configure an Open vSwitch to connect to an
  10 OpenFlow controller over SSL.  Refer to [INSTALL.md] for instructions
  11 on building Open vSwitch with SSL support.
  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
  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.
  36
  37     This is the only switch PKI model currently supported by NOX
  38     (http://noxrepo.org).
  39
  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.
  44
  45     This is the only switch PKI model supported by the simple
  46     OpenFlow controller included with Open vSwitch.
  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
  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.
  58
  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.
  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
  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.
  88
  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.
  92
  93 The switchca subdirectory contains switch CA files, analogous to those
  94 in the controllerca subdirectory:
  95
  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.
  99
 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.
 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
 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.
 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
 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.
 147
 148      * sc-cert.pem, the switch certificate, signed by the switch's
 149        own private key.  Its contents are not a secret.
 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
 173      * sc-privkey.pem, the switch private key file.  For
 174        security, the contents of this file must remain secret.
 175
 176      * sc-cert.pem, the switch certificate.  Its contents are
 177        not a secret.
 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
 205        % ovs-pki req sc
 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
 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.
 217
 218      * sc-req.pem, the switch "certificate request", which is
 219        essentially the switch's public key.  Its contents are not a
 220        secret.
 221
 222      * A fingerprint, on stdout.
 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
 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.
 287
 288 Once you have these files, configure ovs-vswitchd to use them using
 289 the ovs-vsctl "set-ssl" command, e.g.:
 290
 291     ovs-vsctl set-ssl /etc/openvswitch/sc-privkey.pem /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem
 292
 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.
 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
 300 machine to the Open vSwitch, then add the --bootstrap option, e.g.:
 301
 302     ovs-vsctl -- --bootstrap set-ssl /etc/openvswitch/sc-privkey.pem /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem
 303
 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.
 308
 309 Reporting Bugs
 310 --------------
 311
 312 Please report problems to bugs@openvswitch.org.
 313
 314 [INSTALL.md]:INSTALL.md