xref: /dpdk/doc/guides/sample_app_ug/ipsec_secgw.rst (revision f43d3dbbd90c9e195d26d18ac7da9ca2854c3f1e)
15630257fSFerruh Yigit..  SPDX-License-Identifier: BSD-3-Clause
25630257fSFerruh Yigit    Copyright(c) 2016-2017 Intel Corporation.
3d299106eSSergio Gonzalez Monroy
4d299106eSSergio Gonzalez MonroyIPsec Security Gateway Sample Application
5d299106eSSergio Gonzalez Monroy=========================================
6d299106eSSergio Gonzalez Monroy
7d299106eSSergio Gonzalez MonroyThe IPsec Security Gateway application is an example of a "real world"
8d299106eSSergio Gonzalez Monroyapplication using DPDK cryptodev framework.
9d299106eSSergio Gonzalez Monroy
10d299106eSSergio Gonzalez MonroyOverview
11d299106eSSergio Gonzalez Monroy--------
12d299106eSSergio Gonzalez Monroy
13d299106eSSergio Gonzalez MonroyThe application demonstrates the implementation of a Security Gateway
14913154efSSergio Gonzalez Monroy(not IPsec compliant, see the Constraints section below) using DPDK based on RFC4301,
15d299106eSSergio Gonzalez MonroyRFC4303, RFC3602 and RFC2404.
16d299106eSSergio Gonzalez Monroy
17d299106eSSergio Gonzalez MonroyInternet Key Exchange (IKE) is not implemented, so only manual setting of
18d299106eSSergio Gonzalez MonroySecurity Policies and Security Associations is supported.
19d299106eSSergio Gonzalez Monroy
20d299106eSSergio Gonzalez MonroyThe Security Policies (SP) are implemented as ACL rules, the Security
21913154efSSergio Gonzalez MonroyAssociations (SA) are stored in a table and the routing is implemented
22d299106eSSergio Gonzalez Monroyusing LPM.
23d299106eSSergio Gonzalez Monroy
24913154efSSergio Gonzalez MonroyThe application classifies the ports as *Protected* and *Unprotected*.
25913154efSSergio Gonzalez MonroyThus, traffic received on an Unprotected or Protected port is consider
26d299106eSSergio Gonzalez MonroyInbound or Outbound respectively.
27d299106eSSergio Gonzalez Monroy
28d629b7b5SJohn McNamaraThe application also supports complete IPsec protocol offload to hardware
29d629b7b5SJohn McNamara(Look aside crypto accelerator or using ethernet device). It also support
30ec17993aSAkhil Goyalinline ipsec processing by the supported ethernet device during transmission.
31ec17993aSAkhil GoyalThese modes can be selected during the SA creation configuration.
32ec17993aSAkhil Goyal
33ec17993aSAkhil GoyalIn case of complete protocol offload, the processing of headers(ESP and outer
34ec17993aSAkhil GoyalIP header) is done by the hardware and the application does not need to
35ec17993aSAkhil Goyaladd/remove them during outbound/inbound processing.
36ec17993aSAkhil Goyal
373de3a041SAnoob JosephFor inline offloaded outbound traffic, the application will not do the LPM
383de3a041SAnoob Josephlookup for routing, as the port on which the packet has to be forwarded will be
393de3a041SAnoob Josephpart of the SA. Security parameters will be configured on that port only, and
403de3a041SAnoob Josephsending the packet on other ports could result in unencrypted packets being
413de3a041SAnoob Josephsent out.
423de3a041SAnoob Joseph
43913154efSSergio Gonzalez MonroyThe Path for IPsec Inbound traffic is:
44d299106eSSergio Gonzalez Monroy
45913154efSSergio Gonzalez Monroy*  Read packets from the port.
46d299106eSSergio Gonzalez Monroy*  Classify packets between IPv4 and ESP.
47913154efSSergio Gonzalez Monroy*  Perform Inbound SA lookup for ESP packets based on their SPI.
48ec17993aSAkhil Goyal*  Perform Verification/Decryption (Not needed in case of inline ipsec).
49ec17993aSAkhil Goyal*  Remove ESP and outer IP header (Not needed in case of protocol offload).
50913154efSSergio Gonzalez Monroy*  Inbound SP check using ACL of decrypted packets and any other IPv4 packets.
51913154efSSergio Gonzalez Monroy*  Routing.
52913154efSSergio Gonzalez Monroy*  Write packet to port.
53d299106eSSergio Gonzalez Monroy
54913154efSSergio Gonzalez MonroyThe Path for the IPsec Outbound traffic is:
55d299106eSSergio Gonzalez Monroy
56913154efSSergio Gonzalez Monroy*  Read packets from the port.
57913154efSSergio Gonzalez Monroy*  Perform Outbound SP check using ACL of all IPv4 traffic.
58913154efSSergio Gonzalez Monroy*  Perform Outbound SA lookup for packets that need IPsec protection.
59ec17993aSAkhil Goyal*  Add ESP and outer IP header (Not needed in case protocol offload).
60ec17993aSAkhil Goyal*  Perform Encryption/Digest (Not needed in case of inline ipsec).
61913154efSSergio Gonzalez Monroy*  Routing.
62913154efSSergio Gonzalez Monroy*  Write packet to port.
63913154efSSergio Gonzalez Monroy
64d299106eSSergio Gonzalez Monroy
65d299106eSSergio Gonzalez MonroyConstraints
66d299106eSSergio Gonzalez Monroy-----------
67913154efSSergio Gonzalez Monroy
68913154efSSergio Gonzalez Monroy*  No IPv6 options headers.
69913154efSSergio Gonzalez Monroy*  No AH mode.
701bc489caSHemant Agrawal*  Supported algorithms: AES-CBC, AES-CTR, AES-GCM, 3DES-CBC, HMAC-SHA1 and NULL.
71913154efSSergio Gonzalez Monroy*  Each SA must be handle by a unique lcore (*1 RX queue per port*).
72913154efSSergio Gonzalez Monroy
73d299106eSSergio Gonzalez MonroyCompiling the Application
74d299106eSSergio Gonzalez Monroy-------------------------
75d299106eSSergio Gonzalez Monroy
767cacb056SHerakliusz LipiecTo compile the sample application see :doc:`compiling`.
77d299106eSSergio Gonzalez Monroy
7802dc5b7dSKonstantin AnanyevThe application is located in the ``ipsec-secgw`` sub-directory.
79d299106eSSergio Gonzalez Monroy
80913154efSSergio Gonzalez Monroy#. [Optional] Build the application for debugging:
81913154efSSergio Gonzalez Monroy   This option adds some extra flags, disables compiler optimizations and
82913154efSSergio Gonzalez Monroy   is verbose::
83913154efSSergio Gonzalez Monroy
84913154efSSergio Gonzalez Monroy       make DEBUG=1
85913154efSSergio Gonzalez Monroy
86913154efSSergio Gonzalez Monroy
87d299106eSSergio Gonzalez MonroyRunning the Application
88d299106eSSergio Gonzalez Monroy-----------------------
89d299106eSSergio Gonzalez Monroy
90913154efSSergio Gonzalez MonroyThe application has a number of command line options::
91d299106eSSergio Gonzalez Monroy
92d299106eSSergio Gonzalez Monroy
93913154efSSergio Gonzalez Monroy   ./build/ipsec-secgw [EAL options] --
94bbabfe6eSRadu Nicolau                        -p PORTMASK -P -u PORTMASK -j FRAMESIZE
9502dc5b7dSKonstantin Ananyev                        -l -w REPLAY_WINOW_SIZE -e -a
96913154efSSergio Gonzalez Monroy                        --config (port,queue,lcore)[,(port,queue,lcore]
97913154efSSergio Gonzalez Monroy                        --single-sa SAIDX
9803128be4SKonstantin Ananyev                        --rxoffload MASK
9903128be4SKonstantin Ananyev                        --txoffload MASK
100b01d1cd2SKonstantin Ananyev                        --mtu MTU
101b01d1cd2SKonstantin Ananyev                        --reassemble NUM
1020d547ed0SFan Zhang                        -f CONFIG_FILE_PATH
103d299106eSSergio Gonzalez Monroy
104913154efSSergio Gonzalez MonroyWhere:
105d299106eSSergio Gonzalez Monroy
106913154efSSergio Gonzalez Monroy*   ``-p PORTMASK``: Hexadecimal bitmask of ports to configure.
107d299106eSSergio Gonzalez Monroy
108913154efSSergio Gonzalez Monroy*   ``-P``: *optional*. Sets all ports to promiscuous mode so that packets are
109d299106eSSergio Gonzalez Monroy    accepted regardless of the packet's Ethernet MAC destination address.
110d299106eSSergio Gonzalez Monroy    Without this option, only packets with the Ethernet MAC destination address
111d299106eSSergio Gonzalez Monroy    set to the Ethernet address of the port are accepted (default is enabled).
112d299106eSSergio Gonzalez Monroy
113913154efSSergio Gonzalez Monroy*   ``-u PORTMASK``: hexadecimal bitmask of unprotected ports
114d299106eSSergio Gonzalez Monroy
115b01d1cd2SKonstantin Ananyev*   ``-j FRAMESIZE``: *optional*. data buffer size (in bytes),
116b01d1cd2SKonstantin Ananyev    in other words maximum data size for one segment.
117b01d1cd2SKonstantin Ananyev    Packets with length bigger then FRAMESIZE still can be received,
118b01d1cd2SKonstantin Ananyev    but will be segmented.
119b01d1cd2SKonstantin Ananyev    Default value: RTE_MBUF_DEFAULT_BUF_SIZE (2176)
120b01d1cd2SKonstantin Ananyev    Minimum value: RTE_MBUF_DEFAULT_BUF_SIZE (2176)
121b01d1cd2SKonstantin Ananyev    Maximum value: UINT16_MAX (65535).
122bbabfe6eSRadu Nicolau
12302dc5b7dSKonstantin Ananyev*   ``-l``: enables code-path that uses librte_ipsec.
12402dc5b7dSKonstantin Ananyev
12502dc5b7dSKonstantin Ananyev*   ``-w REPLAY_WINOW_SIZE``: specifies the IPsec sequence number replay window
12602dc5b7dSKonstantin Ananyev    size for each Security Association (available only with librte_ipsec
12702dc5b7dSKonstantin Ananyev    code path).
12802dc5b7dSKonstantin Ananyev
12902dc5b7dSKonstantin Ananyev*   ``-e``: enables Security Association extended sequence number processing
13002dc5b7dSKonstantin Ananyev    (available only with librte_ipsec code path).
13102dc5b7dSKonstantin Ananyev
132d629b7b5SJohn McNamara*   ``-a``: enables Security Association sequence number atomic behavior
13302dc5b7dSKonstantin Ananyev    (available only with librte_ipsec code path).
13402dc5b7dSKonstantin Ananyev
135913154efSSergio Gonzalez Monroy*   ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues
136913154efSSergio Gonzalez Monroy    from which ports are mapped to which cores.
137d299106eSSergio Gonzalez Monroy
138913154efSSergio Gonzalez Monroy*   ``--single-sa SAIDX``: use a single SA for outbound traffic, bypassing the SP
139d299106eSSergio Gonzalez Monroy    on both Inbound and Outbound. This option is meant for debugging/performance
140d299106eSSergio Gonzalez Monroy    purposes.
141d299106eSSergio Gonzalez Monroy
14203128be4SKonstantin Ananyev*   ``--rxoffload MASK``: RX HW offload capabilities to enable/use on this port
14303128be4SKonstantin Ananyev    (bitmask of DEV_RX_OFFLOAD_* values). It is an optional parameter and
14403128be4SKonstantin Ananyev    allows user to disable some of the RX HW offload capabilities.
14503128be4SKonstantin Ananyev    By default all HW RX offloads are enabled.
14603128be4SKonstantin Ananyev
14703128be4SKonstantin Ananyev*   ``--txoffload MASK``: TX HW offload capabilities to enable/use on this port
14803128be4SKonstantin Ananyev    (bitmask of DEV_TX_OFFLOAD_* values). It is an optional parameter and
14903128be4SKonstantin Ananyev    allows user to disable some of the TX HW offload capabilities.
15003128be4SKonstantin Ananyev    By default all HW TX offloads are enabled.
15103128be4SKonstantin Ananyev
152b01d1cd2SKonstantin Ananyev*   ``--mtu MTU``: MTU value (in bytes) on all attached ethernet ports.
153b01d1cd2SKonstantin Ananyev    Outgoing packets with length bigger then MTU will be fragmented.
154b01d1cd2SKonstantin Ananyev    Incoming packets with length bigger then MTU will be discarded.
155b01d1cd2SKonstantin Ananyev    Default value: 1500.
156b01d1cd2SKonstantin Ananyev
157bba1db35SMarcin Smoczynski*   ``--frag-ttl FRAG_TTL_NS``: fragment lifetime (in nanoseconds).
158bba1db35SMarcin Smoczynski    If packet is not reassembled within this time, received fragments
159bba1db35SMarcin Smoczynski    will be discarded. Fragment lifetime should be decreased when
160bba1db35SMarcin Smoczynski    there is a high fragmented traffic loss in high bandwidth networks.
161*f43d3dbbSDavid Marchand    Should be lower for low number of reassembly buckets.
162bba1db35SMarcin Smoczynski    Valid values: from 1 ns to 10 s. Default value: 10000000 (10 s).
163bba1db35SMarcin Smoczynski
164b01d1cd2SKonstantin Ananyev*   ``--reassemble NUM``: max number of entries in reassemble fragment table.
165b01d1cd2SKonstantin Ananyev    Zero value disables reassembly functionality.
166b01d1cd2SKonstantin Ananyev    Default value: 0.
167b01d1cd2SKonstantin Ananyev
1680d547ed0SFan Zhang*   ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all
1690d547ed0SFan Zhang    configuration items for running the application (See Configuration file
1700d547ed0SFan Zhang    syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified.
1710d547ed0SFan Zhang    **ONLY** the UNIX format configuration file is accepted.
172d299106eSSergio Gonzalez Monroy
173d299106eSSergio Gonzalez Monroy
174d299106eSSergio Gonzalez MonroyThe mapping of lcores to port/queues is similar to other l3fwd applications.
175d299106eSSergio Gonzalez Monroy
176913154efSSergio Gonzalez MonroyFor example, given the following command line::
177d299106eSSergio Gonzalez Monroy
178913154efSSergio Gonzalez Monroy    ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048       \
17930883f3eSPablo de Lara           --vdev "crypto_null" -- -p 0xf -P -u 0x3      \
1800d547ed0SFan Zhang           --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)"       \
1810d547ed0SFan Zhang           -f /path/to/config_file                              \
182d299106eSSergio Gonzalez Monroy
183d299106eSSergio Gonzalez Monroywhere each options means:
184d299106eSSergio Gonzalez Monroy
185913154efSSergio Gonzalez Monroy*   The ``-l`` option enables cores 20 and 21.
186d299106eSSergio Gonzalez Monroy
187913154efSSergio Gonzalez Monroy*   The ``-n`` option sets memory 4 channels.
188d299106eSSergio Gonzalez Monroy
189913154efSSergio Gonzalez Monroy*   The ``--socket-mem`` to use 2GB on socket 1.
190d299106eSSergio Gonzalez Monroy
19130883f3eSPablo de Lara*   The ``--vdev "crypto_null"`` option creates virtual NULL cryptodev PMD.
192d299106eSSergio Gonzalez Monroy
193913154efSSergio Gonzalez Monroy*   The ``-p`` option enables ports (detected) 0, 1, 2 and 3.
194d299106eSSergio Gonzalez Monroy
195913154efSSergio Gonzalez Monroy*   The ``-P`` option enables promiscuous mode.
196d299106eSSergio Gonzalez Monroy
197913154efSSergio Gonzalez Monroy*   The ``-u`` option sets ports 1 and 2 as unprotected, leaving 2 and 3 as protected.
198d299106eSSergio Gonzalez Monroy
199913154efSSergio Gonzalez Monroy*   The ``--config`` option enables one queue per port with the following mapping:
200d299106eSSergio Gonzalez Monroy
201d299106eSSergio Gonzalez Monroy    +----------+-----------+-----------+---------------------------------------+
202d299106eSSergio Gonzalez Monroy    | **Port** | **Queue** | **lcore** | **Description**                       |
203d299106eSSergio Gonzalez Monroy    |          |           |           |                                       |
204d299106eSSergio Gonzalez Monroy    +----------+-----------+-----------+---------------------------------------+
205d299106eSSergio Gonzalez Monroy    | 0        | 0         | 20        | Map queue 0 from port 0 to lcore 20.  |
206d299106eSSergio Gonzalez Monroy    |          |           |           |                                       |
207d299106eSSergio Gonzalez Monroy    +----------+-----------+-----------+---------------------------------------+
208d299106eSSergio Gonzalez Monroy    | 1        | 0         | 20        | Map queue 0 from port 1 to lcore 20.  |
209d299106eSSergio Gonzalez Monroy    |          |           |           |                                       |
210d299106eSSergio Gonzalez Monroy    +----------+-----------+-----------+---------------------------------------+
211d299106eSSergio Gonzalez Monroy    | 2        | 0         | 21        | Map queue 0 from port 2 to lcore 21.  |
212d299106eSSergio Gonzalez Monroy    |          |           |           |                                       |
213d299106eSSergio Gonzalez Monroy    +----------+-----------+-----------+---------------------------------------+
214d299106eSSergio Gonzalez Monroy    | 3        | 0         | 21        | Map queue 0 from port 3 to lcore 21.  |
215d299106eSSergio Gonzalez Monroy    |          |           |           |                                       |
216d299106eSSergio Gonzalez Monroy    +----------+-----------+-----------+---------------------------------------+
217d299106eSSergio Gonzalez Monroy
2180d547ed0SFan Zhang*   The ``-f /path/to/config_file`` option enables the application read and
2190d547ed0SFan Zhang    parse the configuration file specified, and configures the application
2200d547ed0SFan Zhang    with a given set of SP, SA and Routing entries accordingly. The syntax of
2210d547ed0SFan Zhang    the configuration file will be explained below in more detail. Please
2220d547ed0SFan Zhang    **note** the parser only accepts UNIX format text file. Other formats
2230d547ed0SFan Zhang    such as DOS/MAC format will cause a parse error.
224d299106eSSergio Gonzalez Monroy
225d299106eSSergio Gonzalez MonroyRefer to the *DPDK Getting Started Guide* for general information on running
226d299106eSSergio Gonzalez Monroyapplications and the Environment Abstraction Layer (EAL) options.
227d299106eSSergio Gonzalez Monroy
228d299106eSSergio Gonzalez MonroyThe application would do a best effort to "map" crypto devices to cores, with
229913154efSSergio Gonzalez Monroyhardware devices having priority. Basically, hardware devices if present would
230913154efSSergio Gonzalez Monroybe assigned to a core before software ones.
231d299106eSSergio Gonzalez MonroyThis means that if the application is using a single core and both hardware
232d299106eSSergio Gonzalez Monroyand software crypto devices are detected, hardware devices will be used.
233d299106eSSergio Gonzalez Monroy
2348d257235SJohn McNamaraA way to achieve the case where you want to force the use of virtual crypto
2358d257235SJohn McNamaradevices is to whitelist the Ethernet devices needed and therefore implicitly
236d299106eSSergio Gonzalez Monroyblacklisting all hardware crypto devices.
237d299106eSSergio Gonzalez Monroy
238d299106eSSergio Gonzalez MonroyFor example, something like the following command line:
239d299106eSSergio Gonzalez Monroy
240d299106eSSergio Gonzalez Monroy.. code-block:: console
241d299106eSSergio Gonzalez Monroy
242913154efSSergio Gonzalez Monroy    ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \
243913154efSSergio Gonzalez Monroy            -w 81:00.0 -w 81:00.1 -w 81:00.2 -w 81:00.3 \
24430883f3eSPablo de Lara            --vdev "crypto_aesni_mb" --vdev "crypto_null" \
245913154efSSergio Gonzalez Monroy	    -- \
246913154efSSergio Gonzalez Monroy            -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \
2470d547ed0SFan Zhang            -f sample.cfg
248d299106eSSergio Gonzalez Monroy
249913154efSSergio Gonzalez Monroy
250d299106eSSergio Gonzalez MonroyConfigurations
251d299106eSSergio Gonzalez Monroy--------------
252d299106eSSergio Gonzalez Monroy
2530d547ed0SFan ZhangThe following sections provide the syntax of configurations to initialize
2547622291bSKonstantin Ananyevyour SP, SA, Routing and Neighbour tables.
2550d547ed0SFan ZhangConfigurations shall be specified in the configuration file to be passed to
2560d547ed0SFan Zhangthe application. The file is then parsed by the application. The successful
2570d547ed0SFan Zhangparsing will result in the appropriate rules being applied to the tables
2580d547ed0SFan Zhangaccordingly.
259913154efSSergio Gonzalez Monroy
260d299106eSSergio Gonzalez Monroy
2610d547ed0SFan ZhangConfiguration File Syntax
26202dc5b7dSKonstantin Ananyev~~~~~~~~~~~~~~~~~~~~~~~~~
263d299106eSSergio Gonzalez Monroy
264d299106eSSergio Gonzalez MonroyAs mention in the overview, the Security Policies are ACL rules.
2650d547ed0SFan ZhangThe application parsers the rules specified in the configuration file and
2660d547ed0SFan Zhangpasses them to the ACL table, and replicates them per socket in use.
267d299106eSSergio Gonzalez Monroy
2680d547ed0SFan ZhangFollowing are the configuration file syntax.
269d299106eSSergio Gonzalez Monroy
2700d547ed0SFan ZhangGeneral rule syntax
2710d547ed0SFan Zhang^^^^^^^^^^^^^^^^^^^
272d299106eSSergio Gonzalez Monroy
2730d547ed0SFan ZhangThe parse treats one line in the configuration file as one configuration
2740d547ed0SFan Zhangitem (unless the line concatenation symbol exists). Every configuration
2757622291bSKonstantin Ananyevitem shall follow the syntax of either SP, SA, Routing or Neighbour
2767622291bSKonstantin Ananyevrules specified below.
277d299106eSSergio Gonzalez Monroy
2780d547ed0SFan ZhangThe configuration parser supports the following special symbols:
279d299106eSSergio Gonzalez Monroy
2800d547ed0SFan Zhang * Comment symbol **#**. Any character from this symbol to the end of
2810d547ed0SFan Zhang   line is treated as comment and will not be parsed.
282d299106eSSergio Gonzalez Monroy
2830d547ed0SFan Zhang * Line concatenation symbol **\\**. This symbol shall be placed in the end
2840d547ed0SFan Zhang   of the line to be concatenated to the line below. Multiple lines'
2850d547ed0SFan Zhang   concatenation is supported.
286d299106eSSergio Gonzalez Monroy
287d299106eSSergio Gonzalez Monroy
2880d547ed0SFan ZhangSP rule syntax
2890d547ed0SFan Zhang^^^^^^^^^^^^^^
290d299106eSSergio Gonzalez Monroy
2910d547ed0SFan ZhangThe SP rule syntax is shown as follows:
292d299106eSSergio Gonzalez Monroy
2930d547ed0SFan Zhang.. code-block:: console
294d299106eSSergio Gonzalez Monroy
2950d547ed0SFan Zhang    sp <ip_ver> <dir> esp <action> <priority> <src_ip> <dst_ip>
2960d547ed0SFan Zhang    <proto> <sport> <dport>
297d299106eSSergio Gonzalez Monroy
298d299106eSSergio Gonzalez Monroy
2990d547ed0SFan Zhangwhere each options means:
300d299106eSSergio Gonzalez Monroy
3010d547ed0SFan Zhang``<ip_ver>``
302d299106eSSergio Gonzalez Monroy
3030d547ed0SFan Zhang * IP protocol version
304d299106eSSergio Gonzalez Monroy
3050d547ed0SFan Zhang * Optional: No
306913154efSSergio Gonzalez Monroy
3070d547ed0SFan Zhang * Available options:
308d299106eSSergio Gonzalez Monroy
3090d547ed0SFan Zhang   * *ipv4*: IP protocol version 4
3100d547ed0SFan Zhang   * *ipv6*: IP protocol version 6
311d299106eSSergio Gonzalez Monroy
3120d547ed0SFan Zhang``<dir>``
313913154efSSergio Gonzalez Monroy
3140d547ed0SFan Zhang * The traffic direction
315d299106eSSergio Gonzalez Monroy
3160d547ed0SFan Zhang * Optional: No
3170d547ed0SFan Zhang
3180d547ed0SFan Zhang * Available options:
3190d547ed0SFan Zhang
3200d547ed0SFan Zhang   * *in*: inbound traffic
3210d547ed0SFan Zhang   * *out*: outbound traffic
3220d547ed0SFan Zhang
3230d547ed0SFan Zhang``<action>``
3240d547ed0SFan Zhang
3250d547ed0SFan Zhang * IPsec action
3260d547ed0SFan Zhang
3270d547ed0SFan Zhang * Optional: No
3280d547ed0SFan Zhang
3290d547ed0SFan Zhang * Available options:
3300d547ed0SFan Zhang
3310d547ed0SFan Zhang   * *protect <SA_idx>*: the specified traffic is protected by SA rule
3320d547ed0SFan Zhang     with id SA_idx
3330d547ed0SFan Zhang   * *bypass*: the specified traffic traffic is bypassed
3340d547ed0SFan Zhang   * *discard*: the specified traffic is discarded
3350d547ed0SFan Zhang
3360d547ed0SFan Zhang``<priority>``
3370d547ed0SFan Zhang
3380d547ed0SFan Zhang * Rule priority
3390d547ed0SFan Zhang
3400d547ed0SFan Zhang * Optional: Yes, default priority 0 will be used
3410d547ed0SFan Zhang
3420d547ed0SFan Zhang * Syntax: *pri <id>*
3430d547ed0SFan Zhang
3440d547ed0SFan Zhang``<src_ip>``
3450d547ed0SFan Zhang
3460d547ed0SFan Zhang * The source IP address and mask
3470d547ed0SFan Zhang
3480d547ed0SFan Zhang * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
3490d547ed0SFan Zhang
3500d547ed0SFan Zhang * Syntax:
3510d547ed0SFan Zhang
3520d547ed0SFan Zhang   * *src X.X.X.X/Y* for IPv4
3530d547ed0SFan Zhang   * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
3540d547ed0SFan Zhang
3550d547ed0SFan Zhang``<dst_ip>``
3560d547ed0SFan Zhang
3570d547ed0SFan Zhang * The destination IP address and mask
3580d547ed0SFan Zhang
3590d547ed0SFan Zhang * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
3600d547ed0SFan Zhang
3610d547ed0SFan Zhang * Syntax:
3620d547ed0SFan Zhang
3630d547ed0SFan Zhang   * *dst X.X.X.X/Y* for IPv4
3640d547ed0SFan Zhang   * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
3650d547ed0SFan Zhang
3660d547ed0SFan Zhang``<proto>``
3670d547ed0SFan Zhang
3680d547ed0SFan Zhang * The protocol start and end range
3690d547ed0SFan Zhang
3700d547ed0SFan Zhang * Optional: yes, default range of 0 to 0 will be used
3710d547ed0SFan Zhang
3720d547ed0SFan Zhang * Syntax: *proto X:Y*
3730d547ed0SFan Zhang
3740d547ed0SFan Zhang``<sport>``
3750d547ed0SFan Zhang
3760d547ed0SFan Zhang * The source port start and end range
3770d547ed0SFan Zhang
3780d547ed0SFan Zhang * Optional: yes, default range of 0 to 0 will be used
3790d547ed0SFan Zhang
3800d547ed0SFan Zhang * Syntax: *sport X:Y*
3810d547ed0SFan Zhang
3820d547ed0SFan Zhang``<dport>``
3830d547ed0SFan Zhang
3840d547ed0SFan Zhang * The destination port start and end range
3850d547ed0SFan Zhang
3860d547ed0SFan Zhang * Optional: yes, default range of 0 to 0 will be used
3870d547ed0SFan Zhang
3880d547ed0SFan Zhang * Syntax: *dport X:Y*
3890d547ed0SFan Zhang
3900d547ed0SFan ZhangExample SP rules:
3910d547ed0SFan Zhang
3920d547ed0SFan Zhang.. code-block:: console
3930d547ed0SFan Zhang
3940d547ed0SFan Zhang    sp ipv4 out esp protect 105 pri 1 dst 192.168.115.0/24 sport 0:65535 \
3950d547ed0SFan Zhang    dport 0:65535
3960d547ed0SFan Zhang
3970d547ed0SFan Zhang    sp ipv6 in esp bypass pri 1 dst 0000:0000:0000:0000:5555:5555:\
3980d547ed0SFan Zhang    0000:0000/96 sport 0:65535 dport 0:65535
3990d547ed0SFan Zhang
4000d547ed0SFan Zhang
4010d547ed0SFan ZhangSA rule syntax
4020d547ed0SFan Zhang^^^^^^^^^^^^^^
4030d547ed0SFan Zhang
4040d547ed0SFan ZhangThe successfully parsed SA rules will be stored in an array table.
4050d547ed0SFan Zhang
4060d547ed0SFan ZhangThe SA rule syntax is shown as follows:
4070d547ed0SFan Zhang
4080d547ed0SFan Zhang.. code-block:: console
4090d547ed0SFan Zhang
4100d547ed0SFan Zhang    sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key>
411ba66534fSMarcin Smoczynski    <mode> <src_ip> <dst_ip> <action_type> <port_id> <fallback>
4120d547ed0SFan Zhang
4130d547ed0SFan Zhangwhere each options means:
4140d547ed0SFan Zhang
4150d547ed0SFan Zhang``<dir>``
4160d547ed0SFan Zhang
4170d547ed0SFan Zhang * The traffic direction
4180d547ed0SFan Zhang
4190d547ed0SFan Zhang * Optional: No
4200d547ed0SFan Zhang
4210d547ed0SFan Zhang * Available options:
4220d547ed0SFan Zhang
4230d547ed0SFan Zhang   * *in*: inbound traffic
4240d547ed0SFan Zhang   * *out*: outbound traffic
4250d547ed0SFan Zhang
4260d547ed0SFan Zhang``<spi>``
4270d547ed0SFan Zhang
4280d547ed0SFan Zhang * The SPI number
4290d547ed0SFan Zhang
4300d547ed0SFan Zhang * Optional: No
4310d547ed0SFan Zhang
4320d547ed0SFan Zhang * Syntax: unsigned integer number
4330d547ed0SFan Zhang
4340d547ed0SFan Zhang``<cipher_algo>``
4350d547ed0SFan Zhang
4360d547ed0SFan Zhang * Cipher algorithm
4370d547ed0SFan Zhang
438501e9c22SPablo de Lara * Optional: Yes, unless <aead_algo> is not used
4390d547ed0SFan Zhang
4400d547ed0SFan Zhang * Available options:
4410d547ed0SFan Zhang
4420d547ed0SFan Zhang   * *null*: NULL algorithm
4430d547ed0SFan Zhang   * *aes-128-cbc*: AES-CBC 128-bit algorithm
444fa908884SAnoob Joseph   * *aes-256-cbc*: AES-CBC 256-bit algorithm
4454470c22dSSergio Gonzalez Monroy   * *aes-128-ctr*: AES-CTR 128-bit algorithm
4461bc489caSHemant Agrawal   * *3des-cbc*: 3DES-CBC 192-bit algorithm
4470d547ed0SFan Zhang
4480d547ed0SFan Zhang * Syntax: *cipher_algo <your algorithm>*
4490d547ed0SFan Zhang
4500d547ed0SFan Zhang``<cipher_key>``
4510d547ed0SFan Zhang
4520d547ed0SFan Zhang * Cipher key, NOT available when 'null' algorithm is used
4530d547ed0SFan Zhang
454501e9c22SPablo de Lara * Optional: Yes, unless <aead_algo> is not used.
455501e9c22SPablo de Lara   Must be followed by <cipher_algo> option
4560d547ed0SFan Zhang
4570d547ed0SFan Zhang * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
4580d547ed0SFan Zhang   The number of bytes should be as same as the specified cipher algorithm
4590d547ed0SFan Zhang   key size.
4600d547ed0SFan Zhang
4610d547ed0SFan Zhang   For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
4620d547ed0SFan Zhang   A1:B2:C3:D4*
4630d547ed0SFan Zhang
4640d547ed0SFan Zhang``<auth_algo>``
4650d547ed0SFan Zhang
4660d547ed0SFan Zhang * Authentication algorithm
4670d547ed0SFan Zhang
468501e9c22SPablo de Lara * Optional: Yes, unless <aead_algo> is not used
4690d547ed0SFan Zhang
4700d547ed0SFan Zhang * Available options:
4710d547ed0SFan Zhang
4720d547ed0SFan Zhang    * *null*: NULL algorithm
4730d547ed0SFan Zhang    * *sha1-hmac*: HMAC SHA1 algorithm
4740d547ed0SFan Zhang
4750d547ed0SFan Zhang``<auth_key>``
4760d547ed0SFan Zhang
477a9121c40SSergio Gonzalez Monroy * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm
478a9121c40SSergio Gonzalez Monroy   is used.
4790d547ed0SFan Zhang
480501e9c22SPablo de Lara * Optional: Yes, unless <aead_algo> is not used.
481501e9c22SPablo de Lara   Must be followed by <auth_algo> option
4820d547ed0SFan Zhang
4830d547ed0SFan Zhang * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
4840d547ed0SFan Zhang   The number of bytes should be as same as the specified authentication
4850d547ed0SFan Zhang   algorithm key size.
4860d547ed0SFan Zhang
4870d547ed0SFan Zhang   For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
4880d547ed0SFan Zhang   A1:B2:C3:D4*
4890d547ed0SFan Zhang
490501e9c22SPablo de Lara``<aead_algo>``
491501e9c22SPablo de Lara
492501e9c22SPablo de Lara * AEAD algorithm
493501e9c22SPablo de Lara
494501e9c22SPablo de Lara * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used
495501e9c22SPablo de Lara
496b79e4c00SPablo de Lara * Available options:
497b79e4c00SPablo de Lara
498b79e4c00SPablo de Lara   * *aes-128-gcm*: AES-GCM 128-bit algorithm
499b79e4c00SPablo de Lara
500501e9c22SPablo de Lara * Syntax: *cipher_algo <your algorithm>*
501501e9c22SPablo de Lara
502501e9c22SPablo de Lara``<aead_key>``
503501e9c22SPablo de Lara
504501e9c22SPablo de Lara * Cipher key, NOT available when 'null' algorithm is used
505501e9c22SPablo de Lara
506501e9c22SPablo de Lara * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used.
507501e9c22SPablo de Lara   Must be followed by <aead_algo> option
508501e9c22SPablo de Lara
509501e9c22SPablo de Lara * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
510501e9c22SPablo de Lara   The number of bytes should be as same as the specified AEAD algorithm
511501e9c22SPablo de Lara   key size.
512501e9c22SPablo de Lara
513501e9c22SPablo de Lara   For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
514501e9c22SPablo de Lara   A1:B2:C3:D4*
515501e9c22SPablo de Lara
5160d547ed0SFan Zhang``<mode>``
5170d547ed0SFan Zhang
5180d547ed0SFan Zhang * The operation mode
5190d547ed0SFan Zhang
5200d547ed0SFan Zhang * Optional: No
5210d547ed0SFan Zhang
5220d547ed0SFan Zhang * Available options:
5230d547ed0SFan Zhang
5240d547ed0SFan Zhang   * *ipv4-tunnel*: Tunnel mode for IPv4 packets
5250d547ed0SFan Zhang   * *ipv6-tunnel*: Tunnel mode for IPv6 packets
5260d547ed0SFan Zhang   * *transport*: transport mode
5270d547ed0SFan Zhang
5280d547ed0SFan Zhang * Syntax: mode XXX
5290d547ed0SFan Zhang
5300d547ed0SFan Zhang``<src_ip>``
5310d547ed0SFan Zhang
5320d547ed0SFan Zhang * The source IP address. This option is not available when
5330d547ed0SFan Zhang   transport mode is used
5340d547ed0SFan Zhang
5350d547ed0SFan Zhang * Optional: Yes, default address 0.0.0.0 will be used
5360d547ed0SFan Zhang
5370d547ed0SFan Zhang * Syntax:
5380d547ed0SFan Zhang
5390d547ed0SFan Zhang   * *src X.X.X.X* for IPv4
5400d547ed0SFan Zhang   * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
5410d547ed0SFan Zhang
5420d547ed0SFan Zhang``<dst_ip>``
5430d547ed0SFan Zhang
5440d547ed0SFan Zhang * The destination IP address. This option is not available when
5450d547ed0SFan Zhang   transport mode is used
5460d547ed0SFan Zhang
5470d547ed0SFan Zhang * Optional: Yes, default address 0.0.0.0 will be used
5480d547ed0SFan Zhang
5490d547ed0SFan Zhang * Syntax:
5500d547ed0SFan Zhang
5510d547ed0SFan Zhang   * *dst X.X.X.X* for IPv4
5520d547ed0SFan Zhang   * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
5530d547ed0SFan Zhang
554ec17993aSAkhil Goyal``<type>``
555ec17993aSAkhil Goyal
556ec17993aSAkhil Goyal * Action type to specify the security action. This option specify
557ec17993aSAkhil Goyal   the SA to be performed with look aside protocol offload to HW
558ec17993aSAkhil Goyal   accelerator or protocol offload on ethernet device or inline
559ec17993aSAkhil Goyal   crypto processing on the ethernet device during transmission.
560ec17993aSAkhil Goyal
561ec17993aSAkhil Goyal * Optional: Yes, default type *no-offload*
562ec17993aSAkhil Goyal
563ec17993aSAkhil Goyal * Available options:
564ec17993aSAkhil Goyal
565ec17993aSAkhil Goyal   * *lookaside-protocol-offload*: look aside protocol offload to HW accelerator
566ec17993aSAkhil Goyal   * *inline-protocol-offload*: inline protocol offload on ethernet device
567ec17993aSAkhil Goyal   * *inline-crypto-offload*: inline crypto processing on ethernet device
568ec17993aSAkhil Goyal   * *no-offload*: no offloading to hardware
569ec17993aSAkhil Goyal
570ec17993aSAkhil Goyal ``<port_id>``
571ec17993aSAkhil Goyal
572ec17993aSAkhil Goyal * Port/device ID of the ethernet/crypto accelerator for which the SA is
5733de3a041SAnoob Joseph   configured. For *inline-crypto-offload* and *inline-protocol-offload*, this
5743de3a041SAnoob Joseph   port will be used for routing. The routing table will not be referred in
5753de3a041SAnoob Joseph   this case.
576ec17993aSAkhil Goyal
577ec17993aSAkhil Goyal * Optional: No, if *type* is not *no-offload*
578ec17993aSAkhil Goyal
579ec17993aSAkhil Goyal * Syntax:
580ec17993aSAkhil Goyal
581ec17993aSAkhil Goyal   * *port_id X* X is a valid device number in decimal
582ec17993aSAkhil Goyal
583ba66534fSMarcin Smoczynski ``<fallback>``
584ba66534fSMarcin Smoczynski
585ba66534fSMarcin Smoczynski * Action type for ingress IPsec packets that inline processor failed to
586ba66534fSMarcin Smoczynski   process. Only a combination of *inline-crypto-offload* as a primary
587ba66534fSMarcin Smoczynski   session and *lookaside-none* as a fall-back session is supported at the
588ba66534fSMarcin Smoczynski   moment.
589ba66534fSMarcin Smoczynski
590ba66534fSMarcin Smoczynski   If used in conjunction with IPsec window, its width needs be increased
591ba66534fSMarcin Smoczynski   due to different processing times of inline and lookaside modes which
592ba66534fSMarcin Smoczynski   results in packet reordering.
593ba66534fSMarcin Smoczynski
594ba66534fSMarcin Smoczynski * Optional: Yes.
595ba66534fSMarcin Smoczynski
596ba66534fSMarcin Smoczynski * Available options:
597ba66534fSMarcin Smoczynski
598ba66534fSMarcin Smoczynski   * *lookaside-none*: use automatically chosen cryptodev to process packets
599ba66534fSMarcin Smoczynski
600ba66534fSMarcin Smoczynski * Syntax:
601ba66534fSMarcin Smoczynski
602ba66534fSMarcin Smoczynski   * *fallback lookaside-none*
603ec17993aSAkhil Goyal
6040d547ed0SFan ZhangExample SA rules:
6050d547ed0SFan Zhang
6060d547ed0SFan Zhang.. code-block:: console
6070d547ed0SFan Zhang
6080d547ed0SFan Zhang    sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \
6090d547ed0SFan Zhang    src 172.16.1.5 dst 172.16.2.5
6100d547ed0SFan Zhang
6110d547ed0SFan Zhang    sa out 25 cipher_algo aes-128-cbc \
6120d547ed0SFan Zhang    cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
6130d547ed0SFan Zhang    auth_algo sha1-hmac \
6140d547ed0SFan Zhang    auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
6150d547ed0SFan Zhang    mode ipv6-tunnel \
6160d547ed0SFan Zhang    src 1111:1111:1111:1111:1111:1111:1111:5555 \
6170d547ed0SFan Zhang    dst 2222:2222:2222:2222:2222:2222:2222:5555
6180d547ed0SFan Zhang
619b79e4c00SPablo de Lara    sa in 105 aead_algo aes-128-gcm \
620b79e4c00SPablo de Lara    aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
621a9121c40SSergio Gonzalez Monroy    mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5
6220d547ed0SFan Zhang
623ec17993aSAkhil Goyal    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 \
624ec17993aSAkhil Goyal    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 \
625ec17993aSAkhil Goyal    mode ipv4-tunnel src 172.16.1.5 dst 172.16.2.5 \
626ec17993aSAkhil Goyal    type lookaside-protocol-offload port_id 4
627ec17993aSAkhil Goyal
62802dc5b7dSKonstantin Ananyev    sa in 35 aead_algo aes-128-gcm \
62902dc5b7dSKonstantin Ananyev    aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
63002dc5b7dSKonstantin Ananyev    mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 \
63102dc5b7dSKonstantin Ananyev    type inline-crypto-offload port_id 0
63202dc5b7dSKonstantin Ananyev
6330d547ed0SFan ZhangRouting rule syntax
6340d547ed0SFan Zhang^^^^^^^^^^^^^^^^^^^
6350d547ed0SFan Zhang
6360d547ed0SFan ZhangThe Routing rule syntax is shown as follows:
6370d547ed0SFan Zhang
6380d547ed0SFan Zhang.. code-block:: console
6390d547ed0SFan Zhang
6400d547ed0SFan Zhang    rt <ip_ver> <src_ip> <dst_ip> <port>
6410d547ed0SFan Zhang
6420d547ed0SFan Zhang
6430d547ed0SFan Zhangwhere each options means:
6440d547ed0SFan Zhang
6450d547ed0SFan Zhang``<ip_ver>``
6460d547ed0SFan Zhang
6470d547ed0SFan Zhang * IP protocol version
6480d547ed0SFan Zhang
6490d547ed0SFan Zhang * Optional: No
6500d547ed0SFan Zhang
6510d547ed0SFan Zhang * Available options:
6520d547ed0SFan Zhang
6530d547ed0SFan Zhang   * *ipv4*: IP protocol version 4
6540d547ed0SFan Zhang   * *ipv6*: IP protocol version 6
6550d547ed0SFan Zhang
6560d547ed0SFan Zhang``<src_ip>``
6570d547ed0SFan Zhang
6580d547ed0SFan Zhang * The source IP address and mask
6590d547ed0SFan Zhang
6600d547ed0SFan Zhang * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
6610d547ed0SFan Zhang
6620d547ed0SFan Zhang * Syntax:
6630d547ed0SFan Zhang
6640d547ed0SFan Zhang   * *src X.X.X.X/Y* for IPv4
6650d547ed0SFan Zhang   * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
6660d547ed0SFan Zhang
6670d547ed0SFan Zhang``<dst_ip>``
6680d547ed0SFan Zhang
6690d547ed0SFan Zhang * The destination IP address and mask
6700d547ed0SFan Zhang
6710d547ed0SFan Zhang * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
6720d547ed0SFan Zhang
6730d547ed0SFan Zhang * Syntax:
6740d547ed0SFan Zhang
6750d547ed0SFan Zhang   * *dst X.X.X.X/Y* for IPv4
6760d547ed0SFan Zhang   * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
6770d547ed0SFan Zhang
6780d547ed0SFan Zhang``<port>``
6790d547ed0SFan Zhang
6800d547ed0SFan Zhang * The traffic output port id
6810d547ed0SFan Zhang
6820d547ed0SFan Zhang * Optional: yes, default output port 0 will be used
6830d547ed0SFan Zhang
6840d547ed0SFan Zhang * Syntax: *port X*
6850d547ed0SFan Zhang
6860d547ed0SFan ZhangExample SP rules:
6870d547ed0SFan Zhang
6880d547ed0SFan Zhang.. code-block:: console
6890d547ed0SFan Zhang
6900d547ed0SFan Zhang    rt ipv4 dst 172.16.1.5/32 port 0
6910d547ed0SFan Zhang
6920d547ed0SFan Zhang    rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0
6937622291bSKonstantin Ananyev
6947622291bSKonstantin AnanyevNeighbour rule syntax
6957622291bSKonstantin Ananyev^^^^^^^^^^^^^^^^^^^^^
6967622291bSKonstantin Ananyev
6977622291bSKonstantin AnanyevThe Neighbour rule syntax is shown as follows:
6987622291bSKonstantin Ananyev
6997622291bSKonstantin Ananyev.. code-block:: console
7007622291bSKonstantin Ananyev
7017622291bSKonstantin Ananyev    neigh <port> <dst_mac>
7027622291bSKonstantin Ananyev
7037622291bSKonstantin Ananyev
7047622291bSKonstantin Ananyevwhere each options means:
7057622291bSKonstantin Ananyev
7067622291bSKonstantin Ananyev``<port>``
7077622291bSKonstantin Ananyev
7087622291bSKonstantin Ananyev * The output port id
7097622291bSKonstantin Ananyev
7107622291bSKonstantin Ananyev * Optional: No
7117622291bSKonstantin Ananyev
7127622291bSKonstantin Ananyev * Syntax: *port X*
7137622291bSKonstantin Ananyev
7147622291bSKonstantin Ananyev``<dst_mac>``
7157622291bSKonstantin Ananyev
7167622291bSKonstantin Ananyev * The destination ethernet address to use for that port
7177622291bSKonstantin Ananyev
7187622291bSKonstantin Ananyev * Optional: No
7197622291bSKonstantin Ananyev
7207622291bSKonstantin Ananyev * Syntax:
7217622291bSKonstantin Ananyev
7227622291bSKonstantin Ananyev   * XX:XX:XX:XX:XX:XX
7237622291bSKonstantin Ananyev
7247622291bSKonstantin AnanyevExample Neighbour rules:
7257622291bSKonstantin Ananyev
7267622291bSKonstantin Ananyev.. code-block:: console
7277622291bSKonstantin Ananyev
7287622291bSKonstantin Ananyev    neigh port 0 DE:AD:BE:EF:01:02
72902dc5b7dSKonstantin Ananyev
73002dc5b7dSKonstantin AnanyevTest directory
73102dc5b7dSKonstantin Ananyev--------------
73202dc5b7dSKonstantin Ananyev
73302dc5b7dSKonstantin AnanyevThe test directory contains scripts for testing the various encryption
73402dc5b7dSKonstantin Ananyevalgorithms.
73502dc5b7dSKonstantin Ananyev
73602dc5b7dSKonstantin AnanyevThe purpose of the scripts is to automate ipsec-secgw testing
73702dc5b7dSKonstantin Ananyevusing another system running linux as a DUT.
73802dc5b7dSKonstantin Ananyev
73902dc5b7dSKonstantin AnanyevThe user must setup the following environment variables:
74002dc5b7dSKonstantin Ananyev
74102dc5b7dSKonstantin Ananyev*   ``SGW_PATH``: path to the ipsec-secgw binary to test.
74202dc5b7dSKonstantin Ananyev
74302dc5b7dSKonstantin Ananyev*   ``REMOTE_HOST``: IP address/hostname of the DUT.
74402dc5b7dSKonstantin Ananyev
74502dc5b7dSKonstantin Ananyev*   ``REMOTE_IFACE``: interface name for the test-port on the DUT.
74602dc5b7dSKonstantin Ananyev
74702dc5b7dSKonstantin Ananyev*   ``ETH_DEV``: ethernet device to be used on the SUT by DPDK ('-w <pci-id>')
74802dc5b7dSKonstantin Ananyev
74902dc5b7dSKonstantin AnanyevAlso the user can optionally setup:
75002dc5b7dSKonstantin Ananyev
75102dc5b7dSKonstantin Ananyev*   ``SGW_LCORE``: lcore to run ipsec-secgw on (default value is 0)
75202dc5b7dSKonstantin Ananyev
75302dc5b7dSKonstantin Ananyev*   ``CRYPTO_DEV``: crypto device to be used ('-w <pci-id>'). If none specified
75402dc5b7dSKonstantin Ananyev    appropriate vdevs will be created by the script
75502dc5b7dSKonstantin Ananyev
756403e9d91SMarcin Smoczynski*   ``MULTI_SEG_TEST``: ipsec-secgw option to enable reassembly support and
757403e9d91SMarcin Smoczynski    specify size of reassembly table (e.g.
758403e9d91SMarcin Smoczynski    ``MULTI_SEG_TEST='--reassemble 128'``). This option must be set for
759403e9d91SMarcin Smoczynski    fallback session tests.
760403e9d91SMarcin Smoczynski
76102dc5b7dSKonstantin AnanyevNote that most of the tests require the appropriate crypto PMD/device to be
76202dc5b7dSKonstantin Ananyevavailable.
76302dc5b7dSKonstantin Ananyev
76402dc5b7dSKonstantin AnanyevServer configuration
76502dc5b7dSKonstantin Ananyev~~~~~~~~~~~~~~~~~~~~
76602dc5b7dSKonstantin Ananyev
76702dc5b7dSKonstantin AnanyevTwo servers are required for the tests, SUT and DUT.
76802dc5b7dSKonstantin Ananyev
76902dc5b7dSKonstantin AnanyevMake sure the user from the SUT can ssh to the DUT without entering the password.
77002dc5b7dSKonstantin AnanyevTo enable this feature keys must be setup on the DUT.
77102dc5b7dSKonstantin Ananyev
77202dc5b7dSKonstantin Ananyev``ssh-keygen`` will make a private & public key pair on the SUT.
77302dc5b7dSKonstantin Ananyev
77402dc5b7dSKonstantin Ananyev``ssh-copy-id`` <user name>@<target host name> on the SUT will copy the public
77502dc5b7dSKonstantin Ananyevkey to the DUT. It will ask for credentials so that it can upload the public key.
77602dc5b7dSKonstantin Ananyev
77702dc5b7dSKonstantin AnanyevThe SUT and DUT are connected through at least 2 NIC ports.
77802dc5b7dSKonstantin Ananyev
77902dc5b7dSKonstantin AnanyevOne NIC port is expected to be managed by linux on both machines and will be
78002dc5b7dSKonstantin Ananyevused as a control path.
78102dc5b7dSKonstantin Ananyev
78202dc5b7dSKonstantin AnanyevThe second NIC port (test-port) should be bound to DPDK on the SUT, and should
78302dc5b7dSKonstantin Ananyevbe managed by linux on the DUT.
78402dc5b7dSKonstantin Ananyev
78502dc5b7dSKonstantin AnanyevThe script starts ``ipsec-secgw`` with 2 NIC devices: ``test-port`` and
78602dc5b7dSKonstantin Ananyev``tap vdev``.
78702dc5b7dSKonstantin Ananyev
78802dc5b7dSKonstantin AnanyevIt then configures the local tap interface and the remote interface and IPsec
78902dc5b7dSKonstantin Ananyevpolicies in the following way:
79002dc5b7dSKonstantin Ananyev
79102dc5b7dSKonstantin AnanyevTraffic going over the test-port in both directions has to be protected by IPsec.
79202dc5b7dSKonstantin Ananyev
79302dc5b7dSKonstantin AnanyevTraffic going over the TAP port in both directions does not have to be protected.
79402dc5b7dSKonstantin Ananyev
79502dc5b7dSKonstantin Ananyevi.e:
79602dc5b7dSKonstantin Ananyev
79702dc5b7dSKonstantin AnanyevDUT OS(NIC1)--(IPsec)-->(NIC1)ipsec-secgw(TAP)--(plain)-->(TAP)SUT OS
79802dc5b7dSKonstantin Ananyev
79902dc5b7dSKonstantin AnanyevSUT OS(TAP)--(plain)-->(TAP)psec-secgw(NIC1)--(IPsec)-->(NIC1)DUT OS
80002dc5b7dSKonstantin Ananyev
801d629b7b5SJohn McNamaraIt then tries to perform some data transfer using the scheme described above.
80202dc5b7dSKonstantin Ananyev
80302dc5b7dSKonstantin Ananyevusage
80402dc5b7dSKonstantin Ananyev~~~~~
80502dc5b7dSKonstantin Ananyev
80602dc5b7dSKonstantin AnanyevIn the ipsec-secgw/test directory
80702dc5b7dSKonstantin Ananyev
80802dc5b7dSKonstantin Ananyevto run one test for IPv4 or IPv6
80902dc5b7dSKonstantin Ananyev
81002dc5b7dSKonstantin Ananyev/bin/bash linux_test(4|6).sh <ipsec_mode>
81102dc5b7dSKonstantin Ananyev
81202dc5b7dSKonstantin Ananyevto run all tests for IPv4 or IPv6
81302dc5b7dSKonstantin Ananyev
81402dc5b7dSKonstantin Ananyev/bin/bash run_test.sh -4|-6
81502dc5b7dSKonstantin Ananyev
81602dc5b7dSKonstantin AnanyevFor the list of available modes please refer to run_test.sh.
817