extras/strongswan/vpp_sswan/README.rst

   1 .. _vpp_sswan_doc:
   2
   3 VPP-SSWAN
   4 =======================
   5
   6 ``VPP-SSWAN`` is a StrongSwan plugin that helps offloading Strongswan IPsec ESP
   7 process from Linux Kernel to ``VPP``.
   8
   9 The ``VPP-SSWAN`` takes advantage of ``StrongSwan`` extendable plugin design
  10 and translates ``StrongSwan`` SA creation/deletion and routing
  11 update operations into ``VPP`` C API calls. The successful execution of the
  12 API calls means the operations shall be performed by VPP smoothly.
  13
  14 Inside ``VPP-SSWAN``, the kernel-vpp plugin is an interface to the IPsec and
  15 networking backend for `VPP <https://wiki.fd.io/view/VPP>`__ platform using
  16 the `VPP C API <https://wiki.fd.io/view/VPP/How_To_Use_The_C_API>`__.
  17 It provides address and routing lookup functionality and installs routes for
  18 IPsec traffic.
  19
  20 The plugin also installs and maintains Security Associations and Policies to
  21 the `VPP IPsec <https://wiki.fd.io/view/VPP/IPSec_and_IKEv2#IPSec>`__.
  22
  23 Since ``StrongSwan`` expects both IKE and IPsec traffic coming through the
  24 same network protected interfaces, the ``VPP-SSWAN`` expects the IKE traffic
  25 being diverted to Linux Kernel through the help of
  26 `VPP Linux Control Plane <https://s3-docs.fd.io/vpp/22.10/developer/plugins/
  27 lcp.html>`__. It is important to notice that due to LCP is a Tun/Tap interface,
  28 the IPsec performance will be limited by it if Transport mode of IPsec is used.
  29
  30 Prerequisites
  31 -------------
  32
  33 ``VPP`` in release mode should be built before compiling ``vpp-swan plugin``.
  34 User may install ``StrongSwan`` prior to compile the plugin. However the
  35 plugin requires downloading ``StrongSwan`` source to include some of its
  36 header files to compile ``VPP-SSWAN``. In addition ``libsystemd-dev``
  37 should be installed prior to compile the plugin.
  38
  39 Please Note: ONLY Strongswan version ``5.9.5`` and ``5.9.6`` were tested with
  40 this plugin.
  41
  42 Build VPP Strongswan Plugin
  43 -------------
  44
  45 ``VPP-SSWAN`` requires ``StrongSwan`` source to compile. To obtain
  46 ``StrongSwan`` the simplest way is to run the following commands:
  47
  48 ::
  49
  50    cd path/to/vpp/external/strongswan/vpp_swan/
  51    make all
  52
  53 Or you may download ``StrongSwan``  from its github page. It is recommended to
  54 use ``Strongswan`` version ``5.9.6`` or ``5.9.5`` for ``VPP-SSWAN`` to be
  55 compiled and integrate. The following steps are required for manually download
  56 ``Strongswan`` source:
  57
  58 - download strongswan source code to:
  59 ``path/to/vpp/build/external/downloads``
  60
  61 - unzip source code strongswan to:
  62 ``path/to/vpp/build-root/build-vpp-native/external/sswan``
  63
  64 - check if you have installed packages: ``libsystemd-dev`` on your OS
  65
  66 - configure strongswan by:
  67 ``./autogen.sh``
  68 ``./configure --prefix=/usr --sysconfdir=/etc --enable-libipsec
  69 --enable-systemd --enable-swanctl --disable-gmp --enable-openssl``
  70
  71 - compile ``vpp-swan plugin`` by:
  72
  73 ::
  74
  75    cd path/to/vpp/external/strongswan/vpp_swan/
  76    make
  77
  78 Build/install Strongswan (Optional)
  79 -------------
  80
  81 In case you haven't installed ``Strongswan`` yet, you may use the following
  82 simple command to compile and install ``Strongswan`` from the downloaded source.
  83
  84 ::
  85
  86    cd path/to/vpp/external/strongswan/vpp_swan/
  87    make pull-swan
  88    make install-swan
  89
  90 Install VPP-SWAN plugin into StrongSwan
  91 -------------
  92
  93 After the ``VPP-SSWAN`` plugin has been built and ``Strongswan`` was installed,
  94 the following command will install the ``VPP-SSWAN`` plugin into ``Strongswan``.
  95
  96 ::
  97
  98    cd path/to/vpp/external/strongswan/vpp_swan/
  99    make install
 100
 101 Or you can manually copy ``libstrongswan-kernel-vpp.so`` into:
 102 ``/usr/lib/ipsec/plugins``,
 103 and also ``kernel-vpp.conf`` into: ``/etc/strongswan.d/charon/``
 104
 105 Now you can restart ``Strongswan`` by executing the following command:
 106
 107 ::
 108
 109    systemctl restart strongswan.service
 110
 111 Configuration Strongswan
 112 -------------
 113
 114 As an example, ``swanctl.conf`` file provides an example configuration to
 115 initialize connections between two endpoints.
 116
 117 You may update the file based on your need and Copy into:
 118 ``/etc/swanctl/conf.d/swanctl.conf``
 119
 120 Configuration VPP
 121 -------------
 122
 123 Some special treatment to VPP are required in your VPP ``startup.conf``.
 124 Since we use ``Strongswan`` to process IKE messages, we should disable VPP's
 125 IKEv2 plugin. Also as mentioned ``Linux Control Plane`` plugin is needed to
 126 route the traffic between VPP interface and Tun/Tap interface. To do so, simply
 127 adding the following commands:
 128
 129 ::
 130
 131    plugins {
 132      plugin linux_cp_plugin.so { enable }
 133      plugin ikev2_plugin.so { disable }
 134     }
 135
 136    linux-cp {
 137       lcp-sync
 138    }
 139
 140 Running VPP
 141 -------------
 142
 143 Based on the provided sample ``swanctl.conf``, the following commands are
 144 required to be executed in ``VPP``:
 145
 146 ::
 147
 148    lcp create eth2 host-if eth2
 149    set interface state eth2 up
 150    set interface ip address eth2 192.168.0.2/24
 151    set int state eth1 up
 152    set int ip addr eth1 192.168.200.1/24
 153
 154 In the commands above we assume ``eth2`` is the WAN interface to receive both
 155 IKE message and ESP encapsulated packets, and ``eth1`` is the LAN interface to
 156 receive plain packets to be encrypted. With the commands a ``Linux CP`` interface
 157 is created to mirror the ``eth2`` interface to Linux Kernel, and both interfaces
 158 were set the IP addresses followed by the ``swanctl.conf``.
 159
 160 With the commands successfully executed and the security policy is succesfully
 161 agreed between two IKE daemons (one with VPP as IPsec processing engine), you may
 162 see the packets are encrypted/decrypted by VPP smoothly.
 163
 164 Misc
 165 -------------
 166 This plugin is based on:
 167 `https://github.com/matfabia/strongswan
 168 <https://github.com/matfabia/strongswan>`__
 169
 170 Author: Matus Fabian <matfabia@cisco.com>