X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fsample_app_ug%2Fipsec_secgw.rst;h=81c5d43606159a4cb62d29162f716eebfce2c6c1;hb=0b133c36ad7d5fdce852b060d69019d69d48a7cb;hp=fcb33c26cbca4d79e3bc4f3acecefbdbd06132c8;hpb=913154efa7ffb9f71bcf51d16b2043ccba6c5be7;p=dpdk.git diff --git a/doc/guides/sample_app_ug/ipsec_secgw.rst b/doc/guides/sample_app_ug/ipsec_secgw.rst index fcb33c26cb..81c5d43606 100644 --- a/doc/guides/sample_app_ug/ipsec_secgw.rst +++ b/doc/guides/sample_app_ug/ipsec_secgw.rst @@ -1,32 +1,6 @@ -.. BSD LICENSE - Copyright(c) 2016 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016-2017 Intel Corporation. + Copyright (C) 2020 Marvell International Ltd. IPsec Security Gateway Sample Application ========================================= @@ -52,13 +26,28 @@ The application classifies the ports as *Protected* and *Unprotected*. Thus, traffic received on an Unprotected or Protected port is consider Inbound or Outbound respectively. +The application also supports complete IPsec protocol offload to hardware +(Look aside crypto accelerator or using ethernet device). It also support +inline ipsec processing by the supported ethernet device during transmission. +These modes can be selected during the SA creation configuration. + +In case of complete protocol offload, the processing of headers(ESP and outer +IP header) is done by the hardware and the application does not need to +add/remove them during outbound/inbound processing. + +For inline offloaded outbound traffic, the application will not do the LPM +lookup for routing, as the port on which the packet has to be forwarded will be +part of the SA. Security parameters will be configured on that port only, and +sending the packet on other ports could result in unencrypted packets being +sent out. + The Path for IPsec Inbound traffic is: * Read packets from the port. * Classify packets between IPv4 and ESP. * Perform Inbound SA lookup for ESP packets based on their SPI. -* Perform Verification/Decryption. -* Remove ESP and outer IP header +* Perform Verification/Decryption (Not needed in case of inline ipsec). +* Remove ESP and outer IP header (Not needed in case of protocol offload). * Inbound SP check using ACL of decrypted packets and any other IPv4 packets. * Routing. * Write packet to port. @@ -68,42 +57,64 @@ The Path for the IPsec Outbound traffic is: * Read packets from the port. * Perform Outbound SP check using ACL of all IPv4 traffic. * Perform Outbound SA lookup for packets that need IPsec protection. -* Add ESP and outer IP header. -* Perform Encryption/Digest. +* Add ESP and outer IP header (Not needed in case protocol offload). +* Perform Encryption/Digest (Not needed in case of inline ipsec). * Routing. * Write packet to port. +The application supports two modes of operation: poll mode and event mode. + +* In the poll mode a core receives packets from statically configured list + of eth ports and eth ports' queues. + +* In the event mode a core receives packets as events. After packet processing + is done core submits them back as events to an event device. This enables + multicore scaling and HW assisted scheduling by making use of the event device + capabilities. The event mode configuration is predefined. All packets reaching + given eth port will arrive at the same event queue. All event queues are mapped + to all event ports. This allows all cores to receive traffic from all ports. + Since the underlying event device might have varying capabilities, the worker + threads can be drafted differently to maximize performance. For example, if an + event device - eth device pair has Tx internal port, then application can call + rte_event_eth_tx_adapter_enqueue() instead of regular rte_event_enqueue_burst(). + So a thread which assumes that the device pair has internal port will not be the + right solution for another pair. The infrastructure added for the event mode aims + to help application to have multiple worker threads by maximizing performance from + every type of event device without affecting existing paths/use cases. The worker + to be used will be determined by the operating conditions and the underlying device + capabilities. **Currently the application provides non-burst, internal port worker + threads and supports inline protocol only.** It also provides infrastructure for + non-internal port however does not define any worker threads. + +Additionally the event mode introduces two submodes of processing packets: + +* Driver submode: This submode has bare minimum changes in the application to support + IPsec. There are no lookups, no routing done in the application. And for inline + protocol use case, the worker thread resembles l2fwd worker thread as the IPsec + processing is done entirely in HW. This mode can be used to benchmark the raw + performance of the HW. The driver submode is selected with --single-sa option + (used also by poll mode). When --single-sa option is used in conjution with event + mode then index passed to --single-sa is ignored. + +* App submode: This submode has all the features currently implemented with the + application (non librte_ipsec path). All the lookups, routing follows existing + methods and report numbers that can be compared against regular poll mode + benchmark numbers. Constraints ----------- * No IPv6 options headers. * No AH mode. -* Currently only EAS-CBC, HMAC-SHA1 and NULL. +* Supported algorithms: AES-CBC, AES-CTR, AES-GCM, 3DES-CBC, HMAC-SHA1 and NULL. * Each SA must be handle by a unique lcore (*1 RX queue per port*). -* No chained mbufs. - Compiling the Application ------------------------- -To compile the application: - -#. Go to the sample application directory:: - - export RTE_SDK=/path/to/rte_sdk - cd ${RTE_SDK}/examples/ipsec-secgw - -#. Set the target (a default target is used if not specified). For example:: - - - export RTE_TARGET=x86_64-native-linuxapp-gcc +To compile the sample application see :doc:`compiling`. - See the *DPDK Getting Started Guide* for possible RTE_TARGET values. - -#. Build the application:: - - make +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 @@ -119,10 +130,21 @@ The application has a number of command line options:: ./build/ipsec-secgw [EAL options] -- - -p PORTMASK -P -u PORTMASK - --config (port,queue,lcore)[,(port,queue,lcore] + -p PORTMASK -P -u PORTMASK -j FRAMESIZE + -l -w REPLAY_WINOW_SIZE -e -a + -c SAD_CACHE_SIZE + -s NUMBER_OF_MBUFS_IN_PACKET_POOL + -f CONFIG_FILE_PATH + --config (port,queue,lcore)[,(port,queue,lcore)] --single-sa SAIDX - --ep0|--ep1 + --cryptodev_mask MASK + --transfer-mode MODE + --event-schedule-type TYPE + --rxoffload MASK + --txoffload MASK + --reassemble NUM + --mtu MTU + --frag-ttl FRAG_TTL_NS Where: @@ -135,31 +157,100 @@ Where: * ``-u PORTMASK``: hexadecimal bitmask of unprotected ports -* ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues - from which ports are mapped to which cores. - -* ``--single-sa SAIDX``: use a single SA for outbound traffic, bypassing the SP - on both Inbound and Outbound. This option is meant for debugging/performance - purposes. - -* ``--ep0``: configure the app as Endpoint 0. - -* ``--ep1``: configure the app as Endpoint 1. +* ``-j FRAMESIZE``: *optional*. data buffer size (in bytes), + in other words maximum data size for one segment. + Packets with length bigger then FRAMESIZE still can be received, + but will be segmented. + Default value: RTE_MBUF_DEFAULT_BUF_SIZE (2176) + Minimum value: RTE_MBUF_DEFAULT_BUF_SIZE (2176) + Maximum value: UINT16_MAX (65535). + +* ``-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 behavior + (available only with librte_ipsec code path). + +* ``-c``: specifies the SAD cache size. Stores the most recent SA in a per + lcore cache. Cache represents flat array containing SA's indexed by SPI. + Zero value disables cache. + Default value: 128. + +* ``-s``: sets number of mbufs in packet pool, if not provided number of mbufs + will be calculated based on number of cores, eth ports and crypto queues. + +* ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all + configuration items for running the application (See Configuration file + syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified. + **ONLY** the UNIX format configuration file is accepted. + +* ``--config (port,queue,lcore)[,(port,queue,lcore)]``: in poll mode determines + which queues from which ports are mapped to which cores. In event mode this + option is not used as packets are dynamically scheduled to cores by HW. + +* ``--single-sa SAIDX``: in poll mode use a single SA for outbound traffic, + bypassing the SP on both Inbound and Outbound. This option is meant for + debugging/performance purposes. In event mode selects driver submode, SA index + value is ignored. + +* ``--cryptodev_mask MASK``: hexadecimal bitmask of the crypto devices + to configure. + +* ``--transfer-mode MODE``: sets operating mode of the application + "poll" : packet transfer via polling (default) + "event" : Packet transfer via event device + +* ``--event-schedule-type TYPE``: queue schedule type, applies only when + --transfer-mode is set to event. + "ordered" : Ordered (default) + "atomic" : Atomic + "parallel" : Parallel + When --event-schedule-type is set as RTE_SCHED_TYPE_ORDERED/ATOMIC, event + device will ensure the ordering. Ordering will be lost when tried in PARALLEL. + +* ``--rxoffload MASK``: RX HW offload capabilities to enable/use on this port + (bitmask of DEV_RX_OFFLOAD_* values). It is an optional parameter and + allows user to disable some of the RX HW offload capabilities. + By default all HW RX offloads are enabled. + +* ``--txoffload MASK``: TX HW offload capabilities to enable/use on this port + (bitmask of DEV_TX_OFFLOAD_* values). It is an optional parameter and + allows user to disable some of the TX HW offload capabilities. + By default all HW TX offloads are enabled. + +* ``--reassemble NUM``: max number of entries in reassemble fragment table. + Zero value disables reassembly functionality. + Default value: 0. + +* ``--mtu MTU``: MTU value (in bytes) on all attached ethernet ports. + Outgoing packets with length bigger then MTU will be fragmented. + Incoming packets with length bigger then MTU will be discarded. + Default value: 1500. + +* ``--frag-ttl FRAG_TTL_NS``: fragment lifetime (in nanoseconds). + If packet is not reassembled within this time, received fragments + will be discarded. Fragment lifetime should be decreased when + there is a high fragmented traffic loss in high bandwidth networks. + Should be lower for low number of reassembly buckets. + Valid values: from 1 ns to 10 s. Default value: 10000000 (10 s). -Either one of ``--ep0`` or ``--ep1`` **must** be specified. -The main purpose of these options is to easily configure two systems -back-to-back that would forward traffic through an IPsec tunnel (see -:ref:`figure_ipsec_endpoints`). The mapping of lcores to port/queues is similar to other l3fwd applications. -For example, given the following command line:: +For example, given the following command line to run application in poll mode:: ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ - --vdev "cryptodev_null_pmd" -- -p 0xf -P -u 0x3 \ - --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" --ep0 \ + --vdev "crypto_null" -- -p 0xf -P -u 0x3 \ + --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ + -f /path/to/config_file --transfer-mode poll \ -where each options means: +where each option means: * The ``-l`` option enables cores 20 and 21. @@ -167,13 +258,13 @@ where each options means: * The ``--socket-mem`` to use 2GB on socket 1. -* The ``--vdev "cryptodev_null_pmd"`` option creates virtual NULL cryptodev PMD. +* The ``--vdev "crypto_null"`` option creates virtual NULL cryptodev PMD. * The ``-p`` option enables ports (detected) 0, 1, 2 and 3. * The ``-P`` option enables promiscuous mode. -* The ``-u`` option sets ports 1 and 2 as unprotected, leaving 2 and 3 as protected. +* The ``-u`` option sets ports 0 and 1 as unprotected, leaving 2 and 3 as protected. * The ``--config`` option enables one queue per port with the following mapping: @@ -194,8 +285,39 @@ where each options means: | | | | | +----------+-----------+-----------+---------------------------------------+ -* The ``--ep0`` options configures the app with a given set of SP, SA and Routing - entries as explained below in more detail. +* The ``-f /path/to/config_file`` option enables the application read and + parse the configuration file specified, and configures the application + with a given set of SP, SA and Routing entries accordingly. The syntax of + the configuration file will be explained below in more detail. Please + **note** the parser only accepts UNIX format text file. Other formats + such as DOS/MAC format will cause a parse error. + +* The ``--transfer-mode`` option selects poll mode for processing packets. + +Similarly for example, given the following command line to run application in +event app mode:: + + ./build/ipsec-secgw -c 0x3 -- -P -p 0x3 -u 0x1 \ + -f /path/to/config_file --transfer-mode event \ + --event-schedule-type parallel \ + +where each option means: + +* The ``-c`` option selects cores 0 and 1 to run on. + +* The ``-P`` option enables promiscuous mode. + +* The ``-p`` option enables ports (detected) 0 and 1. + +* The ``-u`` option sets ports 0 as unprotected, leaving 1 as protected. + +* The ``-f /path/to/config_file`` option has the same behavior as in poll + mode example. + +* The ``--transfer-mode`` option selects event mode for processing packets. + +* The ``--event-schedule-type`` option selects parallel ordering of event queues. + Refer to the *DPDK Getting Started Guide* for general information on running applications and the Environment Abstraction Layer (EAL) options. @@ -216,499 +338,621 @@ For example, something like the following command line: ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ -w 81:00.0 -w 81:00.1 -w 81:00.2 -w 81:00.3 \ - --vdev "cryptodev_aesni_mb_pmd" --vdev "cryptodev_null_pmd" \ + --vdev "crypto_aesni_mb" --vdev "crypto_null" \ -- \ -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ - --ep0 + -f sample.cfg Configurations -------------- -The following sections provide some details on the default values used to -initialize the SP, SA and Routing tables. -Currently all configuration information is hard coded into the application. +The following sections provide the syntax of configurations to initialize +your SP, SA, Routing and Neighbour tables. +Configurations shall be specified in the configuration file to be passed to +the application. The file is then parsed by the application. The successful +parsing will result in the appropriate rules being applied to the tables +accordingly. -The following image illustrate a few of the concepts regarding IPSec, such -as protected/unprotected and inbound/outbound traffic, from the point of -view of two back-to-back endpoints: -.. _figure_ipsec_endpoints: +Configuration File Syntax +~~~~~~~~~~~~~~~~~~~~~~~~~ -.. figure:: img/ipsec_endpoints.* +As mention in the overview, the Security Policies are ACL rules. +The application parsers the rules specified in the configuration file and +passes them to the ACL table, and replicates them per socket in use. - IPSec Inbound/Outbound traffic +Following are the configuration file syntax. -Note that the above image only displays unidirectional traffic per port -for illustration purposes. -The application supports bidirectional traffic on all ports, +General rule syntax +^^^^^^^^^^^^^^^^^^^ +The parse treats one line in the configuration file as one configuration +item (unless the line concatenation symbol exists). Every configuration +item shall follow the syntax of either SP, SA, Routing or Neighbour +rules specified below. -Security Policy Initialization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The configuration parser supports the following special symbols: -As mention in the overview, the Security Policies are ACL rules. -The application defines two ACLs, one each of Inbound and Outbound, and -it replicates them per socket in use. - -Following are the default rules which show only the relevant information, -assuming ANY value is valid for the fields not mentioned (src ip, proto, -src/dst ports). - -.. _table_ipsec_endpoint_outbound_sp: - -.. table:: Endpoint 0 Outbound Security Policies - - +-----------------------------------+------------+ - | **Dst** | **SA idx** | - | | | - +-----------------------------------+------------+ - | 192.168.105.0/24 | 5 | - | | | - +-----------------------------------+------------+ - | 192.168.106.0/24 | 6 | - | | | - +-----------------------------------+------------+ - | 192.168.175.0/24 | 10 | - | | | - +-----------------------------------+------------+ - | 192.168.176.0/24 | 11 | - | | | - +-----------------------------------+------------+ - | 192.168.200.0/24 | 15 | - | | | - +-----------------------------------+------------+ - | 192.168.201.0/24 | 16 | - | | | - +-----------------------------------+------------+ - | 192.168.55.0/24 | 25 | - | | | - +-----------------------------------+------------+ - | 192.168.56.0/24 | 26 | - | | | - +-----------------------------------+------------+ - | 192.168.240.0/24 | BYPASS | - | | | - +-----------------------------------+------------+ - | 192.168.241.0/24 | BYPASS | - | | | - +-----------------------------------+------------+ - | 0:0:0:0:5555:5555:0:0/96 | 5 | - | | | - +-----------------------------------+------------+ - | 0:0:0:0:6666:6666:0:0/96 | 6 | - | | | - +-----------------------------------+------------+ - | 0:0:1111:1111:0:0:0:0/96 | 10 | - | | | - +-----------------------------------+------------+ - | 0:0:1111:1111:1111:1111:0:0/96 | 11 | - | | | - +-----------------------------------+------------+ - | 0:0:0:0:aaaa:aaaa:0:0/96 | 25 | - | | | - +-----------------------------------+------------+ - | 0:0:0:0:bbbb:bbbb:0:0/96 | 26 | - | | | - +-----------------------------------+------------+ - -.. _table_ipsec_endpoint_inbound_sp: - -.. table:: Endpoint 0 Inbound Security Policies - - +-----------------------------------+------------+ - | **Dst** | **SA idx** | - | | | - +-----------------------------------+------------+ - | 192.168.115.0/24 | 105 | - | | | - +-----------------------------------+------------+ - | 192.168.116.0/24 | 106 | - | | | - +-----------------------------------+------------+ - | 192.168.185.0/24 | 110 | - | | | - +-----------------------------------+------------+ - | 192.168.186.0/24 | 111 | - | | | - +-----------------------------------+------------+ - | 192.168.210.0/24 | 115 | - | | | - +-----------------------------------+------------+ - | 192.168.211.0/24 | 116 | - | | | - +-----------------------------------+------------+ - | 192.168.65.0/24 | 125 | - | | | - +-----------------------------------+------------+ - | 192.168.66.0/24 | 126 | - | | | - +-----------------------------------+------------+ - | 192.168.245.0/24 | BYPASS | - | | | - +-----------------------------------+------------+ - | 192.168.246.0/24 | BYPASS | - | | | - +-----------------------------------+------------+ - | ffff:0:0:0:5555:5555:0:0/96 | 105 | - | | | - +-----------------------------------+------------+ - | ffff:0:0:0:6666:6666:0:0/96 | 106 | - | | | - +-----------------------------------+------------+ - | ffff:0:1111:1111:0:0:0:0/96 | 110 | - | | | - +-----------------------------------+------------+ - | ffff:0:1111:1111:1111:1111:0:0/96 | 111 | - | | | - +-----------------------------------+------------+ - | ffff:0:0:0:aaaa:aaaa:0:0/96 | 125 | - | | | - +-----------------------------------+------------+ - | ffff:0:0:0:bbbb:bbbb:0:0/96 | 126 | - | | | - +-----------------------------------+------------+ - -For Endpoint 1, we use the same policies in reverse, meaning the Inbound SP -entries are set as Outbound and vice versa. - - -Security Association Initialization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The SAs are kept in a array table. - -For Inbound, the SPI is used as index modulo the table size. -This means that on a table for 100 SA, SPI 5 and 105 would use the same index -and that is not currently supported. - -Notice that it is not an issue for Outbound traffic as we store the index and -not the SPI in the Security Policy. - -All SAs configured with AES-CBC and HMAC-SHA1 share the same values for cipher -block size and key, and authentication digest size and key. - -The following are the default values: - -.. _table_ipsec_endpoint_outbound_sa: - -.. table:: Endpoint 0 Outbound Security Associations - - +---------+----------+------------+-----------+----------------+----------------+ - | **SPI** | **Mode** | **Cipher** | **Auth** | **Tunnel src** | **Tunnel dst** | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 5 | Tunnel | AES-CBC | HMAC-SHA1 | 172.16.1.5 | 172.16.2.5 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 6 | Tunnel | AES-CBC | HMAC-SHA1 | 172.16.1.6 | 172.16.2.6 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 10 | Trans | AES-CBC | HMAC-SHA1 | N/A | N/A | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 11 | Trans | AES-CBC | HMAC-SHA1 | N/A | N/A | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 15 | Tunnel | NULL | NULL | 172.16.1.5 | 172.16.2.5 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 16 | Tunnel | NULL | NULL | 172.16.1.6 | 172.16.2.6 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 25 | Tunnel | AES-CBC | HMAC-SHA1 | 1111:1111: | 2222:2222: | - | | | | | 1111:1111: | 2222:2222: | - | | | | | 1111:1111: | 2222:2222: | - | | | | | 1111:5555 | 2222:5555 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 26 | Tunnel | AES-CBC | HMAC-SHA1 | 1111:1111: | 2222:2222: | - | | | | | 1111:1111: | 2222:2222: | - | | | | | 1111:1111: | 2222:2222: | - | | | | | 1111:6666 | 2222:6666 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - -.. _table_ipsec_endpoint_inbound_sa: - -.. table:: Endpoint 0 Inbound Security Associations - - +---------+----------+------------+-----------+----------------+----------------+ - | **SPI** | **Mode** | **Cipher** | **Auth** | **Tunnel src** | **Tunnel dst** | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 105 | Tunnel | AES-CBC | HMAC-SHA1 | 172.16.2.5 | 172.16.1.5 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 106 | Tunnel | AES-CBC | HMAC-SHA1 | 172.16.2.6 | 172.16.1.6 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 110 | Trans | AES-CBC | HMAC-SHA1 | N/A | N/A | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 111 | Trans | AES-CBC | HMAC-SHA1 | N/A | N/A | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 115 | Tunnel | NULL | NULL | 172.16.2.5 | 172.16.1.5 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 116 | Tunnel | NULL | NULL | 172.16.2.6 | 172.16.1.6 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 125 | Tunnel | AES-CBC | HMAC-SHA1 | 2222:2222: | 1111:1111: | - | | | | | 2222:2222: | 1111:1111: | - | | | | | 2222:2222: | 1111:1111: | - | | | | | 2222:5555 | 1111:5555 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - | 126 | Tunnel | AES-CBC | HMAC-SHA1 | 2222:2222: | 1111:1111: | - | | | | | 2222:2222: | 1111:1111: | - | | | | | 2222:2222: | 1111:1111: | - | | | | | 2222:6666 | 1111:6666 | - | | | | | | | - +---------+----------+------------+-----------+----------------+----------------+ - -For Endpoint 1, we use the same policies in reverse, meaning the Inbound SP -entries are set as Outbound and vice versa. - - -Routing Initialization -~~~~~~~~~~~~~~~~~~~~~~ - -The Routing is implemented using an LPM table. - -Following default values: - -.. _table_ipsec_endpoint_outbound_routing: - -.. table:: Endpoint 0 Routing Table - - +------------------+----------+ - | **Dst addr** | **Port** | - | | | - +------------------+----------+ - | 172.16.2.5/32 | 0 | - | | | - +------------------+----------+ - | 172.16.2.6/32 | 1 | - | | | - +------------------+----------+ - | 192.168.175.0/24 | 0 | - | | | - +------------------+----------+ - | 192.168.176.0/24 | 1 | - | | | - +------------------+----------+ - | 192.168.240.0/24 | 0 | - | | | - +------------------+----------+ - | 192.168.241.0/24 | 1 | - | | | - +------------------+----------+ - | 192.168.115.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.116.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.65.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.66.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.185.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.186.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.210.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.211.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.245.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.246.0/24 | 3 | - | | | - +------------------+----------+ - | 2222:2222: | 0 | - | 2222:2222: | | - | 2222:2222: | | - | 2222:5555/116 | | - | | | - +------------------+----------+ - | 2222:2222: | 1 | - | 2222:2222: | | - | 2222:2222: | | - | 2222:6666/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 0 | - | 1111:1111: | | - | 0000:0000: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 1 | - | 1111:1111: | | - | 1111:1111: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 2 | - | 0000:0000: | | - | aaaa:aaaa: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 3 | - | 0000:0000: | | - | bbbb:bbbb: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 2 | - | 0000:0000: | | - | 5555:5555: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 3 | - | 0000:0000: | | - | 6666:6666: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 2 | - | 1111:1111: | | - | 0000:0000: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 3 | - | 1111:1111: | | - | 1111:1111: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - -.. _table_ipsec_endpoint_inbound_routing: - -.. table:: Endpoint 1 Routing Table - - +------------------+----------+ - | **Dst addr** | **Port** | - | | | - +------------------+----------+ - | 172.16.1.5/32 | 0 | - | | | - +------------------+----------+ - | 172.16.1.6/32 | 1 | - | | | - +------------------+----------+ - | 192.168.185.0/24 | 0 | - | | | - +------------------+----------+ - | 192.168.186.0/24 | 1 | - | | | - +------------------+----------+ - | 192.168.245.0/24 | 0 | - | | | - +------------------+----------+ - | 192.168.246.0/24 | 1 | - | | | - +------------------+----------+ - | 192.168.105.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.106.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.55.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.56.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.175.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.176.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.200.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.201.0/24 | 3 | - | | | - +------------------+----------+ - | 192.168.240.0/24 | 2 | - | | | - +------------------+----------+ - | 192.168.241.0/24 | 3 | - | | | - +------------------+----------+ - | 1111:1111: | 0 | - | 1111:1111: | | - | 1111:1111: | | - | 1111:5555/116 | | - | | | - +------------------+----------+ - | 1111:1111: | 1 | - | 1111:1111: | | - | 1111:1111: | | - | 1111:6666/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 0 | - | 1111:1111: | | - | 0000:0000: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | ffff:0000: | 1 | - | 1111:1111: | | - | 1111:1111: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 2 | - | 0000:0000: | | - | aaaa:aaaa: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 3 | - | 0000:0000: | | - | bbbb:bbbb: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 2 | - | 0000:0000: | | - | 5555:5555: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 3 | - | 0000:0000: | | - | 6666:6666: | | - | 0000:0/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 2 | - | 1111:1111: | | - | 0000:0000: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ - | 0000:0000: | 3 | - | 1111:1111: | | - | 1111:1111: | | - | 0000:0000/116 | | - | | | - +------------------+----------+ + * Comment symbol **#**. Any character from this symbol to the end of + line is treated as comment and will not be parsed. + + * Line concatenation symbol **\\**. This symbol shall be placed in the end + of the line to be concatenated to the line below. Multiple lines' + concatenation is supported. + + +SP rule syntax +^^^^^^^^^^^^^^ + +The SP rule syntax is shown as follows: + +.. code-block:: console + + sp esp + + + +where each options means: + +```` + + * IP protocol version + + * Optional: No + + * Available options: + + * *ipv4*: IP protocol version 4 + * *ipv6*: IP protocol version 6 + +```` + + * The traffic direction + + * Optional: No + + * Available options: + + * *in*: inbound traffic + * *out*: outbound traffic + +```` + + * IPsec action + + * Optional: No + + * Available options: + + * *protect *: the specified traffic is protected by SA rule + with id SA_idx + * *bypass*: the specified traffic traffic is bypassed + * *discard*: the specified traffic is discarded + +```` + + * Rule priority + + * Optional: Yes, default priority 0 will be used + + * Syntax: *pri * + +```` + + * The source IP address and mask + + * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used + + * Syntax: + + * *src X.X.X.X/Y* for IPv4 + * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 + +```` + + * The destination IP address and mask + + * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used + + * Syntax: + + * *dst X.X.X.X/Y* for IPv4 + * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 + +```` + + * The protocol start and end range + + * Optional: yes, default range of 0 to 0 will be used + + * Syntax: *proto X:Y* + +```` + + * The source port start and end range + + * Optional: yes, default range of 0 to 0 will be used + + * Syntax: *sport X:Y* + +```` + + * The destination port start and end range + + * Optional: yes, default range of 0 to 0 will be used + + * Syntax: *dport X:Y* + +Example SP rules: + +.. code-block:: console + + sp ipv4 out esp protect 105 pri 1 dst 192.168.115.0/24 sport 0:65535 \ + dport 0:65535 + + sp ipv6 in esp bypass pri 1 dst 0000:0000:0000:0000:5555:5555:\ + 0000:0000/96 sport 0:65535 dport 0:65535 + + +SA rule syntax +^^^^^^^^^^^^^^ + +The successfully parsed SA rules will be stored in an array table. + +The SA rule syntax is shown as follows: + +.. code-block:: console + + sa + + + +where each options means: + +```` + + * The traffic direction + + * Optional: No + + * Available options: + + * *in*: inbound traffic + * *out*: outbound traffic + +```` + + * The SPI number + + * Optional: No + + * Syntax: unsigned integer number + +```` + + * Cipher algorithm + + * Optional: Yes, unless is not used + + * Available options: + + * *null*: NULL algorithm + * *aes-128-cbc*: AES-CBC 128-bit algorithm + * *aes-192-cbc*: AES-CBC 192-bit algorithm + * *aes-256-cbc*: AES-CBC 256-bit algorithm + * *aes-128-ctr*: AES-CTR 128-bit algorithm + * *3des-cbc*: 3DES-CBC 192-bit algorithm + + * Syntax: *cipher_algo * + +```` + + * Cipher key, NOT available when 'null' algorithm is used + + * Optional: Yes, unless is not used. + Must be followed by option + + * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. + The number of bytes should be as same as the specified cipher algorithm + key size. + + For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: + A1:B2:C3:D4* + +```` + + * Authentication algorithm + + * Optional: Yes, unless is not used + + * Available options: + + * *null*: NULL algorithm + * *sha1-hmac*: HMAC SHA1 algorithm + +```` + + * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm + is used. + + * Optional: Yes, unless is not used. + Must be followed by option + + * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. + The number of bytes should be as same as the specified authentication + algorithm key size. + + For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: + A1:B2:C3:D4* + +```` + + * AEAD algorithm + + * Optional: Yes, unless and are not used + + * Available options: + + * *aes-128-gcm*: AES-GCM 128-bit algorithm + * *aes-192-gcm*: AES-GCM 192-bit algorithm + * *aes-256-gcm*: AES-GCM 256-bit algorithm + + * Syntax: *cipher_algo * + +```` + + * Cipher key, NOT available when 'null' algorithm is used + + * Optional: Yes, unless and are not used. + Must be followed by option + + * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. + Last 4 bytes of the provided key will be used as 'salt' and so, the + number of bytes should be same as the sum of specified AEAD algorithm + key size and salt size (4 bytes). + + For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: + A1:B2:C3:D4:A1:B2:C3:D4* + +```` + + * The operation mode + + * Optional: No + + * Available options: + + * *ipv4-tunnel*: Tunnel mode for IPv4 packets + * *ipv6-tunnel*: Tunnel mode for IPv6 packets + * *transport*: transport mode + + * Syntax: mode XXX + +```` + + * The source IP address. This option is not available when + transport mode is used + + * Optional: Yes, default address 0.0.0.0 will be used + + * Syntax: + + * *src X.X.X.X* for IPv4 + * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 + +```` + + * The destination IP address. This option is not available when + transport mode is used + + * Optional: Yes, default address 0.0.0.0 will be used + + * Syntax: + + * *dst X.X.X.X* for IPv4 + * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 + +```` + + * Action type to specify the security action. This option specify + the SA to be performed with look aside protocol offload to HW + accelerator or protocol offload on ethernet device or inline + crypto processing on the ethernet device during transmission. + + * Optional: Yes, default type *no-offload* + + * Available options: + + * *lookaside-protocol-offload*: look aside protocol offload to HW accelerator + * *inline-protocol-offload*: inline protocol offload on ethernet device + * *inline-crypto-offload*: inline crypto processing on ethernet device + * *no-offload*: no offloading to hardware + + ```` + + * Port/device ID of the ethernet/crypto accelerator for which the SA is + configured. For *inline-crypto-offload* and *inline-protocol-offload*, this + port will be used for routing. The routing table will not be referred in + this case. + + * Optional: No, if *type* is not *no-offload* + + * Syntax: + + * *port_id X* X is a valid device number in decimal + + ```` + + * Action type for ingress IPsec packets that inline processor failed to + process. Only a combination of *inline-crypto-offload* as a primary + session and *lookaside-none* as a fall-back session is supported at the + moment. + + If used in conjunction with IPsec window, its width needs be increased + due to different processing times of inline and lookaside modes which + results in packet reordering. + + * Optional: Yes. + + * Available options: + + * *lookaside-none*: use automatically chosen cryptodev to process packets + + * Syntax: + + * *fallback lookaside-none* + +```` + + * Option for redirecting a specific inbound ipsec flow of a port to a specific + queue of that port. + + * Optional: Yes. + + * Available options: + + * *port_id*: Port ID of the NIC for which the SA is configured. + * *queue_id*: Queue ID to which traffic should be redirected. + +Example SA rules: + +.. code-block:: console + + sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \ + src 172.16.1.5 dst 172.16.2.5 + + sa out 25 cipher_algo aes-128-cbc \ + cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ + auth_algo sha1-hmac \ + auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ + mode ipv6-tunnel \ + src 1111:1111:1111:1111:1111:1111:1111:5555 \ + dst 2222:2222:2222:2222:2222:2222:2222:5555 + + sa in 105 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 + + sa out 5 cipher_algo aes-128-cbc cipher_key 0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0 \ + auth_algo sha1-hmac auth_key 0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0 \ + 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 + + sa in 117 cipher_algo null auth_algo null mode ipv4-tunnel src 172.16.2.7 \ + dst 172.16.1.7 flow-direction 0 2 + +Routing rule syntax +^^^^^^^^^^^^^^^^^^^ + +The Routing rule syntax is shown as follows: + +.. code-block:: console + + rt + + +where each options means: + +```` + + * IP protocol version + + * Optional: No + + * Available options: + + * *ipv4*: IP protocol version 4 + * *ipv6*: IP protocol version 6 + +```` + + * The source IP address and mask + + * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used + + * Syntax: + + * *src X.X.X.X/Y* for IPv4 + * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 + +```` + + * The destination IP address and mask + + * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used + + * Syntax: + + * *dst X.X.X.X/Y* for IPv4 + * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 + +```` + + * The traffic output port id + + * Optional: yes, default output port 0 will be used + + * Syntax: *port X* + +Example SP rules: + +.. code-block:: console + + rt ipv4 dst 172.16.1.5/32 port 0 + + rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0 + +Neighbour rule syntax +^^^^^^^^^^^^^^^^^^^^^ + +The Neighbour rule syntax is shown as follows: + +.. code-block:: console + + neigh + + +where each options means: + +```` + + * The output port id + + * Optional: No + + * Syntax: *port X* + +```` + + * The destination ethernet address to use for that port + + * Optional: No + + * Syntax: + + * XX:XX:XX:XX:XX:XX + +Example Neighbour rules: + +.. 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 ') + +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 '). If none specified + appropriate vdevs will be created by the script + +Scripts can be used for multiple test scenarios. To check all available +options run: + +.. code-block:: console + + /bin/bash run_test.sh -h + +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`` @ 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 described above. + +Usage +~~~~~ + +In the ipsec-secgw/test directory run + +/bin/bash run_test.sh + +Available options: + +* ``-4`` Perform tests with use of IPv4. One or both [-46] options needs to be + selected. + +* ``-6`` Perform tests with use of IPv6. One or both [-46] options needs to be + selected. + +* ``-m`` Add IPSec tunnel mixed IP version tests - outer IP version different + than inner. Inner IP version will match selected option [-46]. + +* ``-i`` Run tests in inline mode. Regular tests will not be invoked. + +* ``-f`` Run tests for fallback mechanism. Regular tests will not be invoked. + +* ``-l`` Run tests in legacy mode only. It cannot be used with options [-fsc]. + On default library mode is used. + +* ``-s`` Run all tests with reassembly support. On default only tests for + fallback mechanism use reassembly support. + +* ``-c`` Run tests with use of cpu-crypto. For inline tests it will not be + applied. On default lookaside-none is used. + +* ``-p`` Perform packet validation tests. Option [-46] is not required. + +* ``-h`` Show usage. + +If is specified, only tests for that mode will be invoked. For the +list of available modes please refer to run_test.sh. \ No newline at end of file