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

Stokes, Ian ian.stokes at intel.com
Thu Oct 26 06:01:06 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 ;)

Hi Billy, sure, I was sticking with the RST standard here, but for clarity I could call it out in caps or also in the patch description. Will keep in mind for the next revision.


> > +
> > +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