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