[ovs-dev,RFC,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@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

Hi Ian,

> -----Original Message-----
> From: ovs-dev-bounces@openvswitch.org [mailto:ovs-dev-
> bounces@openvswitch.org] On Behalf Of Ian Stokes
> Sent: Friday, August 25, 2017 5:41 PM
> To: dev@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@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@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev

> Hi Ian,
> 
> > -----Original Message-----
> > From: ovs-dev-bounces@openvswitch.org [mailto:ovs-dev-
> > bounces@openvswitch.org] On Behalf Of Ian Stokes
> > Sent: Friday, August 25, 2017 5:41 PM
> > To: dev@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@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@openvswitch.org
> > https://mail.openvswitch.org/mailman/listinfo/ovs-dev