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