ipsec_secgw.rst revision 6b3e017e
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 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 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
66The 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
77Constraints
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
87Compiling the Application
88-------------------------
89
90To 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
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
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*   ``--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
151The mapping of lcores to port/queues is similar to other l3fwd applications.
152
153For 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
160where 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
202Refer to the *DPDK Getting Started Guide* for general information on running
203applications and the Environment Abstraction Layer (EAL) options.
204
205The application would do a best effort to "map" crypto devices to cores, with
206hardware devices having priority. Basically, hardware devices if present would
207be assigned to a core before software ones.
208This means that if the application is using a single core and both hardware
209and software crypto devices are detected, hardware devices will be used.
210
211A way to achieve the case where you want to force the use of virtual crypto
212devices is to whitelist the Ethernet devices needed and therefore implicitly
213blacklisting all hardware crypto devices.
214
215For 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
227Configurations
228--------------
229
230The following sections provide the syntax of configurations to initialize
231your SP, SA and Routing tables.
232Configurations shall be specified in the configuration file to be passed to
233the application. The file is then parsed by the application. The successful
234parsing will result in the appropriate rules being applied to the tables
235accordingly.
236
237
238Configuration File Syntax
239~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
240
241As mention in the overview, the Security Policies are ACL rules.
242The application parsers the rules specified in the configuration file and
243passes them to the ACL table, and replicates them per socket in use.
244
245Following are the configuration file syntax.
246
247General rule syntax
248^^^^^^^^^^^^^^^^^^^
249
250The parse treats one line in the configuration file as one configuration
251item (unless the line concatenation symbol exists). Every configuration
252item shall follow the syntax of either SP, SA, or Routing rules specified
253below.
254
255The 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
265SP rule syntax
266^^^^^^^^^^^^^^
267
268The 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
276where 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
367Example 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
378SA rule syntax
379^^^^^^^^^^^^^^
380
381The successfully parsed SA rules will be stored in an array table.
382
383The 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
390where 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: No
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: No, must followed by <cipher_algo> option
431
432 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
433   The number of bytes should be as same as the specified cipher algorithm
434   key size.
435
436   For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
437   A1:B2:C3:D4*
438
439``<auth_algo>``
440
441 * Authentication algorithm
442
443 * Optional: No
444
445 * Available options:
446
447    * *null*: NULL algorithm
448    * *sha1-hmac*: HMAC SHA1 algorithm
449    * *aes-128-gcm*: AES-GCM 128-bit algorithm
450
451``<auth_key>``
452
453 * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm
454   is used.
455
456 * Optional: No, must followed by <auth_algo> option
457
458 * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
459   The number of bytes should be as same as the specified authentication
460   algorithm key size.
461
462   For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
463   A1:B2:C3:D4*
464
465``<mode>``
466
467 * The operation mode
468
469 * Optional: No
470
471 * Available options:
472
473   * *ipv4-tunnel*: Tunnel mode for IPv4 packets
474   * *ipv6-tunnel*: Tunnel mode for IPv6 packets
475   * *transport*: transport mode
476
477 * Syntax: mode XXX
478
479``<src_ip>``
480
481 * The source IP address. This option is not available when
482   transport mode is used
483
484 * Optional: Yes, default address 0.0.0.0 will be used
485
486 * Syntax:
487
488   * *src X.X.X.X* for IPv4
489   * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
490
491``<dst_ip>``
492
493 * The destination IP address. This option is not available when
494   transport mode is used
495
496 * Optional: Yes, default address 0.0.0.0 will be used
497
498 * Syntax:
499
500   * *dst X.X.X.X* for IPv4
501   * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
502
503Example SA rules:
504
505.. code-block:: console
506
507    sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \
508    src 172.16.1.5 dst 172.16.2.5
509
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 \
514    mode ipv6-tunnel \
515    src 1111:1111:1111:1111:1111:1111:1111:5555 \
516    dst 2222:2222:2222:2222:2222:2222:2222:5555
517
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
522
523Routing rule syntax
524^^^^^^^^^^^^^^^^^^^
525
526The Routing rule syntax is shown as follows:
527
528.. code-block:: console
529
530    rt <ip_ver> <src_ip> <dst_ip> <port>
531
532
533where each options means:
534
535``<ip_ver>``
536
537 * IP protocol version
538
539 * Optional: No
540
541 * Available options:
542
543   * *ipv4*: IP protocol version 4
544   * *ipv6*: IP protocol version 6
545
546``<src_ip>``
547
548 * The source IP address and mask
549
550 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
551
552 * Syntax:
553
554   * *src X.X.X.X/Y* for IPv4
555   * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
556
557``<dst_ip>``
558
559 * The destination IP address and mask
560
561 * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used
562
563 * Syntax:
564
565   * *dst X.X.X.X/Y* for IPv4
566   * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6
567
568``<port>``
569
570 * The traffic output port id
571
572 * Optional: yes, default output port 0 will be used
573
574 * Syntax: *port X*
575
576Example SP rules:
577
578.. code-block:: console
579
580    rt ipv4 dst 172.16.1.5/32 port 0
581
582    rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0
583