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 conjunction 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 RTE_ETH_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 RTE_ETH_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.