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 <[email protected]> --- 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. + +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 [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
