summaryrefslogtreecommitdiffstats
path: root/extras/strongswan/vpp_sswan/README.rst
blob: 57b30f452e535af5b658523b4ad7a0b5522d1223 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
.. _vpp_sswan_doc:

VPP-SSWAN
=======================

``VPP-SSWAN`` is a StrongSwan plugin that helps offloading Strongswan IPsec ESP
process from Linux Kernel to ``VPP``.

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.

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``.
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
-------------

``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``

- unzip source code strongswan to:
``path/to/vpp/build-root/build-vpp-native/external/sswan``

- 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 ``vpp-swan plugin`` by:

::

   cd path/to/vpp/external/strongswan/vpp_swan/
   make

Build/install Strongswan (Optional)
-------------

In case you haven't installed ``Strongswan`` yet, you may use the following
simple command to compile and install ``Strongswan`` from the downloaded source.

::

   cd path/to/vpp/external/strongswan/vpp_swan/
   make pull-swan
   make install-swan

Install VPP-SWAN plugin into StrongSwan
-------------

After the ``VPP-SSWAN`` plugin has been built and ``Strongswan`` was installed,
the following command will install the ``VPP-SSWAN`` plugin into ``Strongswan``.

::

   cd path/to/vpp/external/strongswan/vpp_swan/
   make install

Or you can manually copy ``libstrongswan-kernel-vpp.so`` into:
``/usr/lib/ipsec/plugins``,
and also ``kernel-vpp.conf`` into: ``/etc/strongswan.d/charon/``

Now you can restart ``Strongswan`` by executing the following command:

::

   systemctl restart strongswan.service

Configuration Strongswan
-------------

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
-------------

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:

::

   plugins {
     plugin linux_cp_plugin.so { enable }
     plugin ikev2_plugin.so { disable }
    }

   linux-cp {
      lcp-sync
   }

Running VPP
-------------

Based on the provided sample ``swanctl.conf``, the following commands are
required to be executed in ``VPP``:

::

   lcp create eth2 host-if eth2
   set interface state eth2 up
   set interface ip address eth2 192.168.0.2/24
   set int state eth1 up
   set int ip addr eth1 192.168.200.1/24

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
-------------
This plugin is based on:
`https://github.com/matfabia/strongswan
<https://github.com/matfabia/strongswan>`__

Author: Matus Fabian <matfabia@cisco.com>