docs: ikev2 usecases

Type: docs

Change-Id: Ib607b9426572585c1c7bfc4fcbbb1591ff5d9d42
Signed-off-by: Filip Tehlar <ftehlar@cisco.com>

6 files changed, 537 insertions, 2 deletions

diff --git a/docs/about.rst b/docs/about.rst
index 808f6f159a7..7f9a88d378e 100644
--- a/docs/about.rst
+++ b/docs/about.rst
@@ -4,6 +4,6 @@
 About
 =====
 
-**VPP Version:** 21.01-rc0~354-g77402be67
+**VPP Version:** 21.06-rc0~304-ga73e7568c
 
-**Built on:** Fri Nov 20 13:50:49 GMT 2020
+**Built on:** Fri Feb 19 23:40:45 GMT 2021
diff --git a/docs/usecases/2_vpp.md b/docs/usecases/2_vpp.md
new file mode 100644
index 00000000000..d5f92818903
--- /dev/null
+++ b/docs/usecases/2_vpp.md
@@ -0,0 +1,128 @@
+How to connect VPP instances using IKEv2
+========================================
+
+This section describes how to initiate IKEv2 session between two VPP instances
+using Linux veth interfaces and namespaces.
+
+
+Create veth interfaces and namespaces and configure it:
+
+```
+sudo ip link add ifresp type veth peer name ifinit
+sudo ip link set dev ifresp up
+sudo ip link set dev ifinit up
+
+sudo ip netns add clientns
+sudo ip netns add serverns
+sudo ip link add veth_client type veth peer name client
+sudo ip link add veth_server type veth peer name server
+sudo ip link set dev veth_client up netns clientns
+sudo ip link set dev veth_server up netns serverns
+
+sudo ip netns exec clientns \
+      bash -c "
+              ip link set dev lo up
+              ip addr add 192.168.5.2/24 dev veth_client
+              ip addr add fec5::2/16 dev veth_client
+              ip route add 192.168.3.0/24 via 192.168.5.1
+              ip route add fec3::0/16 via fec5::1
+      "
+
+sudo ip netns exec serverns \
+      bash -c "
+              ip link set dev lo up
+              ip addr add 192.168.3.2/24 dev veth_server
+              ip addr add fec3::2/16 dev veth_server
+              ip route add 192.168.5.0/24 via 192.168.3.1
+              ip route add fec5::0/16 via fec3::1
+      "
+```
+
+Run responder VPP:
+
+```
+sudo /usr/bin/vpp unix { \
+      cli-listen /tmp/vpp_resp.sock \
+      gid $(id -g) } \
+      api-segment { prefix vpp } \
+      plugins { plugin dpdk_plugin.so { disable } }
+```
+
+Configure the responder
+
+
+```
+create host-interface name ifresp
+set interface ip addr host-ifresp 192.168.10.2/24
+set interface state host-ifresp up
+
+create host-interface name server
+set interface ip addr host-server 192.168.3.1/24
+set interface state host-server up
+
+ikev2 profile add pr1
+ikev2 profile set pr1 auth shared-key-mic string Vpp123
+ikev2 profile set pr1 id local ipv4 192.168.10.2
+ikev2 profile set pr1 id remote ipv4 192.168.10.1
+
+ikev2 profile set pr1 traffic-selector local ip-range 192.168.3.0 - 192.168.3.255 port-range 0 - 65535 protocol 0
+ikev2 profile set pr1 traffic-selector remote ip-range 192.168.5.0 - 192.168.5.255 port-range 0 - 65535 protocol 0
+
+create ipip tunnel src 192.168.10.2 dst 192.168.10.1
+ikev2 profile set pr1 tunnel ipip0
+ip route add 192.168.5.0/24 via 192.168.10.1 ipip0
+set interface unnumbered ipip0 use host-ifresp
+```
+
+Run initiator VPP:
+
+```
+sudo /usr/bin/vpp unix { \
+      cli-listen /tmp/vpp_init.sock \
+      gid $(id -g) } \
+      api-segment { prefix vpp } \
+      plugins { plugin dpdk_plugin.so { disable } }
+```
+
+Configure initiator:
+```
+create host-interface name ifinit
+set interface ip addr host-ifinit 192.168.10.1/24
+set interface state host-ifinit up
+
+create host-interface name client
+set interface ip addr host-client 192.168.5.1/24
+set interface state host-client up
+
+ikev2 profile add pr1
+ikev2 profile set pr1 auth shared-key-mic string Vpp123
+ikev2 profile set pr1 id local ipv4 192.168.10.1
+ikev2 profile set pr1 id remote ipv4 192.168.10.2
+
+ikev2 profile set pr1 traffic-selector remote ip-range 192.168.3.0 - 192.168.3.255 port-range 0 - 65535 protocol 0
+ikev2 profile set pr1 traffic-selector local ip-range 192.168.5.0 - 192.168.5.255 port-range 0 - 65535 protocol 0
+
+ikev2 profile set pr1 responder host-ifinit 192.168.10.2
+ikev2 profile set pr1 ike-crypto-alg aes-gcm-16 256 ike-dh modp-2048
+ikev2 profile set pr1 esp-crypto-alg aes-gcm-16 256
+
+create ipip tunnel src 192.168.10.1 dst 192.168.10.2
+ikev2 profile set pr1 tunnel ipip0
+ip route add 192.168.3.0/24 via 192.168.10.2 ipip0
+set interface unnumbered ipip0 use host-ifinit
+```
+
+Initiate the IKEv2 connection:
+
+```
+vpp# ikev2 initiate sa-init pr1
+```
+
+Responder's and initiator's private networks are now connected with IPSEC tunnel:
+
+```
+$ sudo ip netns exec clientns ping 192.168.3.1
+PING 192.168.3.1 (192.168.3.1) 56(84) bytes of data.
+64 bytes from 192.168.3.1: icmp_seq=1 ttl=63 time=1.64 ms
+64 bytes from 192.168.3.1: icmp_seq=2 ttl=63 time=7.24 ms
+```
diff --git a/docs/usecases/ikev2.rst b/docs/usecases/ikev2.rst
new file mode 100644
index 00000000000..853b22ef738
--- /dev/null
+++ b/docs/usecases/ikev2.rst
@@ -0,0 +1,14 @@
+.. _ikev2:
+
+IKEv2 in VPP
+============
+
+This sections describes some of the ways to establish IKEv2 connection
+between two VPP instances or VPP and strongSwan. It covers scenarios in
+which VPP is the IKEv2 responder (and strongSwan initiator) and vice versa.
+
+.. toctree::
+
+    vpp_resp_sswan_init
+    vpp_init_sswan_resp
+    2_vpp
diff --git a/docs/usecases/index.rst b/docs/usecases/index.rst
index a0364f1143a..d33e9c5fcc7 100644
--- a/docs/usecases/index.rst
+++ b/docs/usecases/index.rst
@@ -21,3 +21,4 @@ extensive list, but should give a sampling of the many features contained in FD.
    webapp
    container_test
    trafficgen
+   ikev2
diff --git a/docs/usecases/vpp_init_sswan_resp.md b/docs/usecases/vpp_init_sswan_resp.md
new file mode 100644
index 00000000000..40da137cbd2
--- /dev/null
+++ b/docs/usecases/vpp_init_sswan_resp.md
@@ -0,0 +1,195 @@
+VPP as IKEv2 initiator and strongSwan as responder
+==================================================
+
+Prerequisites
+-------------
+
+To make the examples easier to configure ``docker`` it is required to pull strongSwan docker image. The networking is done using Linux' veth interfaces and namespaces.
+
+Setup
+-----
+
+First a topology:
+
+```
+192.168.3.2                      192.168.5.2
+     +                           loopback
+     |                                 +
++----+----+ 192.168.10.2         +-----+----+
+|  VPP    |                      |strongSwan|
+|initiator+----------------------+responder |
++---------+                      +----------+
+                     192.168.10.1
+```
+
+Create veth interfaces and namespaces and configure them:
+
+```
+sudo ip link add gw type veth peer name swanif
+sudo ip link set dev gw up
+
+sudo ip netns add ns
+sudo ip link add veth_priv type veth peer name priv
+sudo ip link set dev priv up
+sudo ip link set dev veth_priv up netns ns
+
+sudo ip netns exec ns \
+  bash -c "
+    ip link set dev lo up
+    ip addr add 192.168.3.2/24 dev veth_priv
+    ip route add 192.168.5.0/24 via 192.168.3.1"
+```
+
+
+Create directory with strongswan configs that will be mounted to the docker container
+```
+mkdir /tmp/sswan
+```
+
+Create the ``ipsec.conf`` file in the ``/tmp/sswan`` directory with following content:
+
+```
+config setup
+  strictcrlpolicy=no
+
+conn initiator
+  mobike=no
+  auto=add
+  type=tunnel
+  keyexchange=ikev2
+  ike=aes256gcm16-prfsha256-modp2048!
+  esp=aes256gcm16-esn!
+
+# local:
+  leftauth=psk
+  leftid=@sswan.vpn.example.com
+  leftsubnet=192.168.5.0/24
+
+# remote: (gateway)
+  rightid=@roadwarrior.vpp
+  right=192.168.10.2
+  rightauth=psk
+  rightsubnet=192.168.3.0/24
+```
+
+``/tmp/sswan/ipsec.secrets``
+```
+: PSK 'Vpp123'
+```
+
+``/tmp/sswan/strongswan.conf``
+```
+charon {
+  load_modular = yes
+  plugins {
+    include strongswan.d/charon/*.conf
+  }
+  filelog {
+    /tmp/charon.log {
+      time_format = %b %e %T
+      ike_name = yes
+      append = no
+      default = 2
+      flush_line = yes
+    }
+  }
+}
+include strongswan.d/*.conf
+```
+
+Start docker container with strongSwan:
+
+```
+ docker run --name sswan -d --privileged --rm --net=none \
+  -v /tmp/sswan:/conf -v /tmp/sswan:/etc/ipsec.d philplckthun/strongswan
+```
+
+Finish configuration of initiator's private network:
+
+```
+pid=$(docker inspect --format "{{.State.Pid}}" sswan)
+sudo ip link set netns $pid dev swanif
+
+sudo nsenter -t $pid -n ip addr add 192.168.10.1/24 dev swanif
+sudo nsenter -t $pid -n ip link set dev swanif up
+
+sudo nsenter -t $pid -n ip addr add 192.168.5.2/32 dev lo
+sudo nsenter -t $pid -n ip link set dev lo up
+```
+
+Start VPP ...
+
+```
+sudo /usr/bin/vpp unix { \
+      cli-listen /tmp/vpp.sock \
+      gid $(id -g) } \
+      api-segment { prefix vpp } \
+      plugins { plugin dpdk_plugin.so { disable } }
+```
+
+... and configure it:
+
+```
+create host-interface name gw
+set interface ip addr host-gw 192.168.10.2/24
+set interface state host-gw up
+
+create host-interface name priv
+set interface ip addr host-priv 192.168.3.1/24
+set interface state host-priv up
+
+ikev2 profile add pr1
+ikev2 profile set pr1 auth shared-key-mic string Vpp123
+ikev2 profile set pr1 id local fqdn roadwarrior.vpp
+ikev2 profile set pr1 id remote fqdn sswan.vpn.example.com
+
+ikev2 profile set pr1 traffic-selector local ip-range 192.168.3.0 - 192.168.3.255 port-range 0 - 65535 protocol 0
+ikev2 profile set pr1 traffic-selector remote ip-range 192.168.5.0 - 192.168.5.255 port-range 0 - 65535 protocol 0
+
+ikev2 profile set pr1 responder host-gw 192.168.10.1
+ikev2 profile set pr1 ike-crypto-alg aes-gcm-16 256 ike-dh modp-2048
+ikev2 profile set pr1 esp-crypto-alg aes-gcm-16 256
+
+create ipip tunnel src 192.168.10.2 dst 192.168.10.1
+ikev2 profile set pr1 tunnel ipip0
+ip route add 192.168.5.0/24 via 192.168.10.1 ipip0
+set interface unnumbered ipip0 use host-gw
+```
+
+Initiate the IKEv2 connection:
+
+```
+vpp# ikev2 initiate sa-init pr1
+```
+
+```
+vpp# show ikev2 sa details
+ iip 192.168.10.2 ispi f717b0cbd17e27c3 rip 192.168.10.1 rspi e9b7af7fc9b13361
+ encr:aes-gcm-16 prf:hmac-sha2-256  dh-group:modp-2048
+ nonce i:eb0354613b268c6372061bbdaab13deca37c8a625b1f65c073d25df2ecfe672e
+       r:70e1248ac09943047064f6a2135fa2a424778ba03038ab9c4c2af8aba179ed84
+ SK_d    96bd4feb59be2edf1930a12a3a5d22e30195ee9f56ea203c5fb6cba5dd2bb80f
+ SK_e  i:00000000: 5b75b9d808c8467fd00a0923c06efee2a4eb1d033c57532e05f9316ed9c56fe9
+         00000020: c4db9114
+       r:00000000: 95121b63372d20b83558dc3e209b9affef042816cf071c86a53543677b40c15b
+         00000020: f169ab67
+ SK_p  i:fb40d1114c347ddc3228ba004d4759d58f9c1ae6f1746833f908d39444ef92b1
+       r:aa049828240cb242e1d5aa625cd5914dc8f8e980a74de8e06883623d19384902
+ identifier (i) id-type fqdn data roadwarrior.vpp
+ identifier (r) id-type fqdn data sswan.vpn.example.com
+   child sa 0:encr:aes-gcm-16  esn:yes
+    spi(i) 9dffd57a spi(r) c4e0ef53
+    SK_e  i:290c681694f130b33d511335dd257e78721635b7e8aa87930dd77bb1d6dd3f42
+          r:0a09fa18cf1cf65c6324df02b46dcc998b84e5397cf911b63e0c096053946c2e
+    traffic selectors (i):0 type 7 protocol_id 0 addr 192.168.3.0 - 192.168.3.255 port 0 - 65535
+    traffic selectors (r):0 type 7 protocol_id 0 addr 192.168.5.0 - 192.168.5.255 port 0 - 65535
+```
+
+Now we can generate some traffic between responder's and initiator's private networks and see it works.
+
+```
+$ sudo ip netns exec ns ping 192.168.5.2
+PING 192.168.5.2 (192.168.5.2) 56(84) bytes of data.
+64 bytes from 192.168.5.2: icmp_seq=1 ttl=63 time=0.450 ms
+64 bytes from 192.168.5.2: icmp_seq=2 ttl=63 time=0.630 ms
+```
diff --git a/docs/usecases/vpp_resp_sswan_init.md b/docs/usecases/vpp_resp_sswan_init.md
new file mode 100644
index 00000000000..613a4b69cf6
--- /dev/null
+++ b/docs/usecases/vpp_resp_sswan_init.md
@@ -0,0 +1,197 @@
+VPP as IKEv2 responder and strongSwan as initiator
+==================================================
+
+
+Prerequisites
+-------------
+
+To make the examples easier to configure ``docker`` it is required to pull strongSwan docker image. The networking is done using Linux' veth interfaces and namespaces.
+
+Setup
+-----
+
+First a topology:
+
+```
+192.168.3.2                      192.168.5.2
+     +                           loopback
+     |                                 +
++----+----+ 192.168.10.2         +-----+----+
+|  VPP    |                      |initiator |
+|responder+----------------------+strongSwan|
++---------+                      +----------+
+                     192.168.10.1
+```
+
+Create veth interfaces and namespaces and configure them:
+
+```
+sudo ip link add gw type veth peer name swanif
+sudo ip link set dev gw up
+
+sudo ip netns add ns
+sudo ip link add veth_priv type veth peer name priv
+sudo ip link set dev priv up
+sudo ip link set dev veth_priv up netns ns
+
+sudo ip netns exec ns \
+  bash -c "
+    ip link set dev lo up
+    ip addr add 192.168.3.2/24 dev veth_priv
+    ip route add 192.168.5.0/24 via 192.168.3.1"
+```
+
+
+Create directory with strongswan configs that will be mounted to the docker container
+```
+mkdir /tmp/sswan
+```
+
+Create the ``ipsec.conf`` file in the ``/tmp/sswan`` directory with following content:
+```
+config setup
+ strictcrlpolicy=no
+
+conn initiator
+ mobike=no
+ auto=add
+ type=tunnel
+ keyexchange=ikev2
+ ike=aes256gcm16-prfsha256-modp2048!
+ esp=aes256gcm16-esn!
+
+ # local:
+ leftauth=psk
+ leftid=@roadwarrior.vpn.example.com
+ leftsubnet=192.168.5.0/24
+
+ # remote: (vpp gateway)
+ rightid=@vpp.home
+ right=192.168.10.2
+ rightauth=psk
+ rightsubnet=192.168.3.0/24
+```
+
+``/tmp/sswan/ipsec.secrets``
+```
+: PSK 'Vpp123'
+```
+
+``/tmp/sswan/strongswan.conf``
+```
+charon {
+  load_modular = yes
+  plugins {
+    include strongswan.d/charon/*.conf
+  }
+  filelog {
+    /tmp/charon.log {
+      time_format = %b %e %T
+      ike_name = yes
+      append = no
+      default = 2
+      flush_line = yes
+    }
+  }
+}
+include strongswan.d/*.conf
+```
+
+Start docker container with strongSwan:
+
+```
+ docker run --name sswan -d --privileged --rm --net=none \
+  -v /tmp/sswan:/conf -v /tmp/sswan:/etc/ipsec.d philplckthun/strongswan
+```
+
+Finish configuration of initiator's private network:
+
+```
+pid=$(docker inspect --format "{{.State.Pid}}" sswan)
+sudo ip link set netns $pid dev swanif
+
+sudo nsenter -t $pid -n ip addr add 192.168.10.1/24 dev swanif
+sudo nsenter -t $pid -n ip link set dev swanif up
+
+sudo nsenter -t $pid -n ip addr add 192.168.5.2/32 dev lo
+sudo nsenter -t $pid -n ip link set dev lo up
+```
+
+Start VPP ...
+
+```
+sudo /usr/bin/vpp unix { \
+      cli-listen /tmp/vpp.sock \
+      gid $(id -g) } \
+      api-segment { prefix vpp } \
+      plugins { plugin dpdk_plugin.so { disable } }
+```
+
+... and configure it:
+
+```
+create host-interface name gw
+set interface ip addr host-gw 192.168.10.2/24
+set interface state host-gw up
+
+create host-interface name priv
+set interface ip addr host-priv 192.168.3.1/24
+set interface state host-priv up
+
+ikev2 profile add pr1
+ikev2 profile set pr1 auth shared-key-mic string Vpp123
+ikev2 profile set pr1 id local fqdn vpp.home
+ikev2 profile set pr1 id remote fqdn roadwarrior.vpn.example.com
+
+ikev2 profile set pr1 traffic-selector local ip-range 192.168.3.0 - 192.168.3.255 port-range 0 - 65535 protocol 0
+ikev2 profile set pr1 traffic-selector remote ip-range 192.168.5.0 - 192.168.5.255 port-range 0 - 65535 protocol 0
+
+create ipip tunnel src 192.168.10.2 dst 192.168.10.1
+ikev2 profile set pr1 tunnel ipip0
+ip route add 192.168.5.0/24 via 192.168.10.1 ipip0
+set interface unnumbered ipip0 use host-gw
+```
+
+Initiate the IKEv2 connection:
+
+```
+$ sudo docker exec sswan ipsec up initiator
+
+...
+CHILD_SA initiator{1} established with SPIs c320c95f_i 213932c2_o and TS 192.168.5.0/24 === 192.168.3.0/24
+connection 'initiator' established successfully
+```
+
+```
+vpp# show ikev2 sa details
+
+iip 192.168.10.1 ispi 7849021d9f655f1b rip 192.168.10.2 rspi 5a9ca7469a035205
+ encr:aes-gcm-16 prf:hmac-sha2-256  dh-group:modp-2048
+ nonce i:692ce8fd8f1c1934f63bfa2b167c4de2cff25640dffe938cdfe01a5d7f6820e6
+       r:3ed84a14ea8526063e5aa762312be225d33e866d7152b9ce23e50f0ededca9e3
+ SK_d    9a9b896ed6c35c78134fcd6e966c04868b6ecacf6d5088b4b2aee8b05d30fdda
+ SK_e  i:00000000: 1b1619788d8c812ca5916c07e635bda860f15293099f3bf43e8d88e52074b006
+         00000020: 72c8e3e3
+       r:00000000: 89165ceb2cef6a6b3319f437386292d9ef2e96d8bdb21eeb0cb0d3b92733de03
+         00000020: bbc29c50
+ SK_p  i:fe35fca30985ee75e7c8bc0d7bc04db7a0e1655e997c0f5974c31458826b6fef
+       r:0dd318662a96a25fcdf4998d8c6e4180c67c03586cf91dab26ed43aeda250272
+ identifier (i) id-type fqdn data roadwarrior.vpn.example.com
+ identifier (r) id-type fqdn data vpp.home
+   child sa 0:encr:aes-gcm-16  esn:yes
+    spi(i) c320c95f spi(r) 213932c2
+    SK_e  i:2a6c9eae9dbed202c0ae6ccc001621aba5bb0b01623d4de4d14fd27bd5185435
+          r:15e2913d39f809040ca40a02efd27da298b6de05f67bd8f10210da5e6ae606fb
+    traffic selectors (i):0 type 7 protocol_id 0 addr 192.168.5.0 - 192.168.5.255 port 0 - 65535
+    traffic selectors (r):0 type 7 protocol_id 0 addr 192.168.3.0 - 192.168.3.255 port 0 - 65535
+
+```
+
+Now we can generate some traffic between responder's and initiator's private networks and see it works.
+
+```
+$ sudo ip netns exec ns ping 192.168.5.2
+PING 192.168.5.2 (192.168.5.2) 56(84) bytes of data.
+64 bytes from 192.168.5.2: icmp_seq=1 ttl=63 time=1.02 ms
+64 bytes from 192.168.5.2: icmp_seq=2 ttl=63 time=0.599 ms
+```