INSTALL.SSL

   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
 317 Please report problems to bugs@openvswitch.org.