doc/guides/sample_app_ug/ipsec_secgw.rst

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