[ovs-dev] [RFC PATCH v2 09/10] Docs: Add userspace-ipsec how to guide.

O Mahony, Billy billy.o.mahony at intel.com
Wed Oct 18 16:59:48 UTC 2017


Hi Ian,

> -----Original Message-----
> From: ovs-dev-bounces at openvswitch.org [mailto:ovs-dev-
> bounces at openvswitch.org] On Behalf Of Ian Stokes
> Sent: Friday, August 25, 2017 5:41 PM
> To: dev at openvswitch.org
> Subject: [ovs-dev] [RFC PATCH v2 09/10] Docs: Add userspace-ipsec how to
> guide.
> 
> This commit adds a how to guide for using the proposed vxlanipsec userspace
> interface. It is not intended to be upstreamed but simply seeks to solicit feed
> back by providing an example of the proposed vxlanipsec interface design setup
> and usage.
> 
> The how to usecase deals with securing vxlan traffic between 2 VMs as
> described in the userspace-vxlan how to guide. It provides an example of how
> the proposed ipsec interface is configured with an SPD, creation of SAs including
> IPsec protocol, mode, crypto/authentication algorithms/keys, assigning SPD
> entires to SAs for inbound/outbound traffic with traffic selectors and finally
> updating the SA keys.
> 
> Signed-off-by: Ian Stokes <ian.stokes at intel.com>
> ---
>  Documentation/automake.mk               |    1 +
>  Documentation/howto/index.rst           |    1 +
>  Documentation/howto/userspace-ipsec.rst |  187
> +++++++++++++++++++++++++++++++
>  3 files changed, 189 insertions(+), 0 deletions(-)  create mode 100644
> Documentation/howto/userspace-ipsec.rst
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk index
> 24fe63d..a8f2a01 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -59,6 +59,7 @@ DOC_SOURCE = \
>  	Documentation/howto/tunneling.png \
>  	Documentation/howto/tunneling.rst \
>  	Documentation/howto/userspace-tunneling.rst \
> +	Documentation/howto/userspace-ipsec.rst \
>  	Documentation/howto/vlan.png \
>  	Documentation/howto/vlan.rst \
>  	Documentation/howto/vtep.rst \
> diff --git a/Documentation/howto/index.rst b/Documentation/howto/index.rst
> index 5859a33..97d690a 100644
> --- a/Documentation/howto/index.rst
> +++ b/Documentation/howto/index.rst
> @@ -43,6 +43,7 @@ OVS
>     lisp
>     tunneling
>     userspace-tunneling
> +   userspace-ipsec
>     vlan
>     qos
>     vtep
> diff --git a/Documentation/howto/userspace-ipsec.rst
> b/Documentation/howto/userspace-ipsec.rst
> new file mode 100644
> index 0000000..2ae2bd8
> --- /dev/null
> +++ b/Documentation/howto/userspace-ipsec.rst
> @@ -0,0 +1,187 @@
> +..
> +      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.
> +
> +==========================================================
> +Securing VXLAN traffic between VMs Using IPsec (Userspace)
> +==========================================================
> +
> +This document describes how to use IPsec in Open vSwitch to secure
> +traffic between VMs on two different hosts communicating over VXLAN
> +tunnels. This solution works entirely in userspace.
> +
> +.. note::
> +
> +   This guide covers the steps required to configure an IPsec interface to
> +   secure VXLAN tunneling traffic. It does not cover the steps to configure
> +   the vxlan tunnels in userspace. For these configuration steps please refer
> +   to :doc:`userspace-tunneling`.
> +
> +.. TODO(stephenfin): Convert this to a (prettier) PNG with same styling as the
> +   rest of the document
> +
> +::
> +
> +    +--------------+                                  +--------------+
> +    |     vm0      | 192.168.1.1/24    192.168.1.2/24 |     vm1      |
> +    +--------------+                                  +--------------+
> +       (vm_port0)                                        (vm_port1)
> +           |                                                 |
> +           |                                                 |
> +           |                                                 |
> +    +--------------+                                  +--------------+
> +    |    br-int    |                                  |    br-int    |
> +    +--------------+                                  +--------------+
> +    | vxlanipsec0  | 172.168.1.1/24    172.168.1.2/24 | vxlanipsec0  |
> +    +--------------+                                  +--------------+
> +           |                                                 |
> +           |                                                 |
> +           |                                                 |
> +    +--------------+                                  +--------------+
> +    |    br-phy    |                                  |    br-phy    |
> +    +--------------+                                  +--------------+
> +    |  dpdk0/eth1  |----------------------------------|  dpdk0/eth1  |
> +    +--------------+                                  +--------------+
> +    Host 1 with OVS.                                  Host 2 with OVS.
> +
> +Setup
> +-----
> +
> +This guide assumes the environment is configured as described below.
> +
> +Two Physical Hosts
> +~~~~~~~~~~~~~~~~~~
> +
> +The environment assumes the use of two hosts, named `host1` and
> +`host2`. We only detail the configuration of `host1` but a similar
> +configuration can be used for `host2`. Both hosts should be configured
> +with Open vSwitch with DPDK datapath, QEMU/KVM and suitable VM images.
> +Open vSwitch should be running before proceeding.
> +
> +Configuration Steps
> +-------------------
> +
> +For the purpose of functional testing at this point a user should
> +follow the :doc:`userspace-tunneling` guide but with the following
> +modification. Replace the interface type of ``vxlan`` with
> +``vxlanipsec``. Specifically the user should replace the following command::
> +
> +    $ ovs-vsctl add-port br-int vxlan0 \
> +         -- set interface vxlan0 type=vxlan
> + options:remote_ip=172.168.1.2
> +
> +with::
> +
> +    $ ovs-vsctl add-port br-int vxlanipsec0 \
> +         -- set interface vxlanipsec0 type=vxlanipsec \
> +         options:remote_ip=172.168.1.2
> +
> +The current setup allows functional testing of a vxlanipsec port using
> +128 AES-CBC cipher for encryption and HMAC-SHA1-96 for authentication.
> +Configuration parameters such as keys etc.e are hard coded at this
> +point for the purpose of testing.
> +
> +Note:: At this point the IPsec tunnel work is ongoing and is part of an
> +RFC patchset. As such the configuration options below are not yet supported.
> +They are included here for the purpose of completeness only and to
> +solicit feedback on the proposed eventual implementation.
[[BO'M]] I have to admit I missed the 'not yet supported' part above. It should be made to standout more - all caps maybe? Or a big section break - (even if it breaks rst syntax) would be helpful to the unobservant among us ;)
> +
> +Complete the following steps to configure a vxlan IPsec interface for
> +securing VXLAN traffic between the VMs.
> +
> +Perform the following configuration on `host1`:
> +
> +#. On `host1`, add a port with an IPsec interface to bridge `br-int`::
> +
> +       $ ovs-vsctl add-port br-int vxlanipsec0 -- set Interface ipsec0 \
> +           type=vxlanipsec
> +
> +#. Create a SPD with ID `1` for `ipsec0`::
> +
> +       $ ovs-vsctl set Interface vxlanipsec0 options:spd_id=1
> +
> +#. Create two SAs with ID `10` and `20` for `ipsec0` with required SA info::
> +
> +       $ ovs-vsctl set Interface vxlanipsec0 options:sa_id=10 \
> +           options:sa_spi=7A390BC1 \
> +           options:sa_protocol=esp \
> +           options:ipsec_mode=transport \
> +           options:crypto_alg=aes_cbc \
> +           options:crypto_key=4a506a794f574265564551694d653768 \
> +           options:auth_alg=hmac_sha2_256_128 \
> +           options:auth_key=4339314b55523947594d6d3547666b45764e6a58 \
> +
> +       $ ovs-vsctl set Interface vxlanipsec0 options:sa_id=20 \
> +           options:sa_spi=7A390BC1 \
> +           options:sa_protocol=esp \
> +           options:ipsec_mode=transport \
> +           options:crypto_alg=aes_cbc \
> +           options:crypto_key=4a506a794f574265564551694d653768 \
> +           options:auth_alg=hmac_sha2_256_128 \
> +           options:auth_key=4339314b55523947594d6d3547666b45764e6a58 \
> +
> +#. Create a policy for inbound IPsec traffic with desired IP address info::
> +
> +       $ ovs-vsctl set Interface vxlanipsec0 options:policy_priority=20 \
> +           options:policy_tdir=inbound \
> +           options:policy_action=protect \
> +           options:policy_sa=10 \
> +           options:ts_local_ip_range=172.168.1.1 - 178.168.1.1 \
> +           options:ts_remote_ip_range=172.168.1.2 - 172.168.1.2 \
> +           options:ts_protocol=50
> +
> +#. Create a policy for outbound VXLAN traffic with desired IP address info::
> +
> +       $ ovs-vsctl set Interface vxlanipsec0 options:policy_priority=20 \
> +           options:policy_tdir=outbound \
> +           options:policy_action=protect \
> +           options:policy_sa=20 \
> +           options:ts_local_ip_range=172.168.1.1 - 178.168.1.1 \
> +           options:ts_remote_ip_range=172.168.1.2 - 172.168.1.2 \
> +           options:ts_remote_port_range=4789 - 4789 \
> +           options:ts_protocol=17 \
> +
> +   .. note::
> +
> +      This assumes the user is using the IANA port `4789` for VXLAN traffic.
> +
> +Repeat these steps for `host2`, but using ``172.168.1.1`` and
> +``172.168.1.2`` for the remote and local IP ranges, respectively.
> +
> +Testing
> +-------
> +
> +With this setup, ping to VXLAN target device (``192.168.1.2``) should work.
> +Outbound traffic will be VXLAN encapsulated, encrypted/authenticated
> +with the specified algorithms defined in SA `20` and sent over ``dpdk0``
> interface.
> +
> +Inbound traffic will be decrypted/authenticated with the specified
> +algorithms defined in SA `10`.
> +
> +Configuration Updates
> +---------------------
> +
> +#. The keys for SA `10` can be updated with the following command::
> +
> +
> +       $ ovs-vsctl set Interface vxlanipsec0 options:sa_id=10 \
> +           options:crypto_key=4a506a794f574265564551694d653768 \
> +           options:auth_key=4339314b55523947594d6d3547666b45764e6a58 \
> --
> 1.7.0.7
> 
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev


More information about the dev mailing list