86556bd4fa47c42bd0a1fbbcc8527d4f1ab119b1
[dpdk.git] / doc / guides / sample_app_ug / ipsec_secgw.rst
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
31 IPsec Security Gateway Sample Application
32 =========================================
33
34 The IPsec Security Gateway application is an example of a "real world"
35 application using DPDK cryptodev framework.
36
37 Overview
38 --------
39
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.
43
44 Internet Key Exchange (IKE) is not implemented, so only manual setting of
45 Security Policies and Security Associations is supported.
46
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
49 using LPM.
50
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.
54
55 The Path for IPsec Inbound traffic is:
56
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.
63 *  Routing.
64 *  Write packet to port.
65
66 The Path for the IPsec Outbound traffic is:
67
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.
73 *  Routing.
74 *  Write packet to port.
75
76
77 Constraints
78 -----------
79
80 *  No IPv6 options headers.
81 *  No AH mode.
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*).
84 *  No chained mbufs.
85
86
87 Compiling the Application
88 -------------------------
89
90 To compile the application:
91
92 #. Go to the sample application directory::
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
100       export RTE_TARGET=x86_64-native-linuxapp-gcc
101
102    See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
103
104 #. Build the application::
105
106        make
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
115 Running the Application
116 -----------------------
117
118 The application has a number of command line options::
119
120
121    ./build/ipsec-secgw [EAL options] --
122                         -p PORTMASK -P -u PORTMASK
123                         --config (port,queue,lcore)[,(port,queue,lcore]
124                         --single-sa SAIDX
125                         -f CONFIG_FILE_PATH
126
127 Where:
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 *   ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues
139     from which ports are mapped to which cores.
140
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
143     purposes.
144
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.
149
150
151 The mapping of lcores to port/queues is similar to other l3fwd applications.
152
153 For example, given the following command line::
154
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                              \
159
160 where each options means:
161
162 *   The ``-l`` option enables cores 20 and 21.
163
164 *   The ``-n`` option sets memory 4 channels.
165
166 *   The ``--socket-mem`` to use 2GB on socket 1.
167
168 *   The ``--vdev "cryptodev_null_pmd"`` option creates virtual NULL cryptodev PMD.
169
170 *   The ``-p`` option enables ports (detected) 0, 1, 2 and 3.
171
172 *   The ``-P`` option enables promiscuous mode.
173
174 *   The ``-u`` option sets ports 1 and 2 as unprotected, leaving 2 and 3 as protected.
175
176 *   The ``--config`` option enables one queue per port with the following mapping:
177
178     +----------+-----------+-----------+---------------------------------------+
179     | **Port** | **Queue** | **lcore** | **Description**                       |
180     |          |           |           |                                       |
181     +----------+-----------+-----------+---------------------------------------+
182     | 0        | 0         | 20        | Map queue 0 from port 0 to lcore 20.  |
183     |          |           |           |                                       |
184     +----------+-----------+-----------+---------------------------------------+
185     | 1        | 0         | 20        | Map queue 0 from port 1 to lcore 20.  |
186     |          |           |           |                                       |
187     +----------+-----------+-----------+---------------------------------------+
188     | 2        | 0         | 21        | Map queue 0 from port 2 to lcore 21.  |
189     |          |           |           |                                       |
190     +----------+-----------+-----------+---------------------------------------+
191     | 3        | 0         | 21        | Map queue 0 from port 3 to lcore 21.  |
192     |          |           |           |                                       |
193     +----------+-----------+-----------+---------------------------------------+
194
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.
201
202 Refer to the *DPDK Getting Started Guide* for general information on running
203 applications and the Environment Abstraction Layer (EAL) options.
204
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.
210
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.
214
215 For example, something like the following command line:
216
217 .. code-block:: console
218
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" \
222             -- \
223             -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \
224             -f sample.cfg
225
226
227 Configurations
228 --------------
229
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
235 accordingly.
236
237
238 Configuration File Syntax
239 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
240
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.
244
245 Following are the configuration file syntax.
246
247 General rule syntax
248 ^^^^^^^^^^^^^^^^^^^
249
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
253 below.
254
255 The configuration parser supports the following special symbols:
256
257  * Comment symbol **#**. Any character from this symbol to the end of
258    line is treated as comment and will not be parsed.
259
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.
263
264
265 SP rule syntax
266 ^^^^^^^^^^^^^^
267
268 The SP rule syntax is shown as follows:
269
270 .. code-block:: console
271
272     sp <ip_ver> <dir> esp <action> <priority> <src_ip> <dst_ip>
273     <proto> <sport> <dport>
274
275
276 where each options means:
277
278 ``<ip_ver>``
279
280  * IP protocol version
281
282  * Optional: No
283
284  * Available options:
285
286    * *ipv4*: IP protocol version 4
287    * *ipv6*: IP protocol version 6
288
289 ``<dir>``
290
291  * The traffic direction
292
293  * Optional: No
294
295  * Available options:
296
297    * *in*: inbound traffic
298    * *out*: outbound traffic
299
300 ``<action>``
301
302  * IPsec action
303
304  * Optional: No
305
306  * Available options:
307
308    * *protect <SA_idx>*: the specified traffic is protected by SA rule
309      with id SA_idx
310    * *bypass*: the specified traffic traffic is bypassed
311    * *discard*: the specified traffic is discarded
312
313 ``<priority>``
314
315  * Rule priority
316
317  * Optional: Yes, default priority 0 will be used
318
319  * Syntax: *pri <id>*
320
321 ``<src_ip>``
322
323  * The source IP address and mask
324
325  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
326
327  * Syntax:
328
329    * *src X.X.X.X/Y* for IPv4
330    * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
331
332 ``<dst_ip>``
333
334  * The destination IP address and mask
335
336  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
337
338  * Syntax:
339
340    * *dst X.X.X.X/Y* for IPv4
341    * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
342
343 ``<proto>``
344
345  * The protocol start and end range
346
347  * Optional: yes, default range of 0 to 0 will be used
348
349  * Syntax: *proto X:Y*
350
351 ``<sport>``
352
353  * The source port start and end range
354
355  * Optional: yes, default range of 0 to 0 will be used
356
357  * Syntax: *sport X:Y*
358
359 ``<dport>``
360
361  * The destination port start and end range
362
363  * Optional: yes, default range of 0 to 0 will be used
364
365  * Syntax: *dport X:Y*
366
367 Example SP rules:
368
369 .. code-block:: console
370
371     sp ipv4 out esp protect 105 pri 1 dst 192.168.115.0/24 sport 0:65535 \
372     dport 0:65535
373
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
376
377
378 SA rule syntax
379 ^^^^^^^^^^^^^^
380
381 The successfully parsed SA rules will be stored in an array table.
382
383 The SA rule syntax is shown as follows:
384
385 .. code-block:: console
386
387     sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key>
388     <mode> <src_ip> <dst_ip>
389
390 where each options means:
391
392 ``<dir>``
393
394  * The traffic direction
395
396  * Optional: No
397
398  * Available options:
399
400    * *in*: inbound traffic
401    * *out*: outbound traffic
402
403 ``<spi>``
404
405  * The SPI number
406
407  * Optional: No
408
409  * Syntax: unsigned integer number
410
411 ``<cipher_algo>``
412
413  * Cipher algorithm
414
415  * Optional: Yes, unless <aead_algo> is not used
416
417  * Available options:
418
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
423
424  * Syntax: *cipher_algo <your algorithm>*
425
426 ``<cipher_key>``
427
428  * Cipher key, NOT available when 'null' algorithm is used
429
430  * Optional: Yes, unless <aead_algo> is not used.
431    Must be followed by <cipher_algo> option
432
433  * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
434    The number of bytes should be as same as the specified cipher algorithm
435    key size.
436
437    For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
438    A1:B2:C3:D4*
439
440 ``<auth_algo>``
441
442  * Authentication algorithm
443
444  * Optional: Yes, unless <aead_algo> is not used
445
446  * Available options:
447
448     * *null*: NULL algorithm
449     * *sha1-hmac*: HMAC SHA1 algorithm
450     * *aes-128-gcm*: AES-GCM 128-bit algorithm
451
452 ``<auth_key>``
453
454  * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm
455    is used.
456
457  * Optional: Yes, unless <aead_algo> is not used.
458    Must be followed by <auth_algo> option
459
460  * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
461    The number of bytes should be as same as the specified authentication
462    algorithm key size.
463
464    For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
465    A1:B2:C3:D4*
466
467 ``<aead_algo>``
468
469  * AEAD algorithm
470
471  * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used
472
473  * Syntax: *cipher_algo <your algorithm>*
474
475 ``<aead_key>``
476
477  * Cipher key, NOT available when 'null' algorithm is used
478
479  * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used.
480    Must be followed by <aead_algo> option
481
482  * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
483    The number of bytes should be as same as the specified AEAD algorithm
484    key size.
485
486    For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
487    A1:B2:C3:D4*
488
489 ``<mode>``
490
491  * The operation mode
492
493  * Optional: No
494
495  * Available options:
496
497    * *ipv4-tunnel*: Tunnel mode for IPv4 packets
498    * *ipv6-tunnel*: Tunnel mode for IPv6 packets
499    * *transport*: transport mode
500
501  * Syntax: mode XXX
502
503 ``<src_ip>``
504
505  * The source IP address. This option is not available when
506    transport mode is used
507
508  * Optional: Yes, default address 0.0.0.0 will be used
509
510  * Syntax:
511
512    * *src X.X.X.X* for IPv4
513    * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
514
515 ``<dst_ip>``
516
517  * The destination IP address. This option is not available when
518    transport mode is used
519
520  * Optional: Yes, default address 0.0.0.0 will be used
521
522  * Syntax:
523
524    * *dst X.X.X.X* for IPv4
525    * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
526
527 Example SA rules:
528
529 .. code-block:: console
530
531     sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \
532     src 172.16.1.5 dst 172.16.2.5
533
534     sa out 25 cipher_algo aes-128-cbc \
535     cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
536     auth_algo sha1-hmac \
537     auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \
538     mode ipv6-tunnel \
539     src 1111:1111:1111:1111:1111:1111:1111:5555 \
540     dst 2222:2222:2222:2222:2222:2222:2222:5555
541
542     sa in 105 cipher_algo aes-128-gcm \
543     cipher_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
544     auth_algo aes-128-gcm \
545     mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5
546
547 Routing rule syntax
548 ^^^^^^^^^^^^^^^^^^^
549
550 The Routing rule syntax is shown as follows:
551
552 .. code-block:: console
553
554     rt <ip_ver> <src_ip> <dst_ip> <port>
555
556
557 where each options means:
558
559 ``<ip_ver>``
560
561  * IP protocol version
562
563  * Optional: No
564
565  * Available options:
566
567    * *ipv4*: IP protocol version 4
568    * *ipv6*: IP protocol version 6
569
570 ``<src_ip>``
571
572  * The source IP address and mask
573
574  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
575
576  * Syntax:
577
578    * *src X.X.X.X/Y* for IPv4
579    * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
580
581 ``<dst_ip>``
582
583  * The destination IP address and mask
584
585  * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
586
587  * Syntax:
588
589    * *dst X.X.X.X/Y* for IPv4
590    * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
591
592 ``<port>``
593
594  * The traffic output port id
595
596  * Optional: yes, default output port 0 will be used
597
598  * Syntax: *port X*
599
600 Example SP rules:
601
602 .. code-block:: console
603
604     rt ipv4 dst 172.16.1.5/32 port 0
605
606     rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0