From patchwork Tue Jul 31 21:08:51 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Qiuyu Xiao X-Patchwork-Id: 951833 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=openvswitch.org (client-ip=140.211.169.12; helo=mail.linuxfoundation.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="r9enm6fX"; dkim-atps=neutral Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 41g8M60mByz9rxx for ; Wed, 1 Aug 2018 07:14:10 +1000 (AEST) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 40BF5106E; Tue, 31 Jul 2018 21:09:46 +0000 (UTC) X-Original-To: ovs-dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 06F8C1032 for ; Tue, 31 Jul 2018 21:09:44 +0000 (UTC) X-Greylist: whitelisted by SQLgrey-1.7.6 Received: from mail-pf1-f194.google.com (mail-pf1-f194.google.com [209.85.210.194]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id ACF837BE for ; Tue, 31 Jul 2018 21:09:40 +0000 (UTC) Received: by mail-pf1-f194.google.com with SMTP id u24-v6so6684389pfn.13 for ; Tue, 31 Jul 2018 14:09:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=AEBAPydHzkpxBfg4tAdQEvfa8Jw9A+P7yyMFsjyEGgw=; b=r9enm6fXS5rPbqhL7oN3zXjj6Zn77cbHRaHAzwfhGGdmxk5IFWmF3gRdxwMFF0dTPP hlQY3YjdzUIkU5ZOmqY9omHRqdnqULfVyKQVuw0Z4JzJa2uRWVVYhJNsHqokjSJP1gDo /DR0nenoLAAOiPbWz40EDo/9AjpY35rdd0HNQaPqcATYsr+yxuF87Y3A9pEOzxiiuG8S P5ka0Itx7bV/O81wwALbb3J/VctUT7dBble7fsSrmeJxvCDCWuniNFvljRDR/bq+0q5y 754PlPxkx0G9G++5Erh8wA5LmUttDxOlQXCUoX9N4RWD8lSAhJOmf4Qxhztnq1USWNIY 9DpQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=AEBAPydHzkpxBfg4tAdQEvfa8Jw9A+P7yyMFsjyEGgw=; b=M2E6ABVM9iIahHaAkLsvl6y/nuj9mQVsO8TXUbYuVh5hLfUgjUWCCAcRlefEerlRyI H+5xxWqOzRPko7bgOVd3JRQf7uIpCNW2f0x5W5KgFKAbUHs9qaXM9UnwNr9byFLwC/3y 5y8F/UDZpar5C3nl6gjkf1v3zEtu/YhiRVi6qDMCB5/0CBw1BSsTgN04TzkmYXHGrvMt ZD6oykUN5gaPDnTKHtpOMcSoGRn5b+0DpncICGu9WbjIH3JjwSYseBmRyE5urXOBpkLS ecz2g4pKK8IYbGlvLWe+YWvb9DGEoHbHeozp9Iy+v9goLonyVYDx+UTqnEEU7zwVzi63 pcCw== X-Gm-Message-State: AOUpUlElZIldoRmkGcHcdOzCzX9bA4sv6AX+QgVGFpPz1gWjofcm+8hx 42lDmlcv4MHv/vNXvLW5C10F0RWT X-Google-Smtp-Source: AAOMgpeU3orcp0G2DZmYFnlp3kV7qvGsGfbXTfKNOocQAI5uyYhUTECiyaSItp+XuQekKVAPIpzRwA== X-Received: by 2002:a63:41c6:: with SMTP id o189-v6mr22352056pga.323.1533071379170; Tue, 31 Jul 2018 14:09:39 -0700 (PDT) Received: from vm1.eng.vmware.com ([66.170.99.1]) by smtp.gmail.com with ESMTPSA id s66-v6sm40894996pfe.53.2018.07.31.14.09.38 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 31 Jul 2018 14:09:38 -0700 (PDT) From: Qiuyu Xiao To: ovs-dev@openvswitch.org Date: Tue, 31 Jul 2018 14:08:51 -0700 Message-Id: <20180731210854.31682-7-qiuyu.xiao.qyx@gmail.com> X-Mailer: git-send-email 2.18.0 In-Reply-To: <20180731210854.31682-1-qiuyu.xiao.qyx@gmail.com> References: <20180731210854.31682-1-qiuyu.xiao.qyx@gmail.com> X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, FREEMAIL_FROM, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Cc: Ansis Atteka Subject: [ovs-dev] [PATCH v4 6/9] Documentation: IPsec tunnel tutorial and documentation. X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org tutorials/index.rst gives a step-by-setp guide to set up OVS IPsec tunnel. tutorials/ipsec.rst gives detailed explanation on the IPsec tunnel configuration methods and forwarding modes. Signed-off-by: Qiuyu Xiao Signed-off-by: Ansis Atteka Co-authored-by: Ansis Atteka --- Documentation/automake.mk | 2 + Documentation/howto/index.rst | 1 + Documentation/howto/ipsec.rst | 193 +++++++++++++++++ Documentation/tutorials/index.rst | 1 + Documentation/tutorials/ipsec.rst | 342 ++++++++++++++++++++++++++++++ vswitchd/vswitch.xml | 122 ++++++++++- 6 files changed, 652 insertions(+), 9 deletions(-) create mode 100644 Documentation/howto/ipsec.rst create mode 100644 Documentation/tutorials/ipsec.rst diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 244479490..5401b9bad 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -28,6 +28,7 @@ DOC_SOURCE = \ Documentation/tutorials/ovn-openstack.rst \ Documentation/tutorials/ovn-sandbox.rst \ Documentation/tutorials/ovs-conntrack.rst \ + Documentation/tutorials/ipsec.rst \ Documentation/topics/index.rst \ Documentation/topics/bonding.rst \ Documentation/topics/idl-compound-indexes.rst \ @@ -60,6 +61,7 @@ DOC_SOURCE = \ Documentation/howto/docker.rst \ Documentation/howto/dpdk.rst \ Documentation/howto/firewalld.rst \ + Documentation/howto/ipsec.rst \ Documentation/howto/kvm.rst \ Documentation/howto/libvirt.rst \ Documentation/howto/selinux.rst \ diff --git a/Documentation/howto/index.rst b/Documentation/howto/index.rst index 201d6936b..9a3487be3 100644 --- a/Documentation/howto/index.rst +++ b/Documentation/howto/index.rst @@ -37,6 +37,7 @@ OVS :maxdepth: 2 kvm + ipsec selinux libvirt ssl diff --git a/Documentation/howto/ipsec.rst b/Documentation/howto/ipsec.rst new file mode 100644 index 000000000..17dead501 --- /dev/null +++ b/Documentation/howto/ipsec.rst @@ -0,0 +1,193 @@ +.. + 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. + +======================================= +Encrypt Open vSwitch Tunnels with IPsec +======================================= + +This document gives detailed description on the OVS IPsec tunnel and its +configuration modes. If you want to follow a step-by-step guide to run and +test IPsec tunnel, please refer to :doc:`/tutorials/ipsec`. + +Overview +-------- + +Why do encryption? +~~~~~~~~~~~~~~~~~~ + +OVS tunnel packets are transported from one machine to another. Along the path, +the packets are processed by physical routers and physical switches. There are +risks that these physical devices might read or write the contents of the +tunnel packets. IPsec encrypts IP payload and prevents the malicious party +sniffing or manipulating the tunnel traffic. + +OVS IPsec +~~~~~~~~~ + +OVS IPsec aims to provide a simple interface for user to add encryption on OVS +tunnels. It supports GRE, GENEVE, VXLAN, and STT tunnel. The IPsec +configuration is done by setting options of the tunnel interface and +other_config of Open_vSwitch. You can choose different authentication methods +and fowarding modes based on your system requirement. + +Configuration +------------- + +Authentication Methods +~~~~~~~~~~~~~~~~~~~~~~ + +Hosts of the IPsec tunnel need to authenticate each other to build a secure +channel. There are three authentication methods: + +1) You can use pre-shared key (PSK) to do authentication. In both hosts, set + the same PSK value. This PSK is like your password. You should never reveal + it to untrusted parties. This method is easier to use but less secure than + the certificate-based methods:: + + $ ovs-vsctl add-port br0 ipsec_gre0 -- \ + set interface ipsec_gre0 type=gre \ + options:local_ip=1.1.1.1 \ + options:remote_ip=2.2.2.2 \ + options:psk=swordfish + + .. note:: + + The local_ip field is required for the IPsec tunnel. + +2) You can use self-signed certificate to do authentication. In each host, + generate a certificate and the paired private key. Copy the certificate of + the remote host to the local host and configure the OVS as following:: + + $ ovs-vsctl set Open_vSwitch . \ + other_config:certificate=/path/to/local_cert.pem \ + other_config:private_key=/path/to/priv_key.pem + $ ovs-vsctl add-port br0 ipsec_gre0 -- \ + set interface ipsec_gre0 type=gre \ + options:local_ip=1.1.1.1 \ + options:remote_ip=2.2.2.2 \ + options:remote_cert=/path/to/remote_cert.pem + + `local_cert.pem` is the certificate of the local host. `priv_key.pem` + is the private key of the local host. `priv_key.pem` needs to be stored in + a secure location. `remote_cert.pem` is the certificate of the remote host. + + .. note:: + + OVS IPsec requires x.509 version 3 certificate with the subjectAltName + DNS field setting the same string as the common name (CN) field. You can + follow the tutorial in :doc:`/tutorials/ipsec` and use ovs-pki(8) to + generate compatible certificate and key. + +3) You can also use CA-signed certificate to do authentication. First, you need + to create a CA certificate and sign each host certificate with the CA key + (please see :doc:`/tutorials/ipsec`). Copy the CA certificate to each + host and configure the OVS as following:: + + $ ovs-vsctl set Open_vSwitch . \ + other_config:certificate=/path/to/local_cert.pem \ + other_config:private_key=/path/to/priv_key.pem \ + other_config:ca_cert=/path/to/ca_cert.pem + $ ovs-vsctl add-port br0 ipsec_gre0 -- \ + set interface ipsec_gre0 type=gre \ + options:local_ip=1.1.1.1 \ + options:remote_ip=2.2.2.2 \ + options:remote_name=remote_cn + + `ca_cert.pem` is the CA certificate. You need to set `remote_cn` as the + common name (CN) of the remote host's certificate so that only the + certificate with the expected CN can be trusted in this connection. It is + preferable to use this method than 2) if there are many remote hosts since + you don't have to copy every remote certificate to the local host. + + .. note:: + + When using certificate-based authentication, you should not set psk in + the interface options. When using psk-based authentication, you should + not set certificate, private_key, ca_cert, remote_cert, and remote_name. + +Forwarding Modes +~~~~~~~~~~~~~~~~ + +There is delay between the user setting up IPsec tunnel and the IPsec tunnel +actually taking affect to encrypt packets. To offset the risk of unencrypted +packets leaking out during this period, you can choose a more secure forwarding +mode. There are three forwarding modes: + +1) The default mode allows unencrypted packets being sent out before IPsec + taking effect:: + + $ ovs-vsctl add-port br0 ipsec_gre0 -- \ + set interface ipsec_gre0 type=gre \ + options:local_ip=1.1.1.1 \ + options:remote_ip=2.2.2.2 \ + options:psk=swordfish + + This mode should be used only and only if tunnel configuration is static + and/or if there is firewall that can drop the plain packets that + occasionally leak the tunnel unencrypted on OVSDB (re)configuration events. + +2) The ipsec_skb_mark mode filters unencrypted packets by using skb mark of + tunnel packets:: + + $ ovs-vsctl set Open_vSwitch . other_config:ipsec_skb_mark=0/1 + $ ovs-vsctl add-port br0 ipsec_gre0 -- \ + set interface ipsec_gre0 type=gre \ + options:local_ip=1.1.1.1 \ + options:remote_ip=2.2.2.2 \ + options:psk=swordfish + + OVS IPsec filters unencrypted packets which carry the same skb mark as + `ipsec_skb_mark`. By setting the ipsec_skb_mark as 0/1, OVS IPsec prevents + all unencrypted tunnel packets leaving the host since the default skb mark + value for tunnel packets are 0. This affects all OVS tunnels including those + without IPsec being set up. You can install OpenFlow rules to whitelist + those non-IPsec tunnels by setting the skb mark of the tunnel traffic as + non-zero value. + +3) Setting `ipsec_skb_mark` as 1/1 only filters tunnel packets with skb mark + value being 1:: + + $ ovs-vsctl set Open_vSwitch . other_config:ipsec_skb_mark=1/1 + $ ovs-vsctl add-port br0 ipsec_gre0 -- \ + set interface ipsec_gre0 type=gre \ + options:local_ip=1.1.1.1 \ + options:remote_ip=2.2.2.2 \ + options:psk=swordfish + + Opposite to 2), this mode doesn't filter unencrypted tunnel packets by + default. To filter unencrypted IPsec tunnel traffic, you need to explicitly + set skb mark to a non-zero value for those tunnel traffic by installing + OpenFlow rules. + +Bug Reporting +------------- + +If you think you may have found a bug with security implications, like + +1) IPsec protected tunnel accepted packets that came unencrypted; OR +2) IPsec protected tunnel allowed packets to leave unencrypted; + +Then report such bugs according to :doc:`/internals/security`. + +If bug does not have security implications, then report it according to +instructions in :doc:`/internals/bugs`. diff --git a/Documentation/tutorials/index.rst b/Documentation/tutorials/index.rst index ab90b7c84..b481090a0 100644 --- a/Documentation/tutorials/index.rst +++ b/Documentation/tutorials/index.rst @@ -40,6 +40,7 @@ vSwitch. :maxdepth: 2 faucet + ipsec ovs-advanced ovn-sandbox ovn-openstack diff --git a/Documentation/tutorials/ipsec.rst b/Documentation/tutorials/ipsec.rst new file mode 100644 index 000000000..d25fcb0f7 --- /dev/null +++ b/Documentation/tutorials/ipsec.rst @@ -0,0 +1,342 @@ +.. + 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. + +================== +OVS IPsec Tutorial +================== + +This document provides a step-by-step guide for running IPsec tunnel in Open +vSwitch. A more detailed description on OVS IPsec tunnel and its +configuration modes can be found in :doc:`/howto/ipsec`. + +Requirements +------------ + +OVS IPsec tunnel requires Linux kernel (>= v4.13.0) and OVS out-of-tree kernel +module. The compatible IKE daemons are LibreSwan (>= v3.23) and StrongSwan +(>= v5.3.5). + +.. _install-ovs-ipsec: + +Installing OVS and IPsec Packages +--------------------------------- + +OVS IPsec has .deb and .rpm packages. You should use the right package +based on your Linux distribution. This tutorial uses Ubuntu 16.04 and Fedora 27 +as examples. + +Ubuntu +~~~~~~ + +1. Follow :doc:`/intro/install/debian` to build debian packages. + + .. note:: + + If you have already installed OVS, then you only need to install + openvswitch-pki_*.deb and openvswitch-ipsec_*.deb in the following step. + If your kernel version is below v4.13.0, update your kernel to v4.13.0 or + above. + +2. Install the related packages:: + + $ apt-get install dkms strongswan + $ dpkg -i libopenvswitch_*.deb openvswitch-common_*.deb \ + openvswitch-switch_*.deb openvswitch-datapath-dkms_*.deb \ + python-openvswitch_*.deb openvswitch-pki_*.deb \ + openvswitch-ipsec_*.deb + + If the installation is successful, you should be able to see the + ovs-monitor-ipsec daemon is running in your system. + +Fedora +~~~~~~ + +1. Follow :doc:`/intro/install/fedora` to build RPM packages. + +2. Install the related packages:: + + $ dnf install python2-openvswitch libreswan \ + "kernel-devel-uname-r == $(uname -r)" + $ rpm -i openvswitch-*.rpm openvswitch-kmod-*.rpm \ + openvswitch-openvswitch-ipsec-*.rpm + +3. Install firewall rules to allow ESP traffic:: + + $ iptables -A IN_FedoraServer_allow -p esp -j ACCEPT + +4. Run the openvswitch-ipsec service:: + + $ systemctl start openvswitch-ipsec.service + + .. note:: + + The SELinux policies might prevent openvswitch-ipsec.service to access + certain resources. You can configure SELinux to remove such restrictions. + +Configuring IPsec tunnel +------------------------ + +Suppose you want to build IPsec tunnel between two hosts. `host_1`'s external +IP is `ip_1`. `host_2`'s external IP is `ip_2`. + +1. Set up OVS bridges in both hosts. + + In `host_1`:: + + $ ovs-vsctl add-br br-ipsec + $ ip addr add 192.0.0.1/24 dev br-ipsec + $ ip link set br-ipsec up + + In `host_2`:: + + $ ovs-vsctl add-br br-ipsec + $ ip addr add 192.0.0.2/24 dev br-ipsec + $ ip link set br-ipsec up + +2. Set up IPsec tunnel. + + There are three authentication methods. You can choose one to set up your + IPsec tunnel. + + a) Using pre-shared key + + In `host_1`:: + + $ ovs-vsctl add-port br-ipsec tun -- \ + set interface tun type=gre \ + options:local_ip=ip_1 \ + options:remote_ip=ip_2 \ + options:psk=swordfish + + In `host_2`:: + + $ ovs-vsctl add-port br-ipsec tun -- \ + set interface tun type=gre \ + options:local_ip=ip_2 \ + options:remote_ip=ip_1 \ + options:psk=swordfish + + .. note:: + + Pre-shared key (PSK) based authentication is easy to set up but less + secure compared with other authentication methods. You should use it + cautiously in production system. + + b) Using self-signed certificate + + Generate self-signed certificate in both `host_1` and `host_2`. Then copy + the certificate of `host_1` to `host_2` and the certificate of `host_2` + to `host_1`. + + In `host_1`:: + + $ ovs-pki req -u host_1 + $ ovs-pki self-sign host_1 + $ scp host_1-cert.pem host_2@ip_2:/path/to/host_1-cert.pem + + In `host_2`:: + + $ ovs-pki req -u host_2 + $ ovs-pki self-sign host_2 + $ scp host_2-cert.pem host_1@ip_1:/path/to/host_2-cert.pem + + .. note:: + + If you use StrongSwan as IKE daemon, please move the host certificates + to /etc/ipsec.d/certs/ and private key to /etc/ipsec.d/private/ so that + StrongSwan has permission to access those files. + + Configure IPsec tunnel to use self-signed certificate. + + In `host_1`:: + + $ ovs-vsctl set Open_vSwitch . \ + other_config:certificate=/path/to/host_1-cert.pem \ + other_config:private_key=/path/to/host_1-privkey.pem + $ ovs-vsctl add-port br-ipsec tun -- \ + set interface tun type=gre \ + options:local_ip=ip_1 \ + options:remote_ip=ip_2 \ + options:remote_cert=/path/to/host_2-cert.pem + + In `host_2`:: + + $ ovs-vsctl set Open_vSwitch . \ + other_config:certificate=/path/to/host_2-cert.pem \ + other_config:private_key=/path/to/host_2-privkey.pem + $ ovs-vsctl add-port br-ipsec tun -- \ + set interface tun type=gre \ + options:local_ip=ip_2 \ + options:remote_ip=ip_1 \ + options:remote_cert=/path/to/host_1-cert.pem + + .. note:: + + The security of the private key is very critical. Don't copy the + private key to unsafe place. + + c) Using CA-signed certificate + + First you need to establish a public key infrastructure (PKI). Suppose + you choose `host_1` to host PKI. + + In `host_1`:: + + $ ovs-pki init + + Generate certificate requests and copy the certificate request of + `host_2` to `host_1`. + + In `host_1`:: + + $ ovs-pki req -u host_1 + + In `host_2`:: + + $ ovs-pki req -u host_2 + $ scp host_2-req.pem host_1@ip_1:/path/to/host_2-req.pem + + Sign the certificate requests with the CA key. Copy `host_2`'s signed + certificate and the CA certificate to `host_2`. + + In `host_1`:: + + $ ovs-pki sign host_1 switch + $ ovs-pki sign host_2 switch + $ scp host_2-cert.pem host_2@ip_2:/path/to/host_2-cert.pem + $ scp /var/lib/openvswitch/pki/switchca/cacert.pem \ + host_2@ip_2:/path/to/cacert.pem + + .. note:: + + If you use StrongSwan as IKE daemon, please move the host certificates + to /etc/ipsec.d/certs/, CA certificate to /etc/ipsec.d/cacerts/, and + private key to /etc/ipsec.d/private/ so that StrongSwan has permission + to access those files. + + Configure IPsec tunnel to use CA-signed certificate. + + In `host_1`:: + + $ ovs-vsctl set Open_vSwitch . \ + other_config:certificate=/path/to/host_1-cert.pem \ + other_config:private_key=/path/to/host_1-privkey.pem \ + other_config:ca_cert=/path/to/cacert.pem + $ ovs-vsctl add-port br-ipsec tun -- \ + set interface tun type=gre \ + options:local_ip=ip_1 \ + options:remote_ip=ip_2 \ + options:remote_name=host_2 + + In `host_2`:: + + $ ovs-vsctl set Open_vSwitch . \ + other_config:certificate=/path/to/host_2-cert.pem \ + other_config:private_key=/path/to/host_2-privkey.pem \ + other_config:ca_cert=/path/to/cacert.pem + $ ovs-vsctl add-port br-ipsec tun -- \ + set interface tun type=gre \ + options:local_ip=ip_2 \ + options:remote_ip=ip_1 \ + options:remote_name=host_1 + + .. note:: + + remote_name is the common name (CN) of the signed-certificate. It + should be set correctly so that only certificate with the expected CN + can be authenticated. + +3. Test IPsec tunnel. + + Now you should have an IPsec GRE tunnel running between two hosts. To verify + it, in `host_1`:: + + $ ping 192.0.0.2 & + $ tcpdump -ni any net ip_2 + + You should be able to see that ESP packets are being sent from `host_1` to + `host_2`. + +Troubleshooting +--------------- + +Use following ovs-apptcl command to get ovs-monitor-ipsec internal +representation of tunnel configuration:: + + $ ovs-appctl -t ovs-monitor-ipsec tunnels/show + +If there is misconfiguration then ovs-appctl should indicate why. +For example:: + + Interface name: gre0 v5 (CONFIGURED) <--- Should be set to CONFIGURED. + Otherwise, error message will + be provided + Tunnel Type: gre + Local IP: 1.1.1.1 + Remote IP: 2.2.2.2 + SKB mark: None + Local cert: None + Local name: None + Local key: None + Remote cert: None + Remote name: None + CA cert: None + PSK: swordfish + Ofport: 1 <--- Whether ovs-vswitchd has assigned Ofport + number to this Tunnel Port + CFM state: Up <--- Whether CFM declared this tunnel healthy + Kernel policies installed: + ... <--- IPsec policies for this OVS tunnel in + Linux Kernel installed by strongSwan + Kernel security associations installed: + ... <--- IPsec security associations for this OVS + tunnel in Linux Kernel installed by + strongswan + IPsec connections that are active: + ... <--- IPsec "connections" for this OVS + tunnel + +If you don't see any active connections, try to run the following command to +refresh the ovs-monitor-ipsec daemon:: + + $ ovs-appctl -t ovs-monitor-ipsec refresh + +You can also check the logs of the ovs-monitor-ipsec daemon and the IKE daemon +to locate issues. The logs of the ovs-monitor-ipsec is in +/var/log/openvswitch/ovs-monitor-ipsec.log. + +Bug Reporting +------------- + +If you think you may have found a bug with security implications, like + +1. IPsec protected tunnel accepted packets that came unencrypted; OR +2. IPsec protected tunnel allowed packets to leave unencrypted; + +Then report such bugs according to :doc:`/internals/security`. + +If bug does not have security implications, then report it according to +instructions in :doc:`/internals/bugs`. + +If you have suggestions to improve this tutorial, please send a email to +ovs-discuss@openvswitch.org. diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml index 634294944..df96f30d1 100644 --- a/vswitchd/vswitch.xml +++ b/vswitchd/vswitch.xml @@ -503,10 +503,8 @@ OpenFlow specification mandates the timeout to be at least one second. The default is 10 seconds.

- - + - Sequence number for client to increment. When a client modifies @@ -770,6 +768,85 @@ + +

+ The global configuration of IPsec tunnels is set in the + other_config column of the Open_vSwitch + table. The individual IPsec tunnel configuration is set in the + options column of the Interface table. +

+

+ ipsec_skb_mark is set to choose forwarding mode which + prevents unencrypted packets being sent out since there is delay + between the user setting up IPsec tunnel and the IPsec tunnel actually + taking affect to encrypt packets. +

+

+ There are three authentication modes: +

+
    +
  1. + Pre-shared key mode: private_key, + certificate, and ca_cert must not be set. + psk in the options column of the + Interface table should be set as the preshared key. +
    2. +
  2. + Self-signed certificate mode: private_key and + certificate must be set. remote_cert in the + options column of the Interface table must + be set. The remote certificate can be self-signed. +
    3. +
  3. + CA-signed certificate mode: private_key, + certificate, and ca_cert must be set. + remote_name in the options column of the + Interface table must be set as the common name (CN) of + the remote certificate. The remote certificate must be signed by the + CA. +
    4. +
+ +

+ Setting ipsec_skb_mark as 1/1 blocks unecrypted packets with skb + mark setting as 1. Besides, the OpenFlow rule with set SKB mark + action specified in OVSDB needs to be installed in Open_vSwitch + table before the first packet was able to leave the OVS tunnel. +

+

+ Setting ipsec_skb_mark as 0/1 blocks unecrypted packets without skb + mark. As a result, IPsec assumes that all packets coming from + tunnels should be encrypted unless OpenFlow actions explicitly + set skb mark to a non-zero value. +

+ + +

+ Name of a PEM file containing the private key used as the switch's + identity for IPsec tunnels. +

+ + +

+ Name of a PEM file containing a certificate that certifies the + switch's private key, and identifies a trustworthy switch for IPsec + tunnels. The certificate must be x.509 version 3 and with the + string in common name (CN) also set in the subject alternative name + (SAN). +

+ + +

+ Name of a PEM file containing the CA certificate used to verify + that a remote switch of the IPsec tunnel is trustworthy. +

+ + + The overall purpose of these columns is described under Common Columns at the beginning of this document. @@ -1409,7 +1486,7 @@ - +

A port within a .

Most commonly, a port has exactly one ``interface,'' pointed to by its @@ -2398,9 +2475,9 @@

- Optional. The tunnel destination IP that received packets must - match. Default is to match all addresses. If specified, may be one - of: + Optional (except for IPsec tunnels). The tunnel destination IP that + received packets must match. Default is to match all addresses. If + specified, may be one of:

    @@ -2655,7 +2732,7 @@

    - Optional. Compute encapsulation header (either GRE or UDP) + Optional. Compute encapsulation header (either GRE or UDP) checksums on outgoing packets. Default is disabled, set to true to enable. Checksums present on incoming packets will be validated regardless of this setting. @@ -2673,8 +2750,35 @@ - + +

    + gre, geneve, vxlan, and + stt interfaces support these options. +

    + +

    + The preshared secret to negotiate tunnel in PSK mode. This value + must match on both tunnel ends and must be unset when + remote_cert or remote_nameis set. +

    +     + +

    + Name of a PEM file containing a certificate of the remote switch. + The certificate must be x.509 version 3 and with the string in + common name (CN) also set in the subject alternative name (SAN). It + must be unset when psk is set. +

    +     + +

    + Common name (CN) of the remote certificate. It must be unset when + psk is set. +

    +     + +

    Only erspan interfaces support these options.