ipsec_secgw.rst revision 97f17497
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 outer 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 achieve the case where you want to force the use of virtual crypto
204devices is to whitelist the Ethernet devices needed and therefore implicitly
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