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