doc: update ipsec-secgw guide and release notes
authorKonstantin Ananyev <konstantin.ananyev@intel.com>
Thu, 10 Jan 2019 21:09:13 +0000 (21:09 +0000)
committerPablo de Lara <pablo.de.lara.guarch@intel.com>
Thu, 10 Jan 2019 15:57:22 +0000 (16:57 +0100)
Update ipsec-secgw guide and release notes to reflect latest changes.

Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>
Signed-off-by: Konstantin Ananyev <konstantin.ananyev@intel.com>
Acked-by: Akhil Goyal <akhil.goyal@nxp.com>
doc/guides/rel_notes/release_19_02.rst
doc/guides/sample_app_ug/ipsec_secgw.rst

index 6dd4dac..5a46f1a 100644 (file)
@@ -123,6 +123,20 @@ New Features
 
   See :doc:`../prog_guide/ipsec_lib` for more information.
 
 
   See :doc:`../prog_guide/ipsec_lib` for more information.
 
+* **Updated the ipsec-secgw sample application.**
+
+  The ``ipsec-secgw`` sample application has been updated to use the new
+  ``librte_ipsec`` library also added in this release.
+  The original functionality of ipsec-secgw is retained, a new command line
+  parameter ``-l`` has  been added to ipsec-secgw to use the IPsec library,
+  instead of the existing IPsec code in the application.
+
+  The IPsec library does not support all the functionality of the existing
+  ipsec-secgw application, its is planned to add the outstanding functionality
+  in future releases.
+
+  See :doc:`../sample_app_ug/ipsec_secgw` for more information.
+
 * **Enabled checksum support in the ISA-L compressdev driver.**
 
   Added support for both adler and crc32 checksums in the ISA-L PMD.
 * **Enabled checksum support in the ISA-L compressdev driver.**
 
   Added support for both adler and crc32 checksums in the ISA-L PMD.
index 61638e7..3d784e7 100644 (file)
@@ -76,7 +76,7 @@ Compiling the Application
 
 To compile the sample application see :doc:`compiling`.
 
 
 To compile the sample application see :doc:`compiling`.
 
-The application is located in the ``rpsec-secgw`` sub-directory.
+The application is located in the ``ipsec-secgw`` sub-directory.
 
 #. [Optional] Build the application for debugging:
    This option adds some extra flags, disables compiler optimizations and
 
 #. [Optional] Build the application for debugging:
    This option adds some extra flags, disables compiler optimizations and
@@ -93,6 +93,7 @@ The application has a number of command line options::
 
    ./build/ipsec-secgw [EAL options] --
                         -p PORTMASK -P -u PORTMASK -j FRAMESIZE
 
    ./build/ipsec-secgw [EAL options] --
                         -p PORTMASK -P -u PORTMASK -j FRAMESIZE
+                        -l -w REPLAY_WINOW_SIZE -e -a
                         --config (port,queue,lcore)[,(port,queue,lcore]
                         --single-sa SAIDX
                         --rxoffload MASK
                         --config (port,queue,lcore)[,(port,queue,lcore]
                         --single-sa SAIDX
                         --rxoffload MASK
@@ -114,6 +115,18 @@ Where:
     specified as FRAMESIZE. If an invalid value is provided as FRAMESIZE
     then the default value 9000 is used.
 
     specified as FRAMESIZE. If an invalid value is provided as FRAMESIZE
     then the default value 9000 is used.
 
+*   ``-l``: enables code-path that uses librte_ipsec.
+
+*   ``-w REPLAY_WINOW_SIZE``: specifies the IPsec sequence number replay window
+    size for each Security Association (available only with librte_ipsec
+    code path).
+
+*   ``-e``: enables Security Association extended sequence number processing
+    (available only with librte_ipsec code path).
+
+*   ``-a``: enables Security Association sequence number atomic behaviour
+    (available only with librte_ipsec code path).
+
 *   ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues
     from which ports are mapped to which cores.
 
 *   ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues
     from which ports are mapped to which cores.
 
@@ -225,7 +238,7 @@ accordingly.
 
 
 Configuration File Syntax
 
 
 Configuration File Syntax
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 As mention in the overview, the Security Policies are ACL rules.
 The application parsers the rules specified in the configuration file and
 
 As mention in the overview, the Security Policies are ACL rules.
 The application parsers the rules specified in the configuration file and
@@ -571,6 +584,11 @@ Example SA rules:
     mode ipv4-tunnel src 172.16.1.5 dst 172.16.2.5 \
     type lookaside-protocol-offload port_id 4
 
     mode ipv4-tunnel src 172.16.1.5 dst 172.16.2.5 \
     type lookaside-protocol-offload port_id 4
 
+    sa in 35 aead_algo aes-128-gcm \
+    aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
+    mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 \
+    type inline-crypto-offload port_id 0
+
 Routing rule syntax
 ^^^^^^^^^^^^^^^^^^^
 
 Routing rule syntax
 ^^^^^^^^^^^^^^^^^^^
 
@@ -667,3 +685,86 @@ Example Neighbour rules:
 .. code-block:: console
 
     neigh port 0 DE:AD:BE:EF:01:02
 .. code-block:: console
 
     neigh port 0 DE:AD:BE:EF:01:02
+
+Test directory
+--------------
+
+The test directory contains scripts for testing the various encryption
+algorithms.
+
+The purpose of the scripts is to automate ipsec-secgw testing
+using another system running linux as a DUT.
+
+The user must setup the following environment variables:
+
+*   ``SGW_PATH``: path to the ipsec-secgw binary to test.
+
+*   ``REMOTE_HOST``: IP address/hostname of the DUT.
+
+*   ``REMOTE_IFACE``: interface name for the test-port on the DUT.
+
+*   ``ETH_DEV``: ethernet device to be used on the SUT by DPDK ('-w <pci-id>')
+
+Also the user can optionally setup:
+
+*   ``SGW_LCORE``: lcore to run ipsec-secgw on (default value is 0)
+
+*   ``CRYPTO_DEV``: crypto device to be used ('-w <pci-id>'). If none specified
+    appropriate vdevs will be created by the script
+
+Note that most of the tests require the appropriate crypto PMD/device to be
+available.
+
+Server configuration
+~~~~~~~~~~~~~~~~~~~~
+
+Two servers are required for the tests, SUT and DUT.
+
+Make sure the user from the SUT can ssh to the DUT without entering the password.
+To enable this feature keys must be setup on the DUT.
+
+``ssh-keygen`` will make a private & public key pair on the SUT.
+
+``ssh-copy-id`` <user name>@<target host name> on the SUT will copy the public
+key to the DUT. It will ask for credentials so that it can upload the public key.
+
+The SUT and DUT are connected through at least 2 NIC ports.
+
+One NIC port is expected to be managed by linux on both machines and will be
+used as a control path.
+
+The second NIC port (test-port) should be bound to DPDK on the SUT, and should
+be managed by linux on the DUT.
+
+The script starts ``ipsec-secgw`` with 2 NIC devices: ``test-port`` and
+``tap vdev``.
+
+It then configures the local tap interface and the remote interface and IPsec
+policies in the following way:
+
+Traffic going over the test-port in both directions has to be protected by IPsec.
+
+Traffic going over the TAP port in both directions does not have to be protected.
+
+i.e:
+
+DUT OS(NIC1)--(IPsec)-->(NIC1)ipsec-secgw(TAP)--(plain)-->(TAP)SUT OS
+
+SUT OS(TAP)--(plain)-->(TAP)psec-secgw(NIC1)--(IPsec)-->(NIC1)DUT OS
+
+It then tries to perform some data transfer using the scheme decribed above.
+
+usage
+~~~~~
+
+In the ipsec-secgw/test directory
+
+to run one test for IPv4 or IPv6
+
+/bin/bash linux_test(4|6).sh <ipsec_mode>
+
+to run all tests for IPv4 or IPv6
+
+/bin/bash run_test.sh -4|-6
+
+For the list of available modes please refer to run_test.sh.