1.. BSD LICENSE 2 Copyright(c) 2016-2017 Intel Corporation. All rights reserved. 3 All rights reserved. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions 7 are met: 8 9 * Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 * Redistributions in binary form must reproduce the above copyright 12 notice, this list of conditions and the following disclaimer in 13 the documentation and/or other materials provided with the 14 distribution. 15 * Neither the name of Intel Corporation nor the names of its 16 contributors may be used to endorse or promote products derived 17 from this software without specific prior written permission. 18 19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31IPsec Security Gateway Sample Application 32========================================= 33 34The IPsec Security Gateway application is an example of a "real world" 35application using DPDK cryptodev framework. 36 37Overview 38-------- 39 40The application demonstrates the implementation of a Security Gateway 41(not IPsec compliant, see the Constraints section below) using DPDK based on RFC4301, 42RFC4303, RFC3602 and RFC2404. 43 44Internet Key Exchange (IKE) is not implemented, so only manual setting of 45Security Policies and Security Associations is supported. 46 47The Security Policies (SP) are implemented as ACL rules, the Security 48Associations (SA) are stored in a table and the routing is implemented 49using LPM. 50 51The application classifies the ports as *Protected* and *Unprotected*. 52Thus, traffic received on an Unprotected or Protected port is consider 53Inbound or Outbound respectively. 54 55The application also supports complete IPSec protocol offload to hardware 56(Look aside crypto accelarator or using ethernet device). It also support 57inline ipsec processing by the supported ethernet device during transmission. 58These modes can be selected during the SA creation configuration. 59 60In case of complete protocol offload, the processing of headers(ESP and outer 61IP header) is done by the hardware and the application does not need to 62add/remove them during outbound/inbound processing. 63 64For inline offloaded outbound traffic, the application will not do the LPM 65lookup for routing, as the port on which the packet has to be forwarded will be 66part of the SA. Security parameters will be configured on that port only, and 67sending the packet on other ports could result in unencrypted packets being 68sent out. 69 70The Path for IPsec Inbound traffic is: 71 72* Read packets from the port. 73* Classify packets between IPv4 and ESP. 74* Perform Inbound SA lookup for ESP packets based on their SPI. 75* Perform Verification/Decryption (Not needed in case of inline ipsec). 76* Remove ESP and outer IP header (Not needed in case of protocol offload). 77* Inbound SP check using ACL of decrypted packets and any other IPv4 packets. 78* Routing. 79* Write packet to port. 80 81The Path for the IPsec Outbound traffic is: 82 83* Read packets from the port. 84* Perform Outbound SP check using ACL of all IPv4 traffic. 85* Perform Outbound SA lookup for packets that need IPsec protection. 86* Add ESP and outer IP header (Not needed in case protocol offload). 87* Perform Encryption/Digest (Not needed in case of inline ipsec). 88* Routing. 89* Write packet to port. 90 91 92Constraints 93----------- 94 95* No IPv6 options headers. 96* No AH mode. 97* Supported algorithms: AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1 and NULL. 98* Each SA must be handle by a unique lcore (*1 RX queue per port*). 99* No chained mbufs. 100 101Compiling the Application 102------------------------- 103 104To compile the sample application see :doc:`compiling`. 105 106The application is located in the ``rpsec-secgw`` sub-directory. 107 108#. [Optional] Build the application for debugging: 109 This option adds some extra flags, disables compiler optimizations and 110 is verbose:: 111 112 make DEBUG=1 113 114 115Running the Application 116----------------------- 117 118The application has a number of command line options:: 119 120 121 ./build/ipsec-secgw [EAL options] -- 122 -p PORTMASK -P -u PORTMASK -j FRAMESIZE 123 --config (port,queue,lcore)[,(port,queue,lcore] 124 --single-sa SAIDX 125 -f CONFIG_FILE_PATH 126 127Where: 128 129* ``-p PORTMASK``: Hexadecimal bitmask of ports to configure. 130 131* ``-P``: *optional*. Sets all ports to promiscuous mode so that packets are 132 accepted regardless of the packet's Ethernet MAC destination address. 133 Without this option, only packets with the Ethernet MAC destination address 134 set to the Ethernet address of the port are accepted (default is enabled). 135 136* ``-u PORTMASK``: hexadecimal bitmask of unprotected ports 137 138* ``-j FRAMESIZE``: *optional*. Enables jumbo frames with the maximum size 139 specified as FRAMESIZE. If an invalid value is provided as FRAMESIZE 140 then the default value 9000 is used. 141 142* ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues 143 from which ports are mapped to which cores. 144 145* ``--single-sa SAIDX``: use a single SA for outbound traffic, bypassing the SP 146 on both Inbound and Outbound. This option is meant for debugging/performance 147 purposes. 148 149* ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all 150 configuration items for running the application (See Configuration file 151 syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified. 152 **ONLY** the UNIX format configuration file is accepted. 153 154 155The mapping of lcores to port/queues is similar to other l3fwd applications. 156 157For example, given the following command line:: 158 159 ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ 160 --vdev "crypto_null" -- -p 0xf -P -u 0x3 \ 161 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ 162 -f /path/to/config_file \ 163 164where each options means: 165 166* The ``-l`` option enables cores 20 and 21. 167 168* The ``-n`` option sets memory 4 channels. 169 170* The ``--socket-mem`` to use 2GB on socket 1. 171 172* The ``--vdev "crypto_null"`` option creates virtual NULL cryptodev PMD. 173 174* The ``-p`` option enables ports (detected) 0, 1, 2 and 3. 175 176* The ``-P`` option enables promiscuous mode. 177 178* The ``-u`` option sets ports 1 and 2 as unprotected, leaving 2 and 3 as protected. 179 180* The ``--config`` option enables one queue per port with the following mapping: 181 182 +----------+-----------+-----------+---------------------------------------+ 183 | **Port** | **Queue** | **lcore** | **Description** | 184 | | | | | 185 +----------+-----------+-----------+---------------------------------------+ 186 | 0 | 0 | 20 | Map queue 0 from port 0 to lcore 20. | 187 | | | | | 188 +----------+-----------+-----------+---------------------------------------+ 189 | 1 | 0 | 20 | Map queue 0 from port 1 to lcore 20. | 190 | | | | | 191 +----------+-----------+-----------+---------------------------------------+ 192 | 2 | 0 | 21 | Map queue 0 from port 2 to lcore 21. | 193 | | | | | 194 +----------+-----------+-----------+---------------------------------------+ 195 | 3 | 0 | 21 | Map queue 0 from port 3 to lcore 21. | 196 | | | | | 197 +----------+-----------+-----------+---------------------------------------+ 198 199* The ``-f /path/to/config_file`` option enables the application read and 200 parse the configuration file specified, and configures the application 201 with a given set of SP, SA and Routing entries accordingly. The syntax of 202 the configuration file will be explained below in more detail. Please 203 **note** the parser only accepts UNIX format text file. Other formats 204 such as DOS/MAC format will cause a parse error. 205 206Refer to the *DPDK Getting Started Guide* for general information on running 207applications and the Environment Abstraction Layer (EAL) options. 208 209The application would do a best effort to "map" crypto devices to cores, with 210hardware devices having priority. Basically, hardware devices if present would 211be assigned to a core before software ones. 212This means that if the application is using a single core and both hardware 213and software crypto devices are detected, hardware devices will be used. 214 215A way to achieve the case where you want to force the use of virtual crypto 216devices is to whitelist the Ethernet devices needed and therefore implicitly 217blacklisting all hardware crypto devices. 218 219For example, something like the following command line: 220 221.. code-block:: console 222 223 ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ 224 -w 81:00.0 -w 81:00.1 -w 81:00.2 -w 81:00.3 \ 225 --vdev "crypto_aesni_mb" --vdev "crypto_null" \ 226 -- \ 227 -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ 228 -f sample.cfg 229 230 231Configurations 232-------------- 233 234The following sections provide the syntax of configurations to initialize 235your SP, SA and Routing tables. 236Configurations shall be specified in the configuration file to be passed to 237the application. The file is then parsed by the application. The successful 238parsing will result in the appropriate rules being applied to the tables 239accordingly. 240 241 242Configuration File Syntax 243~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 244 245As mention in the overview, the Security Policies are ACL rules. 246The application parsers the rules specified in the configuration file and 247passes them to the ACL table, and replicates them per socket in use. 248 249Following are the configuration file syntax. 250 251General rule syntax 252^^^^^^^^^^^^^^^^^^^ 253 254The parse treats one line in the configuration file as one configuration 255item (unless the line concatenation symbol exists). Every configuration 256item shall follow the syntax of either SP, SA, or Routing rules specified 257below. 258 259The configuration parser supports the following special symbols: 260 261 * Comment symbol **#**. Any character from this symbol to the end of 262 line is treated as comment and will not be parsed. 263 264 * Line concatenation symbol **\\**. This symbol shall be placed in the end 265 of the line to be concatenated to the line below. Multiple lines' 266 concatenation is supported. 267 268 269SP rule syntax 270^^^^^^^^^^^^^^ 271 272The SP rule syntax is shown as follows: 273 274.. code-block:: console 275 276 sp <ip_ver> <dir> esp <action> <priority> <src_ip> <dst_ip> 277 <proto> <sport> <dport> 278 279 280where each options means: 281 282``<ip_ver>`` 283 284 * IP protocol version 285 286 * Optional: No 287 288 * Available options: 289 290 * *ipv4*: IP protocol version 4 291 * *ipv6*: IP protocol version 6 292 293``<dir>`` 294 295 * The traffic direction 296 297 * Optional: No 298 299 * Available options: 300 301 * *in*: inbound traffic 302 * *out*: outbound traffic 303 304``<action>`` 305 306 * IPsec action 307 308 * Optional: No 309 310 * Available options: 311 312 * *protect <SA_idx>*: the specified traffic is protected by SA rule 313 with id SA_idx 314 * *bypass*: the specified traffic traffic is bypassed 315 * *discard*: the specified traffic is discarded 316 317``<priority>`` 318 319 * Rule priority 320 321 * Optional: Yes, default priority 0 will be used 322 323 * Syntax: *pri <id>* 324 325``<src_ip>`` 326 327 * The source IP address and mask 328 329 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used 330 331 * Syntax: 332 333 * *src X.X.X.X/Y* for IPv4 334 * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 335 336``<dst_ip>`` 337 338 * The destination IP address and mask 339 340 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used 341 342 * Syntax: 343 344 * *dst X.X.X.X/Y* for IPv4 345 * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 346 347``<proto>`` 348 349 * The protocol start and end range 350 351 * Optional: yes, default range of 0 to 0 will be used 352 353 * Syntax: *proto X:Y* 354 355``<sport>`` 356 357 * The source port start and end range 358 359 * Optional: yes, default range of 0 to 0 will be used 360 361 * Syntax: *sport X:Y* 362 363``<dport>`` 364 365 * The destination port start and end range 366 367 * Optional: yes, default range of 0 to 0 will be used 368 369 * Syntax: *dport X:Y* 370 371Example SP rules: 372 373.. code-block:: console 374 375 sp ipv4 out esp protect 105 pri 1 dst 192.168.115.0/24 sport 0:65535 \ 376 dport 0:65535 377 378 sp ipv6 in esp bypass pri 1 dst 0000:0000:0000:0000:5555:5555:\ 379 0000:0000/96 sport 0:65535 dport 0:65535 380 381 382SA rule syntax 383^^^^^^^^^^^^^^ 384 385The successfully parsed SA rules will be stored in an array table. 386 387The SA rule syntax is shown as follows: 388 389.. code-block:: console 390 391 sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key> 392 <mode> <src_ip> <dst_ip> <action_type> <port_id> 393 394where each options means: 395 396``<dir>`` 397 398 * The traffic direction 399 400 * Optional: No 401 402 * Available options: 403 404 * *in*: inbound traffic 405 * *out*: outbound traffic 406 407``<spi>`` 408 409 * The SPI number 410 411 * Optional: No 412 413 * Syntax: unsigned integer number 414 415``<cipher_algo>`` 416 417 * Cipher algorithm 418 419 * Optional: Yes, unless <aead_algo> is not used 420 421 * Available options: 422 423 * *null*: NULL algorithm 424 * *aes-128-cbc*: AES-CBC 128-bit algorithm 425 * *aes-128-ctr*: AES-CTR 128-bit algorithm 426 427 * Syntax: *cipher_algo <your algorithm>* 428 429``<cipher_key>`` 430 431 * Cipher key, NOT available when 'null' algorithm is used 432 433 * Optional: Yes, unless <aead_algo> is not used. 434 Must be followed by <cipher_algo> option 435 436 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. 437 The number of bytes should be as same as the specified cipher algorithm 438 key size. 439 440 For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: 441 A1:B2:C3:D4* 442 443``<auth_algo>`` 444 445 * Authentication algorithm 446 447 * Optional: Yes, unless <aead_algo> is not used 448 449 * Available options: 450 451 * *null*: NULL algorithm 452 * *sha1-hmac*: HMAC SHA1 algorithm 453 454``<auth_key>`` 455 456 * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm 457 is used. 458 459 * Optional: Yes, unless <aead_algo> is not used. 460 Must be followed by <auth_algo> option 461 462 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. 463 The number of bytes should be as same as the specified authentication 464 algorithm key size. 465 466 For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: 467 A1:B2:C3:D4* 468 469``<aead_algo>`` 470 471 * AEAD algorithm 472 473 * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used 474 475 * Available options: 476 477 * *aes-128-gcm*: AES-GCM 128-bit algorithm 478 479 * Syntax: *cipher_algo <your algorithm>* 480 481``<aead_key>`` 482 483 * Cipher key, NOT available when 'null' algorithm is used 484 485 * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used. 486 Must be followed by <aead_algo> option 487 488 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. 489 The number of bytes should be as same as the specified AEAD algorithm 490 key size. 491 492 For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: 493 A1:B2:C3:D4* 494 495``<mode>`` 496 497 * The operation mode 498 499 * Optional: No 500 501 * Available options: 502 503 * *ipv4-tunnel*: Tunnel mode for IPv4 packets 504 * *ipv6-tunnel*: Tunnel mode for IPv6 packets 505 * *transport*: transport mode 506 507 * Syntax: mode XXX 508 509``<src_ip>`` 510 511 * The source IP address. This option is not available when 512 transport mode is used 513 514 * Optional: Yes, default address 0.0.0.0 will be used 515 516 * Syntax: 517 518 * *src X.X.X.X* for IPv4 519 * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 520 521``<dst_ip>`` 522 523 * The destination IP address. This option is not available when 524 transport mode is used 525 526 * Optional: Yes, default address 0.0.0.0 will be used 527 528 * Syntax: 529 530 * *dst X.X.X.X* for IPv4 531 * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 532 533``<type>`` 534 535 * Action type to specify the security action. This option specify 536 the SA to be performed with look aside protocol offload to HW 537 accelerator or protocol offload on ethernet device or inline 538 crypto processing on the ethernet device during transmission. 539 540 * Optional: Yes, default type *no-offload* 541 542 * Available options: 543 544 * *lookaside-protocol-offload*: look aside protocol offload to HW accelerator 545 * *inline-protocol-offload*: inline protocol offload on ethernet device 546 * *inline-crypto-offload*: inline crypto processing on ethernet device 547 * *no-offload*: no offloading to hardware 548 549 ``<port_id>`` 550 551 * Port/device ID of the ethernet/crypto accelerator for which the SA is 552 configured. For *inline-crypto-offload* and *inline-protocol-offload*, this 553 port will be used for routing. The routing table will not be referred in 554 this case. 555 556 * Optional: No, if *type* is not *no-offload* 557 558 * Syntax: 559 560 * *port_id X* X is a valid device number in decimal 561 562 563Example SA rules: 564 565.. code-block:: console 566 567 sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \ 568 src 172.16.1.5 dst 172.16.2.5 569 570 sa out 25 cipher_algo aes-128-cbc \ 571 cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ 572 auth_algo sha1-hmac \ 573 auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ 574 mode ipv6-tunnel \ 575 src 1111:1111:1111:1111:1111:1111:1111:5555 \ 576 dst 2222:2222:2222:2222:2222:2222:2222:5555 577 578 sa in 105 aead_algo aes-128-gcm \ 579 aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \ 580 mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 581 582 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 \ 583 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 \ 584 mode ipv4-tunnel src 172.16.1.5 dst 172.16.2.5 \ 585 type lookaside-protocol-offload port_id 4 586 587Routing rule syntax 588^^^^^^^^^^^^^^^^^^^ 589 590The Routing rule syntax is shown as follows: 591 592.. code-block:: console 593 594 rt <ip_ver> <src_ip> <dst_ip> <port> 595 596 597where each options means: 598 599``<ip_ver>`` 600 601 * IP protocol version 602 603 * Optional: No 604 605 * Available options: 606 607 * *ipv4*: IP protocol version 4 608 * *ipv6*: IP protocol version 6 609 610``<src_ip>`` 611 612 * The source IP address and mask 613 614 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used 615 616 * Syntax: 617 618 * *src X.X.X.X/Y* for IPv4 619 * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 620 621``<dst_ip>`` 622 623 * The destination IP address and mask 624 625 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used 626 627 * Syntax: 628 629 * *dst X.X.X.X/Y* for IPv4 630 * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 631 632``<port>`` 633 634 * The traffic output port id 635 636 * Optional: yes, default output port 0 will be used 637 638 * Syntax: *port X* 639 640Example SP rules: 641 642.. code-block:: console 643 644 rt ipv4 dst 172.16.1.5/32 port 0 645 646 rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0 647