2 Copyright(c) 2016 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
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
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.
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.
31 IPsec Security Gateway Sample Application
32 =========================================
34 The IPsec Security Gateway application is an example of a "real world"
35 application using DPDK cryptodev framework.
40 The application demonstrates the implementation of a Security Gateway
41 (not IPsec compliant, see the Constraints section below) using DPDK based on RFC4301,
42 RFC4303, RFC3602 and RFC2404.
44 Internet Key Exchange (IKE) is not implemented, so only manual setting of
45 Security Policies and Security Associations is supported.
47 The Security Policies (SP) are implemented as ACL rules, the Security
48 Associations (SA) are stored in a table and the routing is implemented
51 The application classifies the ports as *Protected* and *Unprotected*.
52 Thus, traffic received on an Unprotected or Protected port is consider
53 Inbound or Outbound respectively.
55 The Path for IPsec Inbound traffic is:
57 * Read packets from the port.
58 * Classify packets between IPv4 and ESP.
59 * Perform Inbound SA lookup for ESP packets based on their SPI.
60 * Perform Verification/Decryption.
61 * Remove ESP and outer IP header
62 * Inbound SP check using ACL of decrypted packets and any other IPv4 packets.
64 * Write packet to port.
66 The Path for the IPsec Outbound traffic is:
68 * Read packets from the port.
69 * Perform Outbound SP check using ACL of all IPv4 traffic.
70 * Perform Outbound SA lookup for packets that need IPsec protection.
71 * Add ESP and outer IP header.
72 * Perform Encryption/Digest.
74 * Write packet to port.
80 * No IPv6 options headers.
82 * Supported algorithms: AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1 and NULL.
83 * Each SA must be handle by a unique lcore (*1 RX queue per port*).
87 Compiling the Application
88 -------------------------
90 To compile the application:
92 #. Go to the sample application directory::
94 export RTE_SDK=/path/to/rte_sdk
95 cd ${RTE_SDK}/examples/ipsec-secgw
97 #. Set the target (a default target is used if not specified). For example::
100 export RTE_TARGET=x86_64-native-linuxapp-gcc
102 See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
104 #. Build the application::
108 #. [Optional] Build the application for debugging:
109 This option adds some extra flags, disables compiler optimizations and
115 Running the Application
116 -----------------------
118 The application has a number of command line options::
121 ./build/ipsec-secgw [EAL options] --
122 -p PORTMASK -P -u PORTMASK
123 --config (port,queue,lcore)[,(port,queue,lcore]
129 * ``-p PORTMASK``: Hexadecimal bitmask of ports to configure.
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).
136 * ``-u PORTMASK``: hexadecimal bitmask of unprotected ports
138 * ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues
139 from which ports are mapped to which cores.
141 * ``--single-sa SAIDX``: use a single SA for outbound traffic, bypassing the SP
142 on both Inbound and Outbound. This option is meant for debugging/performance
145 * ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all
146 configuration items for running the application (See Configuration file
147 syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified.
148 **ONLY** the UNIX format configuration file is accepted.
151 The mapping of lcores to port/queues is similar to other l3fwd applications.
153 For example, given the following command line::
155 ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \
156 --vdev "cryptodev_null_pmd" -- -p 0xf -P -u 0x3 \
157 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \
158 -f /path/to/config_file \
160 where each options means:
162 * The ``-l`` option enables cores 20 and 21.
164 * The ``-n`` option sets memory 4 channels.
166 * The ``--socket-mem`` to use 2GB on socket 1.
168 * The ``--vdev "cryptodev_null_pmd"`` option creates virtual NULL cryptodev PMD.
170 * The ``-p`` option enables ports (detected) 0, 1, 2 and 3.
172 * The ``-P`` option enables promiscuous mode.
174 * The ``-u`` option sets ports 1 and 2 as unprotected, leaving 2 and 3 as protected.
176 * The ``--config`` option enables one queue per port with the following mapping:
178 +----------+-----------+-----------+---------------------------------------+
179 | **Port** | **Queue** | **lcore** | **Description** |
181 +----------+-----------+-----------+---------------------------------------+
182 | 0 | 0 | 20 | Map queue 0 from port 0 to lcore 20. |
184 +----------+-----------+-----------+---------------------------------------+
185 | 1 | 0 | 20 | Map queue 0 from port 1 to lcore 20. |
187 +----------+-----------+-----------+---------------------------------------+
188 | 2 | 0 | 21 | Map queue 0 from port 2 to lcore 21. |
190 +----------+-----------+-----------+---------------------------------------+
191 | 3 | 0 | 21 | Map queue 0 from port 3 to lcore 21. |
193 +----------+-----------+-----------+---------------------------------------+
195 * The ``-f /path/to/config_file`` option enables the application read and
196 parse the configuration file specified, and configures the application
197 with a given set of SP, SA and Routing entries accordingly. The syntax of
198 the configuration file will be explained below in more detail. Please
199 **note** the parser only accepts UNIX format text file. Other formats
200 such as DOS/MAC format will cause a parse error.
202 Refer to the *DPDK Getting Started Guide* for general information on running
203 applications and the Environment Abstraction Layer (EAL) options.
205 The application would do a best effort to "map" crypto devices to cores, with
206 hardware devices having priority. Basically, hardware devices if present would
207 be assigned to a core before software ones.
208 This means that if the application is using a single core and both hardware
209 and software crypto devices are detected, hardware devices will be used.
211 A way to achieve the case where you want to force the use of virtual crypto
212 devices is to whitelist the Ethernet devices needed and therefore implicitly
213 blacklisting all hardware crypto devices.
215 For example, something like the following command line:
217 .. code-block:: console
219 ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \
220 -w 81:00.0 -w 81:00.1 -w 81:00.2 -w 81:00.3 \
221 --vdev "cryptodev_aesni_mb_pmd" --vdev "cryptodev_null_pmd" \
223 -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \
230 The following sections provide the syntax of configurations to initialize
231 your SP, SA and Routing tables.
232 Configurations shall be specified in the configuration file to be passed to
233 the application. The file is then parsed by the application. The successful
234 parsing will result in the appropriate rules being applied to the tables
238 Configuration File Syntax
239 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
241 As mention in the overview, the Security Policies are ACL rules.
242 The application parsers the rules specified in the configuration file and
243 passes them to the ACL table, and replicates them per socket in use.
245 Following are the configuration file syntax.
250 The parse treats one line in the configuration file as one configuration
251 item (unless the line concatenation symbol exists). Every configuration
252 item shall follow the syntax of either SP, SA, or Routing rules specified
255 The configuration parser supports the following special symbols:
257 * Comment symbol **#**. Any character from this symbol to the end of
258 line is treated as comment and will not be parsed.
260 * Line concatenation symbol **\\**. This symbol shall be placed in the end
261 of the line to be concatenated to the line below. Multiple lines'
262 concatenation is supported.
268 The SP rule syntax is shown as follows:
270 .. code-block:: console
272 sp <ip_ver> <dir> esp <action> <priority> <src_ip> <dst_ip>
273 <proto> <sport> <dport>
276 where each options means:
280 * IP protocol version
286 * *ipv4*: IP protocol version 4
287 * *ipv6*: IP protocol version 6
291 * The traffic direction
297 * *in*: inbound traffic
298 * *out*: outbound traffic
308 * *protect <SA_idx>*: the specified traffic is protected by SA rule
310 * *bypass*: the specified traffic traffic is bypassed
311 * *discard*: the specified traffic is discarded
317 * Optional: Yes, default priority 0 will be used
323 * The source IP address and mask
325 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
329 * *src X.X.X.X/Y* for IPv4
330 * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
334 * The destination IP address and mask
336 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
340 * *dst X.X.X.X/Y* for IPv4
341 * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
345 * The protocol start and end range
347 * Optional: yes, default range of 0 to 0 will be used
349 * Syntax: *proto X:Y*
353 * The source port start and end range
355 * Optional: yes, default range of 0 to 0 will be used
357 * Syntax: *sport X:Y*
361 * The destination port start and end range
363 * Optional: yes, default range of 0 to 0 will be used
365 * Syntax: *dport X:Y*
369 .. code-block:: console
371 sp ipv4 out esp protect 105 pri 1 dst 192.168.115.0/24 sport 0:65535 \
374 sp ipv6 in esp bypass pri 1 dst 0000:0000:0000:0000:5555:5555:\
375 0000:0000/96 sport 0:65535 dport 0:65535
381 The successfully parsed SA rules will be stored in an array table.
383 The SA rule syntax is shown as follows:
385 .. code-block:: console
387 sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key>
388 <mode> <src_ip> <dst_ip>
390 where each options means:
394 * The traffic direction
400 * *in*: inbound traffic
401 * *out*: outbound traffic
409 * Syntax: unsigned integer number
419 * *null*: NULL algorithm
420 * *aes-128-cbc*: AES-CBC 128-bit algorithm
421 * *aes-128-ctr*: AES-CTR 128-bit algorithm
422 * *aes-128-gcm*: AES-GCM 128-bit algorithm
424 * Syntax: *cipher_algo <your algorithm>*
428 * Cipher key, NOT available when 'null' algorithm is used
430 * Optional: No, must followed by <cipher_algo> option
432 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
433 The number of bytes should be as same as the specified cipher algorithm
436 For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
441 * Authentication algorithm
447 * *null*: NULL algorithm
448 * *sha1-hmac*: HMAC SHA1 algorithm
449 * *aes-128-gcm*: AES-GCM 128-bit algorithm
453 * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm
456 * Optional: No, must followed by <auth_algo> option
458 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
459 The number of bytes should be as same as the specified authentication
462 For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
473 * *ipv4-tunnel*: Tunnel mode for IPv4 packets
474 * *ipv6-tunnel*: Tunnel mode for IPv6 packets
475 * *transport*: transport mode
481 * The source IP address. This option is not available when
482 transport mode is used
484 * Optional: Yes, default address 0.0.0.0 will be used
488 * *src X.X.X.X* for IPv4
489 * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
493 * The destination IP address. This option is not available when
494 transport mode is used
496 * Optional: Yes, default address 0.0.0.0 will be used
500 * *dst X.X.X.X* for IPv4
501 * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
505 .. code-block:: console
507 sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \
508 src 172.16.1.5 dst 172.16.2.5
510 sa out 25 cipher_algo aes-128-cbc \
511 cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
512 auth_algo sha1-hmac \
513 auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
515 src 1111:1111:1111:1111:1111:1111:1111:5555 \
516 dst 2222:2222:2222:2222:2222:2222:2222:5555
518 sa in 105 cipher_algo aes-128-gcm \
519 cipher_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
520 auth_algo aes-128-gcm \
521 mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5
526 The Routing rule syntax is shown as follows:
528 .. code-block:: console
530 rt <ip_ver> <src_ip> <dst_ip> <port>
533 where each options means:
537 * IP protocol version
543 * *ipv4*: IP protocol version 4
544 * *ipv6*: IP protocol version 6
548 * The source IP address and mask
550 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
554 * *src X.X.X.X/Y* for IPv4
555 * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
559 * The destination IP address and mask
561 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
565 * *dst X.X.X.X/Y* for IPv4
566 * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
570 * The traffic output port id
572 * Optional: yes, default output port 0 will be used
578 .. code-block:: console
580 rt ipv4 dst 172.16.1.5/32 port 0
582 rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0