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