4 =======================
6 ``VPP-SSWAN`` is a StrongSwan plugin that helps offloading Strongswan IPsec ESP
7 process from Linux Kernel to ``VPP``.
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.
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
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>`__.
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.
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.
39 Please Note: ONLY Strongswan version ``5.9.5`` and ``5.9.6`` were tested with
42 Build VPP Strongswan Plugin
45 ``VPP-SSWAN`` requires ``StrongSwan`` source to compile. To obtain
46 ``StrongSwan`` the simplest way is to run the following commands:
50 cd path/to/vpp/external/strongswan/vpp_swan/
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:
58 - download strongswan source code to:
59 ``path/to/vpp/build/external/downloads``
61 - unzip source code strongswan to:
62 ``path/to/vpp/build-root/build-vpp-native/external/sswan``
64 - check if you have installed packages: ``libsystemd-dev`` on your OS
66 - configure strongswan by:
68 ``./configure --prefix=/usr --sysconfdir=/etc --enable-libipsec
69 --enable-systemd --enable-swanctl --disable-gmp --enable-openssl``
71 - compile ``vpp-swan plugin`` by:
75 cd path/to/vpp/external/strongswan/vpp_swan/
78 Build/install Strongswan (Optional)
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.
86 cd path/to/vpp/external/strongswan/vpp_swan/
90 Install VPP-SWAN plugin into StrongSwan
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``.
98 cd path/to/vpp/external/strongswan/vpp_swan/
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/``
105 Now you can restart ``Strongswan`` by executing the following command:
109 systemctl restart strongswan.service
111 Configuration Strongswan
114 As an example, ``swanctl.conf`` file provides an example configuration to
115 initialize connections between two endpoints.
117 You may update the file based on your need and Copy into:
118 ``/etc/swanctl/conf.d/swanctl.conf``
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:
132 plugin linux_cp_plugin.so { enable }
133 plugin ikev2_plugin.so { disable }
143 Based on the provided sample ``swanctl.conf``, the following commands are
144 required to be executed in ``VPP``:
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
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``.
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.
166 This plugin is based on:
167 `https://github.com/matfabia/strongswan
168 <https://github.com/matfabia/strongswan>`__
170 Author: Matus Fabian <matfabia@cisco.com>