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 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 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
 510 where each options means:
 511
 512 ``<dir>``
 513
 514  * The traffic direction
 515
 516  * Optional: No
 517
 518  * Available options:
 519
 520    * *in*: inbound traffic
 521    * *out*: outbound traffic
 522
 523 ``<spi>``
 524
 525  * The SPI number
 526
 527  * Optional: No
 528
 529  * Syntax: unsigned integer number
 530
 531 ``<cipher_algo>``
 532
 533  * Cipher algorithm
 534
 535  * Optional: Yes, unless <aead_algo> is not used
 536
 537  * Available options:
 538
 539    * *null*: NULL algorithm
 540    * *aes-128-cbc*: AES-CBC 128-bit algorithm
 541    * *aes-192-cbc*: AES-CBC 192-bit algorithm
 542    * *aes-256-cbc*: AES-CBC 256-bit algorithm
 543    * *aes-128-ctr*: AES-CTR 128-bit algorithm
 544    * *3des-cbc*: 3DES-CBC 192-bit algorithm
 545
 546  * Syntax: *cipher_algo <your algorithm>*
 547
 548 ``<cipher_key>``
 549
 550  * Cipher key, NOT available when 'null' algorithm is used
 551
 552  * Optional: Yes, unless <aead_algo> is not used.
 553    Must be followed by <cipher_algo> option
 554
 555  * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
 556    The number of bytes should be as same as the specified cipher algorithm
 557    key size.
 558
 559    For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
 560    A1:B2:C3:D4*
 561
 562 ``<auth_algo>``
 563
 564  * Authentication algorithm
 565
 566  * Optional: Yes, unless <aead_algo> is not used
 567
 568  * Available options:
 569
 570     * *null*: NULL algorithm
 571     * *sha1-hmac*: HMAC SHA1 algorithm
 572
 573 ``<auth_key>``
 574
 575  * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm
 576    is used.
 577
 578  * Optional: Yes, unless <aead_algo> is not used.
 579    Must be followed by <auth_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 authentication
 583    algorithm key size.
 584
 585    For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
 586    A1:B2:C3:D4*
 587
 588 ``<aead_algo>``
 589
 590  * AEAD algorithm
 591
 592  * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used
 593
 594  * Available options:
 595
 596    * *aes-128-gcm*: AES-GCM 128-bit algorithm
 597    * *aes-192-gcm*: AES-GCM 192-bit algorithm
 598    * *aes-256-gcm*: AES-GCM 256-bit algorithm
 599
 600  * Syntax: *cipher_algo <your algorithm>*
 601
 602 ``<aead_key>``
 603
 604  * Cipher key, NOT available when 'null' algorithm is used
 605
 606  * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used.
 607    Must be followed by <aead_algo> option
 608
 609  * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
 610    Last 4 bytes of the provided key will be used as 'salt' and so, the
 611    number of bytes should be same as the sum of specified AEAD algorithm
 612    key size and salt size (4 bytes).
 613
 614    For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
 615    A1:B2:C3:D4:A1:B2:C3:D4*
 616
 617 ``<mode>``
 618
 619  * The operation mode
 620
 621  * Optional: No
 622
 623  * Available options:
 624
 625    * *ipv4-tunnel*: Tunnel mode for IPv4 packets
 626    * *ipv6-tunnel*: Tunnel mode for IPv6 packets
 627    * *transport*: transport mode
 628
 629  * Syntax: mode XXX
 630
 631 ``<src_ip>``
 632
 633  * The source IP address. This option is not available when
 634    transport mode is used
 635
 636  * Optional: Yes, default address 0.0.0.0 will be used
 637
 638  * Syntax:
 639
 640    * *src X.X.X.X* for IPv4
 641    * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
 642
 643 ``<dst_ip>``
 644
 645  * The destination IP address. This option is not available when
 646    transport mode is used
 647
 648  * Optional: Yes, default address 0.0.0.0 will be used
 649
 650  * Syntax:
 651
 652    * *dst X.X.X.X* for IPv4
 653    * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
 654
 655 ``<type>``
 656
 657  * Action type to specify the security action. This option specify
 658    the SA to be performed with look aside protocol offload to HW
 659    accelerator or protocol offload on ethernet device or inline
 660    crypto processing on the ethernet device during transmission.
 661
 662  * Optional: Yes, default type *no-offload*
 663
 664  * Available options:
 665
 666    * *lookaside-protocol-offload*: look aside protocol offload to HW accelerator
 667    * *inline-protocol-offload*: inline protocol offload on ethernet device
 668    * *inline-crypto-offload*: inline crypto processing on ethernet device
 669    * *no-offload*: no offloading to hardware
 670
 671  ``<port_id>``
 672
 673  * Port/device ID of the ethernet/crypto accelerator for which the SA is
 674    configured. For *inline-crypto-offload* and *inline-protocol-offload*, this
 675    port will be used for routing. The routing table will not be referred in
 676    this case.
 677
 678  * Optional: No, if *type* is not *no-offload*
 679
 680  * Syntax:
 681
 682    * *port_id X* X is a valid device number in decimal
 683
 684  ``<fallback>``
 685
 686  * Action type for ingress IPsec packets that inline processor failed to
 687    process. Only a combination of *inline-crypto-offload* as a primary
 688    session and *lookaside-none* as a fall-back session is supported at the
 689    moment.
 690
 691    If used in conjunction with IPsec window, its width needs be increased
 692    due to different processing times of inline and lookaside modes which
 693    results in packet reordering.
 694
 695  * Optional: Yes.
 696
 697  * Available options:
 698
 699    * *lookaside-none*: use automatically chosen cryptodev to process packets
 700
 701  * Syntax:
 702
 703    * *fallback lookaside-none*
 704
 705 Example SA rules:
 706
 707 .. code-block:: console
 708
 709     sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \
 710     src 172.16.1.5 dst 172.16.2.5
 711
 712     sa out 25 cipher_algo aes-128-cbc \
 713     cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
 714     auth_algo sha1-hmac \
 715     auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
 716     mode ipv6-tunnel \
 717     src 1111:1111:1111:1111:1111:1111:1111:5555 \
 718     dst 2222:2222:2222:2222:2222:2222:2222:5555
 719
 720     sa in 105 aead_algo aes-128-gcm \
 721     aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
 722     mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5
 723
 724     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 \
 725     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 \
 726     mode ipv4-tunnel src 172.16.1.5 dst 172.16.2.5 \
 727     type lookaside-protocol-offload port_id 4
 728
 729     sa in 35 aead_algo aes-128-gcm \
 730     aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
 731     mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 \
 732     type inline-crypto-offload port_id 0
 733
 734 Routing rule syntax
 735 ^^^^^^^^^^^^^^^^^^^
 736
 737 The Routing rule syntax is shown as follows:
 738
 739 .. code-block:: console
 740
 741     rt <ip_ver> <src_ip> <dst_ip> <port>
 742
 743
 744 where each options means:
 745
 746 ``<ip_ver>``
 747
 748  * IP protocol version
 749
 750  * Optional: No
 751
 752  * Available options:
 753
 754    * *ipv4*: IP protocol version 4
 755    * *ipv6*: IP protocol version 6
 756
 757 ``<src_ip>``
 758
 759  * The source IP address and mask
 760
 761  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
 762
 763  * Syntax:
 764
 765    * *src X.X.X.X/Y* for IPv4
 766    * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
 767
 768 ``<dst_ip>``
 769
 770  * The destination IP address and mask
 771
 772  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
 773
 774  * Syntax:
 775
 776    * *dst X.X.X.X/Y* for IPv4
 777    * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
 778
 779 ``<port>``
 780
 781  * The traffic output port id
 782
 783  * Optional: yes, default output port 0 will be used
 784
 785  * Syntax: *port X*
 786
 787 Example SP rules:
 788
 789 .. code-block:: console
 790
 791     rt ipv4 dst 172.16.1.5/32 port 0
 792
 793     rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0
 794
 795 Neighbour rule syntax
 796 ^^^^^^^^^^^^^^^^^^^^^
 797
 798 The Neighbour rule syntax is shown as follows:
 799
 800 .. code-block:: console
 801
 802     neigh <port> <dst_mac>
 803
 804
 805 where each options means:
 806
 807 ``<port>``
 808
 809  * The output port id
 810
 811  * Optional: No
 812
 813  * Syntax: *port X*
 814
 815 ``<dst_mac>``
 816
 817  * The destination ethernet address to use for that port
 818
 819  * Optional: No
 820
 821  * Syntax:
 822
 823    * XX:XX:XX:XX:XX:XX
 824
 825 Example Neighbour rules:
 826
 827 .. code-block:: console
 828
 829     neigh port 0 DE:AD:BE:EF:01:02
 830
 831 Test directory
 832 --------------
 833
 834 The test directory contains scripts for testing the various encryption
 835 algorithms.
 836
 837 The purpose of the scripts is to automate ipsec-secgw testing
 838 using another system running linux as a DUT.
 839
 840 The user must setup the following environment variables:
 841
 842 *   ``SGW_PATH``: path to the ipsec-secgw binary to test.
 843
 844 *   ``REMOTE_HOST``: IP address/hostname of the DUT.
 845
 846 *   ``REMOTE_IFACE``: interface name for the test-port on the DUT.
 847
 848 *   ``ETH_DEV``: ethernet device to be used on the SUT by DPDK ('-w <pci-id>')
 849
 850 Also the user can optionally setup:
 851
 852 *   ``SGW_LCORE``: lcore to run ipsec-secgw on (default value is 0)
 853
 854 *   ``CRYPTO_DEV``: crypto device to be used ('-w <pci-id>'). If none specified
 855     appropriate vdevs will be created by the script
 856
 857 *   ``MULTI_SEG_TEST``: ipsec-secgw option to enable reassembly support and
 858     specify size of reassembly table (e.g.
 859     ``MULTI_SEG_TEST='--reassemble 128'``). This option must be set for
 860     fallback session tests.
 861
 862 Note that most of the tests require the appropriate crypto PMD/device to be
 863 available.
 864
 865 Server configuration
 866 ~~~~~~~~~~~~~~~~~~~~
 867
 868 Two servers are required for the tests, SUT and DUT.
 869
 870 Make sure the user from the SUT can ssh to the DUT without entering the password.
 871 To enable this feature keys must be setup on the DUT.
 872
 873 ``ssh-keygen`` will make a private & public key pair on the SUT.
 874
 875 ``ssh-copy-id`` <user name>@<target host name> on the SUT will copy the public
 876 key to the DUT. It will ask for credentials so that it can upload the public key.
 877
 878 The SUT and DUT are connected through at least 2 NIC ports.
 879
 880 One NIC port is expected to be managed by linux on both machines and will be
 881 used as a control path.
 882
 883 The second NIC port (test-port) should be bound to DPDK on the SUT, and should
 884 be managed by linux on the DUT.
 885
 886 The script starts ``ipsec-secgw`` with 2 NIC devices: ``test-port`` and
 887 ``tap vdev``.
 888
 889 It then configures the local tap interface and the remote interface and IPsec
 890 policies in the following way:
 891
 892 Traffic going over the test-port in both directions has to be protected by IPsec.
 893
 894 Traffic going over the TAP port in both directions does not have to be protected.
 895
 896 i.e:
 897
 898 DUT OS(NIC1)--(IPsec)-->(NIC1)ipsec-secgw(TAP)--(plain)-->(TAP)SUT OS
 899
 900 SUT OS(TAP)--(plain)-->(TAP)psec-secgw(NIC1)--(IPsec)-->(NIC1)DUT OS
 901
 902 It then tries to perform some data transfer using the scheme described above.
 903
 904 usage
 905 ~~~~~
 906
 907 In the ipsec-secgw/test directory
 908
 909 to run one test for IPv4 or IPv6
 910
 911 /bin/bash linux_test(4|6).sh <ipsec_mode>
 912
 913 to run all tests for IPv4 or IPv6
 914
 915 /bin/bash run_test.sh -4|-6
 916
 917 For the list of available modes please refer to run_test.sh.