1.. BSD LICENSE 2 Copyright(c) 2016 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 Constraints bellow) 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 classify the ports between Protected and Unprotected. 52Thus, traffic received in an Unprotected or Protected port is consider 53Inbound or Outbound respectively. 54 55Path for IPsec Inbound traffic: 56 57* Read packets from the port 58* Classify packets between IPv4 and ESP. 59* Inbound SA lookup for ESP packets based on their SPI 60* Verification/Decryption 61* Removal of ESP and outer IP header 62* Inbound SP check using ACL of decrypted packets and any other IPv4 packet 63 we read. 64* Routing 65* Write packet to port 66 67Path for IPsec Outbound traffic: 68 69* Read packets from the port 70* Outbound SP check using ACL of all IPv4 traffic 71* Outbound SA lookup for packets that need IPsec protection 72* Add ESP and outter IP header 73* Encryption/Digest 74* Routing 75* Write packet to port 76 77Constraints 78----------- 79* IPv4 traffic 80* ESP tunnel mode 81* EAS-CBC, HMAC-SHA1 and NULL 82* Each SA must be handle by a unique lcore (1 RX queue per port) 83* No chained mbufs 84 85Compiling the Application 86------------------------- 87 88To compile the application: 89 90#. Go to the sample application directory: 91 92 .. code-block:: console 93 94 export RTE_SDK=/path/to/rte_sdk 95 cd ${RTE_SDK}/examples/ipsec-secgw 96 97#. Set the target (a default target is used if not specified). For example: 98 99 .. code-block:: console 100 101 export RTE_TARGET=x86_64-native-linuxapp-gcc 102 103 See the *DPDK Getting Started Guide* for possible RTE_TARGET values. 104 105#. Build the application: 106 107 .. code-block:: console 108 109 make 110 111Running the Application 112----------------------- 113 114The application has a number of command line options: 115 116.. code-block:: console 117 118 ./build/ipsec-secgw [EAL options] -- -p PORTMASK -P -u PORTMASK --config 119 (port,queue,lcore)[,(port,queue,lcore] --single-sa SAIDX --ep0|--ep1 120 121where, 122 123* -p PORTMASK: Hexadecimal bitmask of ports to configure 124 125* -P: optional, sets all ports to promiscuous mode so that packets are 126 accepted regardless of the packet's Ethernet MAC destination address. 127 Without this option, only packets with the Ethernet MAC destination address 128 set to the Ethernet address of the port are accepted (default is enabled). 129 130* -u PORTMASK: hexadecimal bitmask of unprotected ports 131 132* --config (port,queue,lcore)[,(port,queue,lcore)]: determines which queues 133 from which ports are mapped to which cores 134 135* --single-sa SAIDX: use a single SA for outbound traffic, bypassing the SP 136 on both Inbound and Outbound. This option is meant for debugging/performance 137 purposes. 138 139* --ep0: configure the app as Endpoint 0. 140 141* --ep1: configure the app as Endpoint 1. 142 143Either one of --ep0 or --ep1 *must* be specified. 144The main purpose of these options is two easily configure two systems 145back-to-back that would forward traffic through an IPsec tunnel. 146 147The mapping of lcores to port/queues is similar to other l3fwd applications. 148 149For example, given the following command line: 150 151.. code-block:: console 152 153 ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 154 --vdev "cryptodev_null_pmd" -- -p 0xf -P -u 0x3 155 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" --ep0 156 157where each options means: 158 159* The -l option enables cores 20 and 21 160 161* The -n option sets memory 4 channels 162 163* The --socket-mem to use 2GB on socket 1 164 165* The --vdev "cryptodev_null_pmd" option creates virtual NULL cryptodev PMD 166 167* The -p option enables ports (detected) 0, 1, 2 and 3 168 169* The -P option enables promiscuous mode 170 171* The -u option sets ports 1 and 2 as unprotected, leaving 2 and 3 as protected 172 173* The --config option enables one queue per port with the following mapping: 174 175+----------+-----------+-----------+---------------------------------------+ 176| **Port** | **Queue** | **lcore** | **Description** | 177| | | | | 178+----------+-----------+-----------+---------------------------------------+ 179| 0 | 0 | 20 | Map queue 0 from port 0 to lcore 20. | 180| | | | | 181+----------+-----------+-----------+---------------------------------------+ 182| 1 | 0 | 20 | Map queue 0 from port 1 to lcore 20. | 183| | | | | 184+----------+-----------+-----------+---------------------------------------+ 185| 2 | 0 | 21 | Map queue 0 from port 2 to lcore 21. | 186| | | | | 187+----------+-----------+-----------+---------------------------------------+ 188| 3 | 0 | 21 | Map queue 0 from port 3 to lcore 21. | 189| | | | | 190+----------+-----------+-----------+---------------------------------------+ 191 192* The --ep0 options configures the app with a given set of SP, SA and Routing 193 entries as explained below in more detail. 194 195Refer to the *DPDK Getting Started Guide* for general information on running 196applications and the Environment Abstraction Layer (EAL) options. 197 198The application would do a best effort to "map" crypto devices to cores, with 199hardware devices having priority. 200This means that if the application is using a single core and both hardware 201and software crypto devices are detected, hardware devices will be used. 202 203A way to achive the case where you want to force the use of virtual crypto 204devices is to whitelist the ethernet devices needed and therefore implicitely 205blacklisting all hardware crypto devices. 206 207For example, something like the following command line: 208 209.. code-block:: console 210 211 ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 212 -w 81:00.0 -w 81:00.1 -w 81:00.2 -w 81:00.3 213 --vdev "cryptodev_aesni_mb_pmd" --vdev "cryptodev_null_pmd" -- 214 -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" 215 --ep0 216 217Configurations 218-------------- 219 220The following sections provide some details on the default values used to 221initialize the SP, SA and Routing tables. 222Currently all the configuration is hard coded into the application. 223 224Security Policy Initialization 225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 226 227As mention in the overview, the Security Policies are ACL rules. 228The application defines two ACLs, one each of Inbound and Outbound, and 229it replicates them per socket in use. 230 231Following are the default rules: 232 233Endpoint 0 Outbound Security Policies: 234 235+---------+------------------+-----------+------------+ 236| **Src** | **Dst** | **proto** | **SA idx** | 237| | | | | 238+---------+------------------+-----------+------------+ 239| Any | 192.168.105.0/24 | Any | 5 | 240| | | | | 241+---------+------------------+-----------+------------+ 242| Any | 192.168.106.0/24 | Any | 6 | 243| | | | | 244+---------+------------------+-----------+------------+ 245| Any | 192.168.107.0/24 | Any | 7 | 246| | | | | 247+---------+------------------+-----------+------------+ 248| Any | 192.168.108.0/24 | Any | 8 | 249| | | | | 250+---------+------------------+-----------+------------+ 251| Any | 192.168.200.0/24 | Any | 9 | 252| | | | | 253+---------+------------------+-----------+------------+ 254| Any | 192.168.250.0/24 | Any | BYPASS | 255| | | | | 256+---------+------------------+-----------+------------+ 257 258Endpoint 0 Inbound Security Policies: 259 260+---------+------------------+-----------+------------+ 261| **Src** | **Dst** | **proto** | **SA idx** | 262| | | | | 263+---------+------------------+-----------+------------+ 264| Any | 192.168.115.0/24 | Any | 5 | 265| | | | | 266+---------+------------------+-----------+------------+ 267| Any | 192.168.116.0/24 | Any | 6 | 268| | | | | 269+---------+------------------+-----------+------------+ 270| Any | 192.168.117.0/24 | Any | 7 | 271| | | | | 272+---------+------------------+-----------+------------+ 273| Any | 192.168.118.0/24 | Any | 8 | 274| | | | | 275+---------+------------------+-----------+------------+ 276| Any | 192.168.210.0/24 | Any | 9 | 277| | | | | 278+---------+------------------+-----------+------------+ 279| Any | 192.168.240.0/24 | Any | BYPASS | 280| | | | | 281+---------+------------------+-----------+------------+ 282 283Endpoint 1 Outbound Security Policies: 284 285+---------+------------------+-----------+------------+ 286| **Src** | **Dst** | **proto** | **SA idx** | 287| | | | | 288+---------+------------------+-----------+------------+ 289| Any | 192.168.115.0/24 | Any | 5 | 290| | | | | 291+---------+------------------+-----------+------------+ 292| Any | 192.168.116.0/24 | Any | 6 | 293| | | | | 294+---------+------------------+-----------+------------+ 295| Any | 192.168.117.0/24 | Any | 7 | 296| | | | | 297+---------+------------------+-----------+------------+ 298| Any | 192.168.118.0/24 | Any | 8 | 299| | | | | 300+---------+------------------+-----------+------------+ 301| Any | 192.168.210.0/24 | Any | 9 | 302| | | | | 303+---------+------------------+-----------+------------+ 304| Any | 192.168.240.0/24 | Any | BYPASS | 305| | | | | 306+---------+------------------+-----------+------------+ 307 308Endpoint 1 Inbound Security Policies: 309 310+---------+------------------+-----------+------------+ 311| **Src** | **Dst** | **proto** | **SA idx** | 312| | | | | 313+---------+------------------+-----------+------------+ 314| Any | 192.168.105.0/24 | Any | 5 | 315| | | | | 316+---------+------------------+-----------+------------+ 317| Any | 192.168.106.0/24 | Any | 6 | 318| | | | | 319+---------+------------------+-----------+------------+ 320| Any | 192.168.107.0/24 | Any | 7 | 321| | | | | 322+---------+------------------+-----------+------------+ 323| Any | 192.168.108.0/24 | Any | 8 | 324| | | | | 325+---------+------------------+-----------+------------+ 326| Any | 192.168.200.0/24 | Any | 9 | 327| | | | | 328+---------+------------------+-----------+------------+ 329| Any | 192.168.250.0/24 | Any | BYPASS | 330| | | | | 331+---------+------------------+-----------+------------+ 332 333 334Security Association Initialization 335~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 336 337The SAs are kept in a array table. 338 339For Inbound, the SPI is used as index module the table size. 340This means that on a table for 100 SA, SPI 5 and 105 would use the same index 341and that is not currently supported. 342 343Notice that it is not an issue for Outbound traffic as we store the index and 344not the SPI in the Security Policy. 345 346All SAs configured with AES-CBC and HMAC-SHA1 share the same values for cipher 347block size and key, and authentication digest size and key. 348 349Following are the default values: 350 351Endpoint 0 Outbound Security Associations: 352 353+---------+------------+-----------+----------------+------------------+ 354| **SPI** | **Cipher** | **Auth** | **Tunnel src** | **Tunnel dst** | 355| | | | | | 356+---------+------------+-----------+----------------+------------------+ 357| 5 | AES-CBC | HMAC-SHA1 | 172.16.1.5 | 172.16.2.5 | 358| | | | | | 359+---------+------------+-----------+----------------+------------------+ 360| 6 | AES-CBC | HMAC-SHA1 | 172.16.1.6 | 172.16.2.6 | 361| | | | | | 362+---------+------------+-----------+----------------+------------------+ 363| 7 | AES-CBC | HMAC-SHA1 | 172.16.1.7 | 172.16.2.7 | 364| | | | | | 365+---------+------------+-----------+----------------+------------------+ 366| 8 | AES-CBC | HMAC-SHA1 | 172.16.1.8 | 172.16.2.8 | 367| | | | | | 368+---------+------------+-----------+----------------+------------------+ 369| 9 | NULL | NULL | 172.16.1.5 | 172.16.2.5 | 370| | | | | | 371+---------+------------+-----------+----------------+------------------+ 372 373Endpoint 0 Inbound Security Associations: 374 375+---------+------------+-----------+----------------+------------------+ 376| **SPI** | **Cipher** | **Auth** | **Tunnel src** | **Tunnel dst** | 377| | | | | | 378+---------+------------+-----------+----------------+------------------+ 379| 5 | AES-CBC | HMAC-SHA1 | 172.16.2.5 | 172.16.1.5 | 380| | | | | | 381+---------+------------+-----------+----------------+------------------+ 382| 6 | AES-CBC | HMAC-SHA1 | 172.16.2.6 | 172.16.1.6 | 383| | | | | | 384+---------+------------+-----------+----------------+------------------+ 385| 7 | AES-CBC | HMAC-SHA1 | 172.16.2.7 | 172.16.1.7 | 386| | | | | | 387+---------+------------+-----------+----------------+------------------+ 388| 8 | AES-CBC | HMAC-SHA1 | 172.16.2.8 | 172.16.1.8 | 389| | | | | | 390+---------+------------+-----------+----------------+------------------+ 391| 9 | NULL | NULL | 172.16.2.5 | 172.16.1.5 | 392| | | | | | 393+---------+------------+-----------+----------------+------------------+ 394 395Endpoint 1 Outbound Security Associations: 396 397+---------+------------+-----------+----------------+------------------+ 398| **SPI** | **Cipher** | **Auth** | **Tunnel src** | **Tunnel dst** | 399| | | | | | 400+---------+------------+-----------+----------------+------------------+ 401| 5 | AES-CBC | HMAC-SHA1 | 172.16.2.5 | 172.16.1.5 | 402| | | | | | 403+---------+------------+-----------+----------------+------------------+ 404| 6 | AES-CBC | HMAC-SHA1 | 172.16.2.6 | 172.16.1.6 | 405| | | | | | 406+---------+------------+-----------+----------------+------------------+ 407| 7 | AES-CBC | HMAC-SHA1 | 172.16.2.7 | 172.16.1.7 | 408| | | | | | 409+---------+------------+-----------+----------------+------------------+ 410| 8 | AES-CBC | HMAC-SHA1 | 172.16.2.8 | 172.16.1.8 | 411| | | | | | 412+---------+------------+-----------+----------------+------------------+ 413| 9 | NULL | NULL | 172.16.2.5 | 172.16.1.5 | 414| | | | | | 415+---------+------------+-----------+----------------+------------------+ 416 417Endpoint 1 Inbound Security Associations: 418 419+---------+------------+-----------+----------------+------------------+ 420| **SPI** | **Cipher** | **Auth** | **Tunnel src** | **Tunnel dst** | 421| | | | | | 422+---------+------------+-----------+----------------+------------------+ 423| 5 | AES-CBC | HMAC-SHA1 | 172.16.1.5 | 172.16.2.5 | 424| | | | | | 425+---------+------------+-----------+----------------+------------------+ 426| 6 | AES-CBC | HMAC-SHA1 | 172.16.1.6 | 172.16.2.6 | 427| | | | | | 428+---------+------------+-----------+----------------+------------------+ 429| 7 | AES-CBC | HMAC-SHA1 | 172.16.1.7 | 172.16.2.7 | 430| | | | | | 431+---------+------------+-----------+----------------+------------------+ 432| 8 | AES-CBC | HMAC-SHA1 | 172.16.1.8 | 172.16.2.8 | 433| | | | | | 434+---------+------------+-----------+----------------+------------------+ 435| 9 | NULL | NULL | 172.16.1.5 | 172.16.2.5 | 436| | | | | | 437+---------+------------+-----------+----------------+------------------+ 438 439Routing Initialization 440~~~~~~~~~~~~~~~~~~~~~~ 441 442The Routing is implemented using LPM table. 443 444Following default values: 445 446Endpoint 0 Routing Table: 447 448+------------------+----------+ 449| **Dst addr** | **Port** | 450| | | 451+------------------+----------+ 452| 172.16.2.5/32 | 0 | 453| | | 454+------------------+----------+ 455| 172.16.2.6/32 | 0 | 456| | | 457+------------------+----------+ 458| 172.16.2.7/32 | 1 | 459| | | 460+------------------+----------+ 461| 172.16.2.8/32 | 1 | 462| | | 463+------------------+----------+ 464| 192.168.115.0/24 | 2 | 465| | | 466+------------------+----------+ 467| 192.168.116.0/24 | 2 | 468| | | 469+------------------+----------+ 470| 192.168.117.0/24 | 3 | 471| | | 472+------------------+----------+ 473| 192.168.118.0/24 | 3 | 474| | | 475+------------------+----------+ 476| 192.168.210.0/24 | 2 | 477| | | 478+------------------+----------+ 479| 192.168.240.0/24 | 2 | 480| | | 481+------------------+----------+ 482| 192.168.250.0/24 | 0 | 483| | | 484+------------------+----------+ 485 486Endpoint 1 Routing Table: 487 488+------------------+----------+ 489| **Dst addr** | **Port** | 490| | | 491+------------------+----------+ 492| 172.16.1.5/32 | 2 | 493| | | 494+------------------+----------+ 495| 172.16.1.6/32 | 2 | 496| | | 497+------------------+----------+ 498| 172.16.1.7/32 | 3 | 499| | | 500+------------------+----------+ 501| 172.16.1.8/32 | 3 | 502| | | 503+------------------+----------+ 504| 192.168.105.0/24 | 0 | 505| | | 506+------------------+----------+ 507| 192.168.106.0/24 | 0 | 508| | | 509+------------------+----------+ 510| 192.168.107.0/24 | 1 | 511| | | 512+------------------+----------+ 513| 192.168.108.0/24 | 1 | 514| | | 515+------------------+----------+ 516| 192.168.200.0/24 | 0 | 517| | | 518+------------------+----------+ 519| 192.168.240.0/24 | 2 | 520| | | 521+------------------+----------+ 522| 192.168.250.0/24 | 0 | 523| | | 524+------------------+----------+ 525