vpp-swan: improve Makefile

Type: improvement

Since VPP-SWAN does not really need StrongSwan to be compiled,
this patch refines the Makefile to reflect the change.

In addition README is updated.

Signed-off-by: Fan Zhang <fanzhang.oss@gmail.com>
Change-Id: I185957167ac71a44f4d12e78e1dac31c194f80f4

1 files changed, 79 insertions, 37 deletions

diff --git a/extras/strongswan/vpp_sswan/README.rst b/extras/strongswan/vpp_sswan/README.rst
index 4def8383c2a..57b30f452e5 100644
--- a/extras/strongswan/vpp_sswan/README.rst
+++ b/extras/strongswan/vpp_sswan/README.rst
@@ -6,25 +6,54 @@ VPP-SSWAN
 ``VPP-SSWAN`` is a StrongSwan plugin that helps offloading Strongswan IPsec ESP
 process from Linux Kernel to ``VPP``.
 
-The kernel-vpp plugin is an interface to the IPsec and networking backend for
-`VPP <https://wiki.fd.io/view/VPP>`__ platform using the
-`VPP C API <https://wiki.fd.io/view/VPP/How_To_Use_The_C_API>`__.
+The ``VPP-SSWAN`` takes advantage of ``StrongSwan`` extendable plugin design
+and translates ``StrongSwan`` SA creation/deletion and routing
+update operations into ``VPP`` C API calls. The successful execution of the
+API calls means the operations shall be performed by VPP smoothly.
+
+Inside ``VPP-SSWAN``, the kernel-vpp plugin is an interface to the IPsec and
+networking backend for `VPP <https://wiki.fd.io/view/VPP>`__ platform using
+the `VPP C API <https://wiki.fd.io/view/VPP/How_To_Use_The_C_API>`__.
 It provides address and routing lookup functionality and installs routes for
 IPsec traffic.
-It installs and maintains Security Associations and Policies to the
-`VPP IPsec <https://wiki.fd.io/view/VPP/IPSec_and_IKEv2#IPSec>`__.
+
+The plugin also installs and maintains Security Associations and Policies to
+the `VPP IPsec <https://wiki.fd.io/view/VPP/IPSec_and_IKEv2#IPSec>`__.
+
+Since ``StrongSwan`` expects both IKE and IPsec traffic coming through the
+same network protected interfaces, the ``VPP-SSWAN`` expects the IKE traffic
+being diverted to Linux Kernel through the help of
+`VPP Linux Control Plane <https://s3-docs.fd.io/vpp/22.10/developer/plugins/
+lcp.html>`__. It is important to notice that due to LCP is a Tun/Tap interface,
+the IPsec performance will be limited by it if Transport mode of IPsec is used.
 
 Prerequisites
 -------------
 
 ``VPP`` in release mode should be built before compiling ``vpp-swan plugin``.
-The dependencies of ``StrongSwan`` should be installed before building
-``VPP-SSWAN``. In addition ``libsystemd-dev`` should be installed.
+User may install ``StrongSwan`` prior to compile the plugin. However the
+plugin requires downloading ``StrongSwan`` source to include some of its
+header files to compile ``VPP-SSWAN``. In addition ``libsystemd-dev``
+should be installed prior to compile the plugin.
+
+Please Note: ONLY Strongswan version ``5.9.5`` and ``5.9.6`` were tested with
+this plugin.
 
 Build VPP Strongswan Plugin
 -------------
 
-The following list of things will be done to build ``vpp-swan plugin``:
+``VPP-SSWAN`` requires ``StrongSwan`` source to compile. To obtain
+``StrongSwan`` the simplest way is to run the following commands:
+
+::
+
+   cd path/to/vpp/external/strongswan/vpp_swan/
+   make all
+
+Or you may download ``StrongSwan``  from its github page. It is recommended to
+use ``Strongswan`` version ``5.9.6`` or ``5.9.5`` for ``VPP-SSWAN`` to be
+compiled and integrate. The following steps are required for manually download
+``Strongswan`` source:
 
 - download strongswan source code to:
 ``path/to/vpp/build/external/downloads``
@@ -35,48 +64,45 @@ The following list of things will be done to build ``vpp-swan plugin``:
 - check if you have installed packages: ``libsystemd-dev`` on your OS
 
 - configure strongswan by:
+``./autogen.sh``
 ``./configure --prefix=/usr --sysconfdir=/etc --enable-libipsec
 --enable-systemd --enable-swanctl --disable-gmp --enable-openssl``
 
-- compile strongswan in:
-``path/to/vpp/build-root/build-vpp-native/external/sswan``
-
 - compile ``vpp-swan plugin`` by:
 
 ::
 
-   ./make all
+   cd path/to/vpp/external/strongswan/vpp_swan/
+   make
 
-- if everything it ok, copy the compiled ``vpp-swan plugin`` to:
-``/usr/lib/ipsec/plugins``
-
-Build/install Strongswan
+Build/install Strongswan (Optional)
 -------------
 
-It is recommended to use ``Strongswan`` in version ``5.9.6`` or ``5.9.5``
-installed from this script, due to configuration Strongswan that is required.
-Only version ``5.9.5`` and ``5.9.6`` was tested with this plugin.
-
-To install the built Strongswan, please execute the following command:
+In case you haven't installed ``Strongswan`` yet, you may use the following
+simple command to compile and install ``Strongswan`` from the downloaded source.
 
 ::
 
-   path/to/vpp/build-root/build-vpp-native/external/sswan/sudo make install
+   cd path/to/vpp/external/strongswan/vpp_swan/
+   make pull-swan
+   make install-swan
 
-Insert plugin in runtime mode
+Install VPP-SWAN plugin into StrongSwan
 -------------
 
-After builded this plugin and also installed Strongswan you can loaded plugin
-into Strongswan directory by:
+After the ``VPP-SSWAN`` plugin has been built and ``Strongswan`` was installed,
+the following command will install the ``VPP-SSWAN`` plugin into ``Strongswan``.
 
 ::
 
-   ./make install
+   cd path/to/vpp/external/strongswan/vpp_swan/
+   make install
 
-Or you can do manually copy ``libstrongswan-kernel-vpp.so`` into:
-``/usr/lib/ipsec/plugins`` and also ``kernel-vpp.conf`` into: ``/etc/strongswan.d/charon/``
+Or you can manually copy ``libstrongswan-kernel-vpp.so`` into:
+``/usr/lib/ipsec/plugins``,
+and also ``kernel-vpp.conf`` into: ``/etc/strongswan.d/charon/``
 
-And also you should restart Strongswan by:
+Now you can restart ``Strongswan`` by executing the following command:
 
 ::
 
@@ -84,15 +110,21 @@ And also you should restart Strongswan by:
 
 Configuration Strongswan
 -------------
-In ``swanctl.conf`` file you can find example configuration to initialize
-connections between two endpoints.
 
-Copy this file into: ``/etc/swanctl/conf.d/swanctl.conf``
+As an example, ``swanctl.conf`` file provides an example configuration to
+initialize connections between two endpoints.
+
+You may update the file based on your need and Copy into:
+``/etc/swanctl/conf.d/swanctl.conf``
 
 Configuration VPP
 -------------
 
-In your ``startup.conf`` add these following commands:
+Some special treatment to VPP are required in your VPP ``startup.conf``.
+Since we use ``Strongswan`` to process IKE messages, we should disable VPP's
+IKEv2 plugin. Also as mentioned ``Linux Control Plane`` plugin is needed to
+route the traffic between VPP interface and Tun/Tap interface. To do so, simply
+adding the following commands:
 
 ::
 
@@ -105,9 +137,11 @@ In your ``startup.conf`` add these following commands:
       lcp-sync
    }
 
-To enable ``CP Plugin`` and disable ``IKEv2`` plugin.
+Running VPP
+-------------
 
-These following commands executed in ``VPP``:
+Based on the provided sample ``swanctl.conf``, the following commands are
+required to be executed in ``VPP``:
 
 ::
 
@@ -117,7 +151,15 @@ These following commands executed in ``VPP``:
    set int state eth1 up
    set int ip addr eth1 192.168.200.1/24
 
-To create interface by ``CP Plugin`` and also setup two ethernet interfaces.
+In the commands above we assume ``eth2`` is the WAN interface to receive both
+IKE message and ESP encapsulated packets, and ``eth1`` is the LAN interface to
+receive plain packets to be encrypted. With the commands a ``Linux CP`` interface
+is created to mirror the ``eth2`` interface to Linux Kernel, and both interfaces
+were set the IP addresses followed by the ``swanctl.conf``.
+
+With the commands successfully executed and the security policy is succesfully
+agreed between two IKE daemons (one with VPP as IPsec processing engine), you may
+see the packets are encrypted/decrypted by VPP smoothly.
 
 Misc
 -------------
@@ -125,4 +167,4 @@ This plugin is based on:
 `https://github.com/matfabia/strongswan
 <https://github.com/matfabia/strongswan>`__
 
-Author: Matus Fabian <matfabia@cisco.com>
\ No newline at end of file
+Author: Matus Fabian <matfabia@cisco.com>