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