doc/guides/sample_app_ug/ipsec_secgw.rst

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