doc/guides/sample_app_ug/ipsec_secgw.rst

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