From patchwork Sun Oct 30 13:29:56 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 688934 X-Patchwork-Delegate: rbryant@redhat.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from archives.nicira.com (archives.nicira.com [96.126.127.54]) by ozlabs.org (Postfix) with ESMTP id 3t6JMz3wNCz9t1T for ; Mon, 31 Oct 2016 00:33:03 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b=Qyagd4Zm; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id BDE31102FC; Sun, 30 Oct 2016 06:33:02 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx3v3.cudamail.com (mx3.cudamail.com [64.34.241.5]) by archives.nicira.com (Postfix) with ESMTPS id C5A08102C4 for ; Sun, 30 Oct 2016 06:33:00 -0700 (PDT) Received: from bar6.cudamail.com (localhost [127.0.0.1]) by mx3v3.cudamail.com (Postfix) with ESMTPS id 5E4E416402C for ; Sun, 30 Oct 2016 07:33:00 -0600 (MDT) X-ASG-Debug-ID: 1477834377-0b32372042228760001-byXFYA Received: from mx3-pf1.cudamail.com ([192.168.14.2]) by bar6.cudamail.com with ESMTP id v3LH2SEq5OUvljVU (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sun, 30 Oct 2016 07:32:57 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.14.2 Received: from unknown (HELO bongo.tulip.relay.mailchannels.net) (23.83.218.21) by mx3-pf1.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 30 Oct 2016 13:32:56 -0000 Received-SPF: none (mx3-pf1.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 23.83.218.21 X-Barracuda-RBL-IP: 23.83.218.21 X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id AF8401BCDB5 for ; Sun, 30 Oct 2016 13:32:51 +0000 (UTC) Received: from one.mxroute.com (ip-10-229-2-62.us-west-2.compute.internal [10.229.2.62]) by relay.mailchannels.net (Postfix) with ESMTPA id 122C81BD1B5 for ; Sun, 30 Oct 2016 13:32:51 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.107.128.240]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Sun, 30 Oct 2016 13:32:51 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1477834371472:342330264 X-MC-Ingress-Time: 1477834371471 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=aYwVkC0L7Ur5VcZDiuXDpiWh9+usuLkpwpsyVHgFN5o=; b=Qyagd4ZmyGoqV1wAOk9F/+CKZH rLQsznPiNqrBF6RuWV6DLljAbdqhzTJrFWYzV5pfpdu6i9oF23zDXiCWssdxtTYukpt2qekenBuim 4UwII3y5ScldK7HIUL7FAORakxt6nK/YZVzrSOMd3PCpyFOAVKTji4HmU4y+FMke2a7D1EagS21CZ lEdcUe4rW8h+POm9UVvIZMDjcSKMR+YHmY+aRJjf6oG08dzlkgp4gNlu2XgbB2pMVX4AqjT8KLZiT WQSzP+NoMRWU6tXY8b4p7jl8P/KHhHjJu6mwqBIMGU4P+V6mFZgP/jY038LGjuFPp+7uPzkNr+v11 kfdu6ggw==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-V1-1029004211 X-CudaMail-DTE: 103016 X-CudaMail-Originating-IP: 23.83.218.21 Date: Sun, 30 Oct 2016 13:29:56 +0000 X-ASG-Orig-Subj: [##CM-V1-1029004211##][PATCH 10/23] doc: Convert INSTALL.SSL to rST Message-Id: <1477834209-11414-11-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1477834209-11414-1-git-send-email-stephen@that.guru> References: <1477834209-11414-1-git-send-email-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-9.2 X-AuthUser: stephen@that.guru X-GBUdb-Analysis: 0, 23.83.218.21, Ugly c=0.165853 p=-0.2 Source Normal X-MessageSniffer-Rules: 0-0-0-32767-c X-Barracuda-Connect: UNKNOWN[192.168.14.2] X-Barracuda-Start-Time: 1477834377 X-Barracuda-Encrypted: DHE-RSA-AES256-SHA X-Barracuda-URL: https://web.cudamail.com:443/cgi-mod/mark.cgi X-Barracuda-BRTS-Status: 1 X-Virus-Scanned: by bsmtpd at cudamail.com X-Barracuda-Spam-Score: 1.10 X-Barracuda-Spam-Status: No, SCORE=1.10 using global scores of TAG_LEVEL=3.5 QUARANTINE_LEVEL=1000.0 KILL_LEVEL=4.0 tests=BSF_SC0_MV0713, BSF_SC5_MJ1963, DKIM_SIGNED, RDNS_NONE X-Barracuda-Spam-Report: Code version 3.2, rules version 3.2.3.34168 Rule breakdown below pts rule name description ---- ---------------------- -------------------------------------------------- 0.00 DKIM_SIGNED Domain Keys Identified Mail: message has a signature 0.10 RDNS_NONE Delivered to trusted network by a host with no rDNS 0.50 BSF_SC0_MV0713 Custom rule MV0713 0.50 BSF_SC5_MJ1963 Custom Rule MJ1963 Subject: [ovs-dev] [PATCH 10/23] doc: Convert INSTALL.SSL to rST X-BeenThere: dev@openvswitch.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dev-bounces@openvswitch.org Sender: "dev" Signed-off-by: Stephen Finucane --- INSTALL.SSL.md | 314 ------------------------------------- INSTALL.SSL.rst | 338 ++++++++++++++++++++++++++++++++++++++++ Makefile.am | 2 +- README.rst | 2 +- rhel/openvswitch-fedora.spec.in | 2 +- rhel/openvswitch.spec.in | 2 +- 6 files changed, 342 insertions(+), 318 deletions(-) delete mode 100644 INSTALL.SSL.md create mode 100644 INSTALL.SSL.rst diff --git a/INSTALL.SSL.md b/INSTALL.SSL.md deleted file mode 100644 index e341524..0000000 --- a/INSTALL.SSL.md +++ /dev/null @@ -1,314 +0,0 @@ -Configuring Open vSwitch for SSL -================================ - -If you plan to configure Open vSwitch to connect across the network to -an OpenFlow controller, then we recommend that you build Open vSwitch -with OpenSSL. SSL support ensures integrity and confidentiality of -the OpenFlow connections, increasing network security. - -This file explains how to configure an Open vSwitch to connect to an -OpenFlow controller over SSL. Refer to [INSTALL.rst] for instructions -on building Open vSwitch with SSL support. - -Open vSwitch uses TLS version 1.0 or later (TLSv1), as specified by -RFC 2246, which is very similar to SSL version 3.0. TLSv1 was -released in January 1999, so all current software and hardware should -implement it. - -This document assumes basic familiarity with public-key cryptography -and public-key infrastructure. - -SSL Concepts for OpenFlow -------------------------- - -This section is an introduction to the public-key infrastructure -architectures that Open vSwitch supports for SSL authentication. - -To connect over SSL, every Open vSwitch must have a unique -private/public key pair and a certificate that signs that public key. -Typically, the Open vSwitch generates its own public/private key pair. -There are two common ways to obtain a certificate for a switch: - - * Self-signed certificates: The Open vSwitch signs its certificate - with its own private key. In this case, each switch must be - individually approved by the OpenFlow controller(s), since there - is no central authority. - - This is the only switch PKI model currently supported by NOX - (http://noxrepo.org). - - * Switch certificate authority: A certificate authority (the - "switch CA") signs each Open vSwitch's public key. The OpenFlow - controllers then check that any connecting switches' - certificates are signed by that certificate authority. - - This is the only switch PKI model supported by the simple - OpenFlow controller included with Open vSwitch. - -Each Open vSwitch must also have a copy of the CA certificate for the -certificate authority that signs OpenFlow controllers' keys (the -"controller CA" certificate). Typically, the same controller CA -certificate is installed on all of the switches within a given -administrative unit. There are two common ways for a switch to obtain -the controller CA certificate: - - * Manually copy the certificate to the switch through some secure - means, e.g. using a USB flash drive, or over the network with - "scp", or even FTP or HTTP followed by manual verification. - - * Open vSwitch "bootstrap" mode, in which Open vSwitch accepts and - saves the controller CA certificate that it obtains from the - OpenFlow controller on its first connection. Thereafter the - switch will only connect to controllers signed by the same CA - certificate. - -Establishing a Public Key Infrastructure ----------------------------------------- - -Open vSwitch can make use of your existing public key infrastructure. -If you already have a PKI, you may skip forward to the next section. -Otherwise, if you do not have a PKI, the ovs-pki script included with -Open vSwitch can help. To create an initial PKI structure, invoke it -as: - - % ovs-pki init - -to create and populate a new PKI directory. The default location for -the PKI directory depends on how the Open vSwitch tree was configured -(to see the configured default, look for the --dir option description -in the output of "ovs-pki --help"). - -The pki directory contains two important subdirectories. The -controllerca subdirectory contains controller CA files, including the -following: - - - cacert.pem: Root certificate for the controller certificate - authority. Each Open vSwitch must have a copy of this file to - allow it to authenticate valid controllers. - - - private/cakey.pem: Private signing key for the controller - certificate authority. This file must be kept secret. There is - no need for switches or controllers to have a copy of it. - -The switchca subdirectory contains switch CA files, analogous to those -in the controllerca subdirectory: - - - cacert.pem: Root certificate for the switch certificate - authority. The OpenFlow controller must have this file to - enable it to authenticate valid switches. - - - private/cakey.pem: Private signing key for the switch - certificate authority. This file must be kept secret. There is - no need for switches or controllers to have a copy of it. - -After you create the initial structure, you can create keys and -certificates for switches and controllers with ovs-pki. Refer to the -ovs-pki(8) manage for complete details. A few examples of its use -follow: - -CONTROLLER KEY GENERATION - -To create a controller private key and certificate in files named -ctl-privkey.pem and ctl-cert.pem, run the following on the machine -that contains the PKI structure: - - % ovs-pki req+sign ctl controller - -ctl-privkey.pem and ctl-cert.pem would need to be copied to the -controller for its use at runtime. If, for testing purposes, you were -to use ovs-testcontroller, the simple OpenFlow controller included -with Open vSwitch, then the --private-key and --certificate options, -respectively, would point to these files. - -It is very important to make sure that no stray copies of -ctl-privkey.pem are created, because they could be used to impersonate -the controller. - -SWITCH KEY GENERATION WITH SELF-SIGNED CERTIFICATES - -If you are using self-signed certificates (see "SSL Concepts for -OpenFlow"), this is one way to create an acceptable certificate for -your controller to approve. - -1. Run the following command on the Open vSwitch itself: - - % ovs-pki self-sign sc - - (This command does not require a copy of any of the PKI files - generated by "ovs-pki init", and you should not copy them to the - switch because some of them have contents that must remain secret - for security.) - - The "ovs-pki self-sign" command has the following output: - - * sc-privkey.pem, the switch private key file. For security, - the contents of this file must remain secret. There is - ordinarily no need to copy this file off the Open vSwitch. - - * sc-cert.pem, the switch certificate, signed by the switch's - own private key. Its contents are not a secret. - -2. Optionally, copy controllerca/cacert.pem from the machine that has - the OpenFlow PKI structure and verify that it is correct. - (Otherwise, you will have to use CA certificate bootstrapping when - you configure Open vSwitch in the next step.) - -3. Configure Open vSwitch to use the keys and certificates (see - "Configuring SSL Support", below). - -SWITCH KEY GENERATION WITH A SWITCH PKI (EASY METHOD) - -If you are using a switch PKI (see "SSL Concepts for OpenFlow", -above), this method of switch key generation is a little easier than -the alternate method described below, but it is also a little less -secure because it requires copying a sensitive private key from file -from the machine hosting the PKI to the switch. - -1. Run the following on the machine that contains the PKI structure: - - % ovs-pki req+sign sc switch - - This command has the following output: - - * sc-privkey.pem, the switch private key file. For - security, the contents of this file must remain secret. - - * sc-cert.pem, the switch certificate. Its contents are - not a secret. - -2. Copy sc-privkey.pem and sc-cert.pem, plus controllerca/cacert.pem, - to the Open vSwitch. - -3. Delete the copies of sc-privkey.pem and sc-cert.pem on the PKI - machine and any other copies that may have been made in transit. - It is very important to make sure that there are no stray copies of - sc-privkey.pem, because they could be used to impersonate the - switch. - - (Don't delete controllerca/cacert.pem! It is not - security-sensitive and you will need it to configure additional - switches.) - -4. Configure Open vSwitch to use the keys and certificates (see - "Configuring SSL Support", below). - -SWITCH KEY GENERATION WITH A SWITCH PKI (MORE SECURE) - -If you are using a switch PKI (see "SSL Concepts for OpenFlow", -above), then, compared to the previous method, the method described -here takes a little more work, but it does not involve copying the -private key from one machine to another, so it may also be a little -more secure. - -1. Run the following command on the Open vSwitch itself: - - % ovs-pki req sc - - (This command does not require a copy of any of the PKI files - generated by "ovs-pki init", and you should not copy them to the - switch because some of them have contents that must remain secret - for security.) - - The "ovs-pki req" command has the following output: - - * sc-privkey.pem, the switch private key file. For security, - the contents of this file must remain secret. There is - ordinarily no need to copy this file off the Open vSwitch. - - * sc-req.pem, the switch "certificate request", which is - essentially the switch's public key. Its contents are not a - secret. - - * A fingerprint, on stdout. - -2. Write the fingerprint down on a slip of paper and copy sc-req.pem - to the machine that contains the PKI structure. - -3. On the machine that contains the PKI structure, run: - - % ovs-pki sign sc switch - - This command will output a fingerprint to stdout and request that - you verify it. Check that it is the same as the fingerprint that - you wrote down on the slip of paper before you answer "yes". - - "ovs-pki sign" creates a file named sc-cert.pem, which is the - switch certificate. Its contents are not a secret. - -4. Copy the generated sc-cert.pem, plus controllerca/cacert.pem from - the PKI structure, to the Open vSwitch, and verify that they were - copied correctly. - - You may delete sc-cert.pem from the machine that hosts the PKI - structure now, although it is not important that you do so. (Don't - delete controllerca/cacert.pem! It is not security-sensitive and - you will need it to configure additional switches.) - -5. Configure Open vSwitch to use the keys and certificates (see - "Configuring SSL Support", below). - -Configuring SSL Support ------------------------ - -SSL configuration requires three additional configuration files. The -first two of these are unique to each Open vSwitch. If you used the -instructions above to build your PKI, then these files will be named -sc-privkey.pem and sc-cert.pem, respectively: - - - A private key file, which contains the private half of an RSA or - DSA key. - - This file can be generated on the Open vSwitch itself, for the - greatest security, or it can be generated elsewhere and copied - to the Open vSwitch. - - The contents of the private key file are secret and must not be - exposed. - - - A certificate file, which certifies that the private key is that - of a trustworthy Open vSwitch. - - This file has to be generated on a machine that has the private - key for the switch certification authority, which should not be - an Open vSwitch; ideally, it should be a machine that is not - networked at all. - - The certificate file itself is not a secret. - -The third configuration file is typically the same across all the -switches in a given administrative unit. If you used the -instructions above to build your PKI, then this file will be named -cacert.pem: - - - The root certificate for the controller certificate authority. - The Open vSwitch verifies it that is authorized to connect to an - OpenFlow controller by verifying a signature against this CA - certificate. - -Once you have these files, configure ovs-vswitchd to use them using -the ovs-vsctl "set-ssl" command, e.g.: - - ovs-vsctl set-ssl /etc/openvswitch/sc-privkey.pem /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem - -Substitute the correct file names, of course, if they differ from the -ones used above. You should use absolute file names (ones that begin -with "/"), because ovs-vswitchd's current directory is unrelated to -the one from which you run ovs-vsctl. - -If you are using self-signed certificates (see "SSL Concepts for -OpenFlow") and you did not copy controllerca/cacert.pem from the PKI -machine to the Open vSwitch, then add the --bootstrap option, e.g.: - - ovs-vsctl -- --bootstrap set-ssl /etc/openvswitch/sc-privkey.pem /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem - -After you have added all of these configuration keys, you may specify -"ssl:" connection methods elsewhere in the configuration database. -"tcp:" connection methods are still allowed even after SSL has been -configured, so for security you should use only "ssl:" connections. - -Reporting Bugs --------------- - -Please report problems to bugs@openvswitch.org. - -[INSTALL.rst]:INSTALL.rst diff --git a/INSTALL.SSL.rst b/INSTALL.SSL.rst new file mode 100644 index 0000000..8edd25e --- /dev/null +++ b/INSTALL.SSL.rst @@ -0,0 +1,338 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +===================== +Open vSwitch with SSL +===================== + +If you plan to configure Open vSwitch to connect across the network to an +OpenFlow controller, then we recommend that you build Open vSwitch with +OpenSSL. SSL support ensures integrity and confidentiality of the OpenFlow +connections, increasing network security. + +This document describes how to configure an Open vSwitch to connect to an +OpenFlow controller over SSL. Refer to the `general installation guide +`__ for instructions on building Open vSwitch with SSL support. + +Open vSwitch uses TLS version 1.0 or later (TLSv1), as specified by RFC 2246, +which is very similar to SSL version 3.0. TLSv1 was released in January 1999, +so all current software and hardware should implement it. + +This document assumes basic familiarity with public-key cryptography and +public-key infrastructure. + +SSL Concepts for OpenFlow +------------------------- + +This section is an introduction to the public-key infrastructure architectures +that Open vSwitch supports for SSL authentication. + +To connect over SSL, every Open vSwitch must have a unique private/public key +pair and a certificate that signs that public key. Typically, the Open vSwitch +generates its own public/private key pair. There are two common ways to obtain +a certificate for a switch: + +* Self-signed certificates: The Open vSwitch signs its certificate with its own + private key. In this case, each switch must be individually approved by the + OpenFlow controller(s), since there is no central authority. + + This is the only switch PKI model currently supported by NOX + (http://noxrepo.org). + +* Switch certificate authority: A certificate authority (the "switch CA") signs + each Open vSwitch's public key. The OpenFlow controllers then check that any + connecting switches' certificates are signed by that certificate authority. + + This is the only switch PKI model supported by the simple OpenFlow controller + included with Open vSwitch. + +Each Open vSwitch must also have a copy of the CA certificate for the +certificate authority that signs OpenFlow controllers' keys (the "controller +CA" certificate). Typically, the same controller CA certificate is installed +on all of the switches within a given administrative unit. There are two +common ways for a switch to obtain the controller CA certificate: + +* Manually copy the certificate to the switch through some secure means, e.g. + using a USB flash drive, or over the network with "scp", or even FTP or HTTP + followed by manual verification. + +* Open vSwitch "bootstrap" mode, in which Open vSwitch accepts and saves the + controller CA certificate that it obtains from the OpenFlow controller on its + first connection. Thereafter the switch will only connect to controllers + signed by the same CA certificate. + +Establishing a Public Key Infrastructure +---------------------------------------- + +Open vSwitch can make use of your existing public key infrastructure. If you +already have a PKI, you may skip forward to the next section. Otherwise, if +you do not have a PKI, the ovs-pki script included with Open vSwitch can help. +To create an initial PKI structure, invoke it as: + +:: + + $ ovs-pki init + +This will create and populate a new PKI directory. The default location for +the PKI directory depends on how the Open vSwitch tree was configured (to see +the configured default, look for the ``--dir`` option description in the output +of ``ovs-pki --help``). + +The pki directory contains two important subdirectories. The `controllerca` +subdirectory contains controller CA files, including the following: + +`cacert.pem` + Root certificate for the controller certificate authority. Each Open vSwitch + must have a copy of this file to allow it to authenticate valid controllers. + +`private/cakey.pem` + Private signing key for the controller certificate authority. This file must + be kept secret. There is no need for switches or controllers to have a copy + of it. + +The `switchca` subdirectory contains switch CA files, analogous to those in the +`controllerca` subdirectory: + +`cacert.pem` + Root certificate for the switch certificate authority. The OpenFlow + controller must have this file to enable it to authenticate valid switches. + +`private/cakey.pem` + Private signing key for the switch certificate authority. This file must be + kept secret. There is no need for switches or controllers to have a copy of + it. + +After you create the initial structure, you can create keys and certificates +for switches and controllers with ovs-pki. Refer to the ovs-pki(8) manage for +complete details. A few examples of its use follow: + +Controller Key Generation +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To create a controller private key and certificate in files named +ctl-privkey.pem and ctl-cert.pem, run the following on the machine that +contains the PKI structure: + +:: + + $ ovs-pki req+sign ctl controller + +ctl-privkey.pem and ctl-cert.pem would need to be copied to the controller for +its use at runtime. If, for testing purposes, you were to use +ovs-testcontroller, the simple OpenFlow controller included with Open vSwitch, +then the --private-key and --certificate options, respectively, would point to +these files. + +It is very important to make sure that no stray copies of ctl-privkey.pem are +created, because they could be used to impersonate the controller. + +Switch Key Generation with Self-Signed Certificates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using self-signed certificates (see "SSL Concepts for OpenFlow"), +this is one way to create an acceptable certificate for your controller to +approve. + +1. Run the following command on the Open vSwitch itself:: + + $ ovs-pki self-sign sc + + .. note:: + This command does not require a copy of any of the PKI files generated by + ``ovs-pki init``, and you should not copy them to the switch because some + of them have contents that must remain secret for security.) + + The ``ovs-pki self-sign`` command has the following output: + + sc-privkey.pem + the switch private key file. For security, the contents of this file must + remain secret. There is ordinarily no need to copy this file off the Open + vSwitch. + + sc-cert.pem + the switch certificate, signed by the switch's own private key. Its + contents are not a secret. + +2. Optionally, copy `controllerca/cacert.pem` from the machine that has the + OpenFlow PKI structure and verify that it is correct. (Otherwise, you will + have to use CA certificate bootstrapping when you configure Open vSwitch in + the next step.) + +3. Configure Open vSwitch to use the keys and certificates (see "Configuring + SSL Support", below). + +Switch Key Generation with a Switch PKI (Easy Method) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using a switch PKI (see "SSL Concepts for OpenFlow", above), this +method of switch key generation is a little easier than the alternate method +described below, but it is also a little less secure because it requires +copying a sensitive private key from file from the machine hosting the PKI to +the switch. + +1. Run the following on the machine that contains the PKI structure:: + + $ ovs-pki req+sign sc switch + + This command has the following output: + + sc-privkey.pem + the switch private key file. For security, the contents of this file must + remain secret. + + sc-cert.pem + the switch certificate. Its contents are not a secret. + +2. Copy sc-privkey.pem and sc-cert.pem, plus controllerca/cacert.pem, to the + Open vSwitch. + +3. Delete the copies of sc-privkey.pem and sc-cert.pem on the PKI machine and + any other copies that may have been made in transit. It is very important + to make sure that there are no stray copies of sc-privkey.pem, because they + could be used to impersonate the switch. + + .. warning:: + Don't delete controllerca/cacert.pem! It is not security-sensitive and + you will need it to configure additional switches. + +4. Configure Open vSwitch to use the keys and certificates (see "Configuring + SSL Support", below). + +Switch Key Generation with a Switch PKI (More Secure) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are using a switch PKI (see "SSL Concepts for OpenFlow", above), then, +compared to the previous method, the method described here takes a little more +work, but it does not involve copying the private key from one machine to +another, so it may also be a little more secure. + +1. Run the following command on the Open vSwitch itself:: + + $ ovs-pki req sc + + .. note:: + This command does not require a copy of any of the PKI files generated by + "ovs-pki init", and you should not copy them to the switch because some of + them have contents that must remain secret for security. + + The "ovs-pki req" command has the following output: + + sc-privkey.pem + the switch private key file. For security, the contents of this file must + remain secret. There is ordinarily no need to copy this file off the Open + vSwitch. + + sc-req.pem + the switch "certificate request", which is essentially the switch's public + key. Its contents are not a secret. + + a fingerprint + this is output on stdout. + +2. Write the fingerprint down on a slip of paper and copy `sc-req.pem` to the + machine that contains the PKI structure. + +3. On the machine that contains the PKI structure, run:: + + $ ovs-pki sign sc switch + + This command will output a fingerprint to stdout and request that you verify + it. Check that it is the same as the fingerprint that you wrote down on the + slip of paper before you answer "yes". + + ``ovs-pki sign`` creates a file named `sc-cert.pem`, which is the switch + certificate. Its contents are not a secret. + +4. Copy the generated `sc-cert.pem`, plus `controllerca/cacert.pem` from the + PKI structure, to the Open vSwitch, and verify that they were copied + correctly. + + You may delete `sc-cert.pem` from the machine that hosts the PKI + structure now, although it is not important that you do so. + + .. warning:: + Don't delete `controllerca/cacert.pem`! It is not security-sensitive and + you will need it to configure additional switches. + +5. Configure Open vSwitch to use the keys and certificates (see "Configuring + SSL Support", below). + +Configuring SSL Support +----------------------- + +SSL configuration requires three additional configuration files. The first two +of these are unique to each Open vSwitch. If you used the instructions above +to build your PKI, then these files will be named `sc-privkey.pem` and +`sc-cert.pem`, respectively: + +- A private key file, which contains the private half of an RSA or DSA key. + + This file can be generated on the Open vSwitch itself, for the greatest + security, or it can be generated elsewhere and copied to the Open vSwitch. + + The contents of the private key file are secret and must not be exposed. + +- A certificate file, which certifies that the private key is that of a + trustworthy Open vSwitch. + + This file has to be generated on a machine that has the private key for the + switch certification authority, which should not be an Open vSwitch; ideally, + it should be a machine that is not networked at all. + + The certificate file itself is not a secret. + +The third configuration file is typically the same across all the switches in a +given administrative unit. If you used the instructions above to build your +PKI, then this file will be named `cacert.pem`: + +- The root certificate for the controller certificate authority. The Open + vSwitch verifies it that is authorized to connect to an OpenFlow controller + by verifying a signature against this CA certificate. + +Once you have these files, configure ovs-vswitchd to use them using the +``ovs-vsctl set-ssl`` command, e.g.:: + + $ ovs-vsctl set-ssl /etc/openvswitch/sc-privkey.pem \ + /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem + +Substitute the correct file names, of course, if they differ from the ones used +above. You should use absolute file names (ones that begin with ``/``), +because ovs-vswitchd's current directory is unrelated to the one from which you +run ovs-vsctl. + +If you are using self-signed certificates (see "SSL Concepts for OpenFlow") and +you did not copy controllerca/cacert.pem from the PKI machine to the Open +vSwitch, then add the ``--bootstrap`` option, e.g.:: + + $ ovs-vsctl -- --bootstrap set-ssl /etc/openvswitch/sc-privkey.pem \ + /etc/openvswitch/sc-cert.pem /etc/openvswitch/cacert.pem + +After you have added all of these configuration keys, you may specify ``ssl:`` +connection methods elsewhere in the configuration database. ``tcp:`` connection +methods are still allowed even after SSL has been configured, so for security +you should use only ``ssl:`` connections. + +Reporting Bugs +-------------- + +Report problems to bugs@openvswitch.org. diff --git a/Makefile.am b/Makefile.am index ebcf263..3f3cd21 100644 --- a/Makefile.am +++ b/Makefile.am @@ -82,7 +82,7 @@ docs = \ INSTALL.NetBSD.md \ INSTALL.RHEL.md \ INSTALL.SELinux.md \ - INSTALL.SSL.md \ + INSTALL.SSL.rst \ INSTALL.XenServer.rst \ INSTALL.userspace.rst \ INSTALL.Windows.rst \ diff --git a/README.rst b/README.rst index 7d18b38..c0a2ce4 100644 --- a/README.rst +++ b/README.rst @@ -101,7 +101,7 @@ To use Open vSwitch... For answers to common questions, refer to the `FAQ `__. To learn how to set up SSL support for Open vSwitch, see `here -`__. +`__. To learn about some advanced features of the Open vSwitch software switch, read the `tutorial `__. diff --git a/rhel/openvswitch-fedora.spec.in b/rhel/openvswitch-fedora.spec.in index 029471c..861dac7 100644 --- a/rhel/openvswitch-fedora.spec.in +++ b/rhel/openvswitch-fedora.spec.in @@ -474,7 +474,7 @@ fi %{_mandir}/man8/ovs-vswitchd.8* %{_mandir}/man8/ovs-parse-backtrace.8* %{_mandir}/man8/ovs-testcontroller.8* -%doc COPYING DESIGN.rst INSTALL.SSL.md NOTICE README.rst WHY-OVS.rst +%doc COPYING DESIGN.rst INSTALL.SSL.rst NOTICE README.rst WHY-OVS.rst %doc FAQ.rst NEWS INSTALL.DPDK.rst rhel/README.RHEL.rst /var/lib/openvswitch /var/log/openvswitch diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in index 2e429e6..6c5fe1b 100644 --- a/rhel/openvswitch.spec.in +++ b/rhel/openvswitch.spec.in @@ -247,7 +247,7 @@ exit 0 /usr/share/openvswitch/scripts/sysconfig.template /usr/share/openvswitch/vswitch.ovsschema /usr/share/openvswitch/vtep.ovsschema -%doc COPYING DESIGN.rst INSTALL.SSL.md NOTICE README.rst WHY-OVS.rst FAQ.rst NEWS +%doc COPYING DESIGN.rst INSTALL.SSL.rst NOTICE README.rst WHY-OVS.rst FAQ.rst NEWS %doc INSTALL.DPDK.rst rhel/README.RHEL.rst README-native-tunneling.rst /var/lib/openvswitch /var/log/openvswitch