event/cnxk: add option to configure getwork mode
[dpdk.git] / doc / guides / sample_app_ug / ipsec_secgw.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2016-2017 Intel Corporation.
3     Copyright (C) 2020 Marvell International Ltd.
4
5 IPsec Security Gateway Sample Application
6 =========================================
7
8 The IPsec Security Gateway application is an example of a "real world"
9 application using DPDK cryptodev framework.
10
11 Overview
12 --------
13
14 The application demonstrates the implementation of a Security Gateway
15 (not IPsec compliant, see the Constraints section below) using DPDK based on RFC4301,
16 RFC4303, RFC3602 and RFC2404.
17
18 Internet Key Exchange (IKE) is not implemented, so only manual setting of
19 Security Policies and Security Associations is supported.
20
21 The Security Policies (SP) are implemented as ACL rules, the Security
22 Associations (SA) are stored in a table and the routing is implemented
23 using LPM.
24
25 The application classifies the ports as *Protected* and *Unprotected*.
26 Thus, traffic received on an Unprotected or Protected port is consider
27 Inbound or Outbound respectively.
28
29 The application also supports complete IPsec protocol offload to hardware
30 (Look aside crypto accelerator or using ethernet device). It also support
31 inline ipsec processing by the supported ethernet device during transmission.
32 These modes can be selected during the SA creation configuration.
33
34 In case of complete protocol offload, the processing of headers(ESP and outer
35 IP header) is done by the hardware and the application does not need to
36 add/remove them during outbound/inbound processing.
37
38 For inline offloaded outbound traffic, the application will not do the LPM
39 lookup for routing, as the port on which the packet has to be forwarded will be
40 part of the SA. Security parameters will be configured on that port only, and
41 sending the packet on other ports could result in unencrypted packets being
42 sent out.
43
44 The Path for IPsec Inbound traffic is:
45
46 *  Read packets from the port.
47 *  Classify packets between IPv4 and ESP.
48 *  Perform Inbound SA lookup for ESP packets based on their SPI.
49 *  Perform Verification/Decryption (Not needed in case of inline ipsec).
50 *  Remove ESP and outer IP header (Not needed in case of protocol offload).
51 *  Inbound SP check using ACL of decrypted packets and any other IPv4 packets.
52 *  Routing.
53 *  Write packet to port.
54
55 The Path for the IPsec Outbound traffic is:
56
57 *  Read packets from the port.
58 *  Perform Outbound SP check using ACL of all IPv4 traffic.
59 *  Perform Outbound SA lookup for packets that need IPsec protection.
60 *  Add ESP and outer IP header (Not needed in case protocol offload).
61 *  Perform Encryption/Digest (Not needed in case of inline ipsec).
62 *  Routing.
63 *  Write packet to port.
64
65 The application supports two modes of operation: poll mode and event mode.
66
67 * In the poll mode a core receives packets from statically configured list
68   of eth ports and eth ports' queues.
69
70 * In the event mode a core receives packets as events. After packet processing
71   is done core submits them back as events to an event device. This enables
72   multicore scaling and HW assisted scheduling by making use of the event device
73   capabilities. The event mode configuration is predefined. All packets reaching
74   given eth port will arrive at the same event queue. All event queues are mapped
75   to all event ports. This allows all cores to receive traffic from all ports.
76   Since the underlying event device might have varying capabilities, the worker
77   threads can be drafted differently to maximize performance. For example, if an
78   event device - eth device pair has Tx internal port, then application can call
79   rte_event_eth_tx_adapter_enqueue() instead of regular rte_event_enqueue_burst().
80   So a thread which assumes that the device pair has internal port will not be the
81   right solution for another pair. The infrastructure added for the event mode aims
82   to help application to have multiple worker threads by maximizing performance from
83   every type of event device without affecting existing paths/use cases. The worker
84   to be used will be determined by the operating conditions and the underlying device
85   capabilities. **Currently the application provides non-burst, internal port worker
86   threads and supports inline protocol only.** It also provides infrastructure for
87   non-internal port however does not define any worker threads.
88
89 Additionally the event mode introduces two submodes of processing packets:
90
91 * Driver submode: This submode has bare minimum changes in the application to support
92   IPsec. There are no lookups, no routing done in the application. And for inline
93   protocol use case, the worker thread resembles l2fwd worker thread as the IPsec
94   processing is done entirely in HW. This mode can be used to benchmark the raw
95   performance of the HW. The driver submode is selected with --single-sa option
96   (used also by poll mode). When --single-sa option is used in conjution with event
97   mode then index passed to --single-sa is ignored.
98
99 * App submode: This submode has all the features currently implemented with the
100   application (non librte_ipsec path). All the lookups, routing follows existing
101   methods and report numbers that can be compared against regular poll mode
102   benchmark numbers.
103
104 Constraints
105 -----------
106
107 *  No IPv6 options headers.
108 *  No AH mode.
109 *  Supported algorithms: AES-CBC, AES-CTR, AES-GCM, 3DES-CBC, HMAC-SHA1 and NULL.
110 *  Each SA must be handle by a unique lcore (*1 RX queue per port*).
111
112 Compiling the Application
113 -------------------------
114
115 To compile the sample application see :doc:`compiling`.
116
117 The application is located in the ``ipsec-secgw`` sub-directory.
118
119
120 Running the Application
121 -----------------------
122
123 The application has a number of command line options::
124
125
126    ./<build_dir>/examples/dpdk-ipsec-secgw [EAL options] --
127                         -p PORTMASK -P -u PORTMASK -j FRAMESIZE
128                         -l -w REPLAY_WINDOW_SIZE -e -a
129                         -c SAD_CACHE_SIZE
130                         -s NUMBER_OF_MBUFS_IN_PACKET_POOL
131                         -f CONFIG_FILE_PATH
132                         --config (port,queue,lcore)[,(port,queue,lcore)]
133                         --single-sa SAIDX
134                         --cryptodev_mask MASK
135                         --transfer-mode MODE
136                         --event-schedule-type TYPE
137                         --rxoffload MASK
138                         --txoffload MASK
139                         --reassemble NUM
140                         --mtu MTU
141                         --frag-ttl FRAG_TTL_NS
142
143 Where:
144
145 *   ``-p PORTMASK``: Hexadecimal bitmask of ports to configure.
146
147 *   ``-P``: *optional*. Sets all ports to promiscuous mode so that packets are
148     accepted regardless of the packet's Ethernet MAC destination address.
149     Without this option, only packets with the Ethernet MAC destination address
150     set to the Ethernet address of the port are accepted (default is enabled).
151
152 *   ``-u PORTMASK``: hexadecimal bitmask of unprotected ports
153
154 *   ``-j FRAMESIZE``: *optional*. data buffer size (in bytes),
155     in other words maximum data size for one segment.
156     Packets with length bigger then FRAMESIZE still can be received,
157     but will be segmented.
158     Default value: RTE_MBUF_DEFAULT_BUF_SIZE (2176)
159     Minimum value: RTE_MBUF_DEFAULT_BUF_SIZE (2176)
160     Maximum value: UINT16_MAX (65535).
161
162 *   ``-l``: enables code-path that uses librte_ipsec.
163
164 *   ``-w REPLAY_WINDOW_SIZE``: specifies the IPsec sequence number replay window
165     size for each Security Association (available only with librte_ipsec
166     code path).
167
168 *   ``-e``: enables Security Association extended sequence number processing
169     (available only with librte_ipsec code path).
170
171 *   ``-a``: enables Security Association sequence number atomic behavior
172     (available only with librte_ipsec code path).
173
174 *   ``-c``: specifies the SAD cache size. Stores the most recent SA in a per
175     lcore cache. Cache represents flat array containing SA's indexed by SPI.
176     Zero value disables cache.
177     Default value: 128.
178
179 *   ``-s``: sets number of mbufs in packet pool, if not provided number of mbufs
180     will be calculated based on number of cores, eth ports and crypto queues.
181
182 *   ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all
183     configuration items for running the application (See Configuration file
184     syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified.
185     **ONLY** the UNIX format configuration file is accepted.
186
187 *   ``--config (port,queue,lcore)[,(port,queue,lcore)]``: in poll mode determines
188     which queues from which ports are mapped to which cores. In event mode this
189     option is not used as packets are dynamically scheduled to cores by HW.
190
191 *   ``--single-sa SAIDX``: in poll mode use a single SA for outbound traffic,
192     bypassing the SP on both Inbound and Outbound. This option is meant for
193     debugging/performance purposes. In event mode selects driver submode, SA index
194     value is ignored.
195
196 *   ``--cryptodev_mask MASK``: hexadecimal bitmask of the crypto devices
197     to configure.
198
199 *   ``--transfer-mode MODE``: sets operating mode of the application
200     "poll"  : packet transfer via polling (default)
201     "event" : Packet transfer via event device
202
203 *   ``--event-schedule-type TYPE``: queue schedule type, applies only when
204     --transfer-mode is set to event.
205     "ordered"  : Ordered (default)
206     "atomic"   : Atomic
207     "parallel" : Parallel
208     When --event-schedule-type is set as RTE_SCHED_TYPE_ORDERED/ATOMIC, event
209     device will ensure the ordering. Ordering will be lost when tried in PARALLEL.
210
211 *   ``--rxoffload MASK``: RX HW offload capabilities to enable/use on this port
212     (bitmask of DEV_RX_OFFLOAD_* values). It is an optional parameter and
213     allows user to disable some of the RX HW offload capabilities.
214     By default all HW RX offloads are enabled.
215
216 *   ``--txoffload MASK``: TX HW offload capabilities to enable/use on this port
217     (bitmask of DEV_TX_OFFLOAD_* values). It is an optional parameter and
218     allows user to disable some of the TX HW offload capabilities.
219     By default all HW TX offloads are enabled.
220
221 *   ``--reassemble NUM``: max number of entries in reassemble fragment table.
222     Zero value disables reassembly functionality.
223     Default value: 0.
224
225 *   ``--mtu MTU``: MTU value (in bytes) on all attached ethernet ports.
226     Outgoing packets with length bigger then MTU will be fragmented.
227     Incoming packets with length bigger then MTU will be discarded.
228     Default value: 1500.
229
230 *   ``--frag-ttl FRAG_TTL_NS``: fragment lifetime (in nanoseconds).
231     If packet is not reassembled within this time, received fragments
232     will be discarded. Fragment lifetime should be decreased when
233     there is a high fragmented traffic loss in high bandwidth networks.
234     Should be lower for low number of reassembly buckets.
235     Valid values: from 1 ns to 10 s. Default value: 10000000 (10 s).
236
237
238 The mapping of lcores to port/queues is similar to other l3fwd applications.
239
240 For example, given the following command line to run application in poll mode::
241
242     ./<build_dir>/examples/dpdk-ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048       \
243            --vdev "crypto_null" -- -p 0xf -P -u 0x3             \
244            --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)"       \
245            -f /path/to/config_file --transfer-mode poll         \
246
247 where each option means:
248
249 *   The ``-l`` option enables cores 20 and 21.
250
251 *   The ``-n`` option sets memory 4 channels.
252
253 *   The ``--socket-mem`` to use 2GB on socket 1.
254
255 *   The ``--vdev "crypto_null"`` option creates virtual NULL cryptodev PMD.
256
257 *   The ``-p`` option enables ports (detected) 0, 1, 2 and 3.
258
259 *   The ``-P`` option enables promiscuous mode.
260
261 *   The ``-u`` option sets ports 0 and 1 as unprotected, leaving 2 and 3 as protected.
262
263 *   The ``--config`` option enables one queue per port with the following mapping:
264
265     +----------+-----------+-----------+---------------------------------------+
266     | **Port** | **Queue** | **lcore** | **Description**                       |
267     |          |           |           |                                       |
268     +----------+-----------+-----------+---------------------------------------+
269     | 0        | 0         | 20        | Map queue 0 from port 0 to lcore 20.  |
270     |          |           |           |                                       |
271     +----------+-----------+-----------+---------------------------------------+
272     | 1        | 0         | 20        | Map queue 0 from port 1 to lcore 20.  |
273     |          |           |           |                                       |
274     +----------+-----------+-----------+---------------------------------------+
275     | 2        | 0         | 21        | Map queue 0 from port 2 to lcore 21.  |
276     |          |           |           |                                       |
277     +----------+-----------+-----------+---------------------------------------+
278     | 3        | 0         | 21        | Map queue 0 from port 3 to lcore 21.  |
279     |          |           |           |                                       |
280     +----------+-----------+-----------+---------------------------------------+
281
282 *   The ``-f /path/to/config_file`` option enables the application read and
283     parse the configuration file specified, and configures the application
284     with a given set of SP, SA and Routing entries accordingly. The syntax of
285     the configuration file will be explained below in more detail. Please
286     **note** the parser only accepts UNIX format text file. Other formats
287     such as DOS/MAC format will cause a parse error.
288
289 *   The ``--transfer-mode`` option selects poll mode for processing packets.
290
291 Similarly for example, given the following command line to run application in
292 event app mode::
293
294     ./<build_dir>/examples/dpdk-ipsec-secgw -c 0x3 -- -P -p 0x3 -u 0x1       \
295            -f /path/to/config_file --transfer-mode event \
296            --event-schedule-type parallel                \
297
298 where each option means:
299
300 *   The ``-c`` option selects cores 0 and 1 to run on.
301
302 *   The ``-P`` option enables promiscuous mode.
303
304 *   The ``-p`` option enables ports (detected) 0 and 1.
305
306 *   The ``-u`` option sets ports 0 as unprotected, leaving 1 as protected.
307
308 *   The ``-f /path/to/config_file`` option has the same behavior as in poll
309     mode example.
310
311 *   The ``--transfer-mode`` option selects event mode for processing packets.
312
313 *   The ``--event-schedule-type`` option selects parallel ordering of event queues.
314
315
316 Refer to the *DPDK Getting Started Guide* for general information on running
317 applications and the Environment Abstraction Layer (EAL) options.
318
319 The application would do a best effort to "map" crypto devices to cores, with
320 hardware devices having priority. Basically, hardware devices if present would
321 be assigned to a core before software ones.
322 This means that if the application is using a single core and both hardware
323 and software crypto devices are detected, hardware devices will be used.
324
325 A way to achieve the case where you want to force the use of virtual crypto
326 devices is to only use the Ethernet devices needed (via the allow flag)
327 and therefore implicitly blocking all hardware crypto devices.
328
329 For example, something like the following command line:
330
331 .. code-block:: console
332
333     ./<build_dir>/examples/dpdk-ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \
334             -a 81:00.0 -a 81:00.1 -a 81:00.2 -a 81:00.3 \
335             --vdev "crypto_aesni_mb" --vdev "crypto_null" \
336             -- \
337             -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \
338             -f sample.cfg
339
340
341 Configurations
342 --------------
343
344 The following sections provide the syntax of configurations to initialize
345 your SP, SA, Routing, Flow and Neighbour tables.
346 Configurations shall be specified in the configuration file to be passed to
347 the application. The file is then parsed by the application. The successful
348 parsing will result in the appropriate rules being applied to the tables
349 accordingly.
350
351
352 Configuration File Syntax
353 ~~~~~~~~~~~~~~~~~~~~~~~~~
354
355 As mention in the overview, the Security Policies are ACL rules.
356 The application parsers the rules specified in the configuration file and
357 passes them to the ACL table, and replicates them per socket in use.
358
359 Following are the configuration file syntax.
360
361 General rule syntax
362 ^^^^^^^^^^^^^^^^^^^
363
364 The parse treats one line in the configuration file as one configuration
365 item (unless the line concatenation symbol exists). Every configuration
366 item shall follow the syntax of either SP, SA, Routing, Flow or Neighbour
367 rules specified below.
368
369 The configuration parser supports the following special symbols:
370
371  * Comment symbol **#**. Any character from this symbol to the end of
372    line is treated as comment and will not be parsed.
373
374  * Line concatenation symbol **\\**. This symbol shall be placed in the end
375    of the line to be concatenated to the line below. Multiple lines'
376    concatenation is supported.
377
378
379 SP rule syntax
380 ^^^^^^^^^^^^^^
381
382 The SP rule syntax is shown as follows:
383
384 .. code-block:: console
385
386     sp <ip_ver> <dir> esp <action> <priority> <src_ip> <dst_ip>
387     <proto> <sport> <dport>
388
389
390 where each options means:
391
392 ``<ip_ver>``
393
394  * IP protocol version
395
396  * Optional: No
397
398  * Available options:
399
400    * *ipv4*: IP protocol version 4
401    * *ipv6*: IP protocol version 6
402
403 ``<dir>``
404
405  * The traffic direction
406
407  * Optional: No
408
409  * Available options:
410
411    * *in*: inbound traffic
412    * *out*: outbound traffic
413
414 ``<action>``
415
416  * IPsec action
417
418  * Optional: No
419
420  * Available options:
421
422    * *protect <SA_idx>*: the specified traffic is protected by SA rule
423      with id SA_idx
424    * *bypass*: the specified traffic traffic is bypassed
425    * *discard*: the specified traffic is discarded
426
427 ``<priority>``
428
429  * Rule priority
430
431  * Optional: Yes, default priority 0 will be used
432
433  * Syntax: *pri <id>*
434
435 ``<src_ip>``
436
437  * The source IP address and mask
438
439  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
440
441  * Syntax:
442
443    * *src X.X.X.X/Y* for IPv4
444    * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
445
446 ``<dst_ip>``
447
448  * The destination IP address and mask
449
450  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
451
452  * Syntax:
453
454    * *dst X.X.X.X/Y* for IPv4
455    * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
456
457 ``<proto>``
458
459  * The protocol start and end range
460
461  * Optional: yes, default range of 0 to 0 will be used
462
463  * Syntax: *proto X:Y*
464
465 ``<sport>``
466
467  * The source port start and end range
468
469  * Optional: yes, default range of 0 to 0 will be used
470
471  * Syntax: *sport X:Y*
472
473 ``<dport>``
474
475  * The destination port start and end range
476
477  * Optional: yes, default range of 0 to 0 will be used
478
479  * Syntax: *dport X:Y*
480
481 Example SP rules:
482
483 .. code-block:: console
484
485     sp ipv4 out esp protect 105 pri 1 dst 192.168.115.0/24 sport 0:65535 \
486     dport 0:65535
487
488     sp ipv6 in esp bypass pri 1 dst 0000:0000:0000:0000:5555:5555:\
489     0000:0000/96 sport 0:65535 dport 0:65535
490
491
492 SA rule syntax
493 ^^^^^^^^^^^^^^
494
495 The successfully parsed SA rules will be stored in an array table.
496
497 The SA rule syntax is shown as follows:
498
499 .. code-block:: console
500
501     sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key>
502     <mode> <src_ip> <dst_ip> <action_type> <port_id> <fallback>
503     <flow-direction> <port_id> <queue_id> <udp-encap>
504
505 where each options means:
506
507 ``<dir>``
508
509  * The traffic direction
510
511  * Optional: No
512
513  * Available options:
514
515    * *in*: inbound traffic
516    * *out*: outbound traffic
517
518 ``<spi>``
519
520  * The SPI number
521
522  * Optional: No
523
524  * Syntax: unsigned integer number
525
526 ``<cipher_algo>``
527
528  * Cipher algorithm
529
530  * Optional: Yes, unless <aead_algo> is not used
531
532  * Available options:
533
534    * *null*: NULL algorithm
535    * *aes-128-cbc*: AES-CBC 128-bit algorithm
536    * *aes-192-cbc*: AES-CBC 192-bit algorithm
537    * *aes-256-cbc*: AES-CBC 256-bit algorithm
538    * *aes-128-ctr*: AES-CTR 128-bit algorithm
539    * *3des-cbc*: 3DES-CBC 192-bit algorithm
540
541  * Syntax: *cipher_algo <your algorithm>*
542
543 ``<cipher_key>``
544
545  * Cipher key, NOT available when 'null' algorithm is used
546
547  * Optional: Yes, unless <aead_algo> is not used.
548    Must be followed by <cipher_algo> option
549
550  * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
551    The number of bytes should be as same as the specified cipher algorithm
552    key size.
553
554    For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
555    A1:B2:C3:D4*
556
557 ``<auth_algo>``
558
559  * Authentication algorithm
560
561  * Optional: Yes, unless <aead_algo> is not used
562
563  * Available options:
564
565     * *null*: NULL algorithm
566     * *sha1-hmac*: HMAC SHA1 algorithm
567
568 ``<auth_key>``
569
570  * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm
571    is used.
572
573  * Optional: Yes, unless <aead_algo> is not used.
574    Must be followed by <auth_algo> option
575
576  * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
577    The number of bytes should be as same as the specified authentication
578    algorithm key size.
579
580    For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
581    A1:B2:C3:D4*
582
583 ``<aead_algo>``
584
585  * AEAD algorithm
586
587  * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used
588
589  * Available options:
590
591    * *aes-128-gcm*: AES-GCM 128-bit algorithm
592    * *aes-192-gcm*: AES-GCM 192-bit algorithm
593    * *aes-256-gcm*: AES-GCM 256-bit algorithm
594
595  * Syntax: *cipher_algo <your algorithm>*
596
597 ``<aead_key>``
598
599  * Cipher key, NOT available when 'null' algorithm is used
600
601  * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used.
602    Must be followed by <aead_algo> option
603
604  * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
605    Last 4 bytes of the provided key will be used as 'salt' and so, the
606    number of bytes should be same as the sum of specified AEAD algorithm
607    key size and salt size (4 bytes).
608
609    For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
610    A1:B2:C3:D4:A1:B2:C3:D4*
611
612 ``<mode>``
613
614  * The operation mode
615
616  * Optional: No
617
618  * Available options:
619
620    * *ipv4-tunnel*: Tunnel mode for IPv4 packets
621    * *ipv6-tunnel*: Tunnel mode for IPv6 packets
622    * *transport*: transport mode
623
624  * Syntax: mode XXX
625
626 ``<src_ip>``
627
628  * The source IP address. This option is not available when
629    transport mode is used
630
631  * Optional: Yes, default address 0.0.0.0 will be used
632
633  * Syntax:
634
635    * *src X.X.X.X* for IPv4
636    * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
637
638 ``<dst_ip>``
639
640  * The destination IP address. This option is not available when
641    transport mode is used
642
643  * Optional: Yes, default address 0.0.0.0 will be used
644
645  * Syntax:
646
647    * *dst X.X.X.X* for IPv4
648    * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
649
650 ``<type>``
651
652  * Action type to specify the security action. This option specify
653    the SA to be performed with look aside protocol offload to HW
654    accelerator or protocol offload on ethernet device or inline
655    crypto processing on the ethernet device during transmission.
656
657  * Optional: Yes, default type *no-offload*
658
659  * Available options:
660
661    * *lookaside-protocol-offload*: look aside protocol offload to HW accelerator
662    * *inline-protocol-offload*: inline protocol offload on ethernet device
663    * *inline-crypto-offload*: inline crypto processing on ethernet device
664    * *no-offload*: no offloading to hardware
665
666  ``<port_id>``
667
668  * Port/device ID of the ethernet/crypto accelerator for which the SA is
669    configured. For *inline-crypto-offload* and *inline-protocol-offload*, this
670    port will be used for routing. The routing table will not be referred in
671    this case.
672
673  * Optional: No, if *type* is not *no-offload*
674
675  * Syntax:
676
677    * *port_id X* X is a valid device number in decimal
678
679  ``<fallback>``
680
681  * Action type for ingress IPsec packets that inline processor failed to
682    process. Only a combination of *inline-crypto-offload* as a primary
683    session and *lookaside-none* as a fall-back session is supported at the
684    moment.
685
686    If used in conjunction with IPsec window, its width needs be increased
687    due to different processing times of inline and lookaside modes which
688    results in packet reordering.
689
690  * Optional: Yes.
691
692  * Available options:
693
694    * *lookaside-none*: use automatically chosen cryptodev to process packets
695
696  * Syntax:
697
698    * *fallback lookaside-none*
699
700 ``<flow-direction>``
701
702  * Option for redirecting a specific inbound ipsec flow of a port to a specific
703    queue of that port.
704
705  * Optional: Yes.
706
707  * Available options:
708
709    * *port_id*: Port ID of the NIC for which the SA is configured.
710    * *queue_id*: Queue ID to which traffic should be redirected.
711
712  ``<udp-encap>``
713
714  * Option to enable IPsec UDP encapsulation for NAT Traversal.
715    Only *lookaside-protocol-offload* mode is supported at the moment.
716
717  * Optional: Yes, it is disabled by default
718
719  * Syntax:
720
721    * *udp-encap*
722
723 Example SA rules:
724
725 .. code-block:: console
726
727     sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \
728     src 172.16.1.5 dst 172.16.2.5
729
730     sa out 25 cipher_algo aes-128-cbc \
731     cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
732     auth_algo sha1-hmac \
733     auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
734     mode ipv6-tunnel \
735     src 1111:1111:1111:1111:1111:1111:1111:5555 \
736     dst 2222:2222:2222:2222:2222:2222:2222:5555
737
738     sa in 105 aead_algo aes-128-gcm \
739     aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
740     mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5
741
742     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 \
743     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 \
744     mode ipv4-tunnel src 172.16.1.5 dst 172.16.2.5 \
745     type lookaside-protocol-offload port_id 4
746
747     sa in 35 aead_algo aes-128-gcm \
748     aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
749     mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 \
750     type inline-crypto-offload port_id 0
751
752     sa in 117 cipher_algo null auth_algo null mode ipv4-tunnel src 172.16.2.7 \
753     dst 172.16.1.7 flow-direction 0 2
754
755 Routing rule syntax
756 ^^^^^^^^^^^^^^^^^^^
757
758 The Routing rule syntax is shown as follows:
759
760 .. code-block:: console
761
762     rt <ip_ver> <src_ip> <dst_ip> <port>
763
764
765 where each options means:
766
767 ``<ip_ver>``
768
769  * IP protocol version
770
771  * Optional: No
772
773  * Available options:
774
775    * *ipv4*: IP protocol version 4
776    * *ipv6*: IP protocol version 6
777
778 ``<src_ip>``
779
780  * The source IP address and mask
781
782  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
783
784  * Syntax:
785
786    * *src X.X.X.X/Y* for IPv4
787    * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
788
789 ``<dst_ip>``
790
791  * The destination IP address and mask
792
793  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
794
795  * Syntax:
796
797    * *dst X.X.X.X/Y* for IPv4
798    * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
799
800 ``<port>``
801
802  * The traffic output port id
803
804  * Optional: yes, default output port 0 will be used
805
806  * Syntax: *port X*
807
808 Example SP rules:
809
810 .. code-block:: console
811
812     rt ipv4 dst 172.16.1.5/32 port 0
813
814     rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0
815
816 Flow rule syntax
817 ^^^^^^^^^^^^^^^^
818
819 Flow rule enables the usage of hardware classification capabilities to match specific
820 ingress traffic and redirect the packets to the specified queue. This feature is
821 optional and relies on hardware ``rte_flow`` support.
822
823 The flow rule syntax is shown as follows:
824
825 .. code-block:: console
826
827     flow <ip_ver> <src_ip> <dst_ip> <port> <queue>
828
829
830 where each options means:
831
832 ``<ip_ver>``
833
834  * IP protocol version
835
836  * Optional: No
837
838  * Available options:
839
840    * *ipv4*: IP protocol version 4
841    * *ipv6*: IP protocol version 6
842
843 ``<src_ip>``
844
845  * The source IP address and mask
846
847  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
848
849  * Syntax:
850
851    * *src X.X.X.X/Y* for IPv4
852    * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
853
854 ``<dst_ip>``
855
856  * The destination IP address and mask
857
858  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
859
860  * Syntax:
861
862    * *dst X.X.X.X/Y* for IPv4
863    * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
864
865 ``<port>``
866
867  * The traffic input port id
868
869  * Optional: yes, default input port 0 will be used
870
871  * Syntax: *port X*
872
873 ``<queue>``
874
875  * The traffic input queue id
876
877  * Optional: yes, default input queue 0 will be used
878
879  * Syntax: *queue X*
880
881 Example flow rules:
882
883 .. code-block:: console
884
885     flow ipv4 dst 172.16.1.5/32 port 0 queue 0
886
887     flow ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 1 queue 0
888
889
890 Neighbour rule syntax
891 ^^^^^^^^^^^^^^^^^^^^^
892
893 The Neighbour rule syntax is shown as follows:
894
895 .. code-block:: console
896
897     neigh <port> <dst_mac>
898
899
900 where each options means:
901
902 ``<port>``
903
904  * The output port id
905
906  * Optional: No
907
908  * Syntax: *port X*
909
910 ``<dst_mac>``
911
912  * The destination ethernet address to use for that port
913
914  * Optional: No
915
916  * Syntax:
917
918    * XX:XX:XX:XX:XX:XX
919
920 Example Neighbour rules:
921
922 .. code-block:: console
923
924     neigh port 0 DE:AD:BE:EF:01:02
925
926 Test directory
927 --------------
928
929 The test directory contains scripts for testing the various encryption
930 algorithms.
931
932 The purpose of the scripts is to automate ipsec-secgw testing
933 using another system running linux as a DUT.
934
935 The user must setup the following environment variables:
936
937 *   ``SGW_PATH``: path to the ipsec-secgw binary to test.
938
939 *   ``REMOTE_HOST``: IP address/hostname of the DUT.
940
941 *   ``REMOTE_IFACE``: interface name for the test-port on the DUT.
942
943 *   ``ETH_DEV``: ethernet device to be used on the SUT by DPDK ('-a <pci-id>')
944
945 Also the user can optionally setup:
946
947 *   ``SGW_LCORE``: lcore to run ipsec-secgw on (default value is 0)
948
949 *   ``CRYPTO_DEV``: crypto device to be used ('-a <pci-id>'). If none specified
950     appropriate vdevs will be created by the script
951
952 Scripts can be used for multiple test scenarios. To check all available
953 options run:
954
955 .. code-block:: console
956
957     /bin/bash run_test.sh -h
958
959 Note that most of the tests require the appropriate crypto PMD/device to be
960 available.
961
962 Server configuration
963 ~~~~~~~~~~~~~~~~~~~~
964
965 Two servers are required for the tests, SUT and DUT.
966
967 Make sure the user from the SUT can ssh to the DUT without entering the password.
968 To enable this feature keys must be setup on the DUT.
969
970 ``ssh-keygen`` will make a private & public key pair on the SUT.
971
972 ``ssh-copy-id`` <user name>@<target host name> on the SUT will copy the public
973 key to the DUT. It will ask for credentials so that it can upload the public key.
974
975 The SUT and DUT are connected through at least 2 NIC ports.
976
977 One NIC port is expected to be managed by linux on both machines and will be
978 used as a control path.
979
980 The second NIC port (test-port) should be bound to DPDK on the SUT, and should
981 be managed by linux on the DUT.
982
983 The script starts ``ipsec-secgw`` with 2 NIC devices: ``test-port`` and
984 ``tap vdev``.
985
986 It then configures the local tap interface and the remote interface and IPsec
987 policies in the following way:
988
989 Traffic going over the test-port in both directions has to be protected by IPsec.
990
991 Traffic going over the TAP port in both directions does not have to be protected.
992
993 i.e:
994
995 DUT OS(NIC1)--(IPsec)-->(NIC1)ipsec-secgw(TAP)--(plain)-->(TAP)SUT OS
996
997 SUT OS(TAP)--(plain)-->(TAP)psec-secgw(NIC1)--(IPsec)-->(NIC1)DUT OS
998
999 It then tries to perform some data transfer using the scheme described above.
1000
1001 Usage
1002 ~~~~~
1003
1004 In the ipsec-secgw/test directory run
1005
1006 /bin/bash run_test.sh <options> <ipsec_mode>
1007
1008 Available options:
1009
1010 *   ``-4`` Perform tests with use of IPv4. One or both [-46] options needs to be
1011     selected.
1012
1013 *   ``-6`` Perform tests with use of IPv6. One or both [-46] options needs to be
1014     selected.
1015
1016 *   ``-m`` Add IPSec tunnel mixed IP version tests - outer IP version different
1017     than inner. Inner IP version will match selected option [-46].
1018
1019 *   ``-i`` Run tests in inline mode. Regular tests will not be invoked.
1020
1021 *   ``-f`` Run tests for fallback mechanism. Regular tests will not be invoked.
1022
1023 *   ``-l`` Run tests in legacy mode only. It cannot be used with options [-fsc].
1024     On default library mode is used.
1025
1026 *   ``-s`` Run all tests with reassembly support. On default only tests for
1027     fallback mechanism use reassembly support.
1028
1029 *   ``-c`` Run tests with use of cpu-crypto. For inline tests it will not be
1030     applied. On default lookaside-none is used.
1031
1032 *   ``-p`` Perform packet validation tests. Option [-46] is not required.
1033
1034 *   ``-h`` Show usage.
1035
1036 If <ipsec_mode> is specified, only tests for that mode will be invoked. For the
1037 list of available modes please refer to run_test.sh.