]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright(c) 2016-2017 Intel Corporation. | |
7c673cae FG |
3 | |
4 | IPsec Security Gateway Sample Application | |
5 | ========================================= | |
6 | ||
7 | The IPsec Security Gateway application is an example of a "real world" | |
8 | application using DPDK cryptodev framework. | |
9 | ||
10 | Overview | |
11 | -------- | |
12 | ||
13 | The application demonstrates the implementation of a Security Gateway | |
14 | (not IPsec compliant, see the Constraints section below) using DPDK based on RFC4301, | |
15 | RFC4303, RFC3602 and RFC2404. | |
16 | ||
17 | Internet Key Exchange (IKE) is not implemented, so only manual setting of | |
18 | Security Policies and Security Associations is supported. | |
19 | ||
20 | The Security Policies (SP) are implemented as ACL rules, the Security | |
21 | Associations (SA) are stored in a table and the routing is implemented | |
22 | using LPM. | |
23 | ||
24 | The application classifies the ports as *Protected* and *Unprotected*. | |
25 | Thus, traffic received on an Unprotected or Protected port is consider | |
26 | Inbound or Outbound respectively. | |
27 | ||
9f95a23c TL |
28 | The application also supports complete IPsec protocol offload to hardware |
29 | (Look aside crypto accelerator or using ethernet device). It also support | |
11fdf7f2 TL |
30 | inline ipsec processing by the supported ethernet device during transmission. |
31 | These modes can be selected during the SA creation configuration. | |
32 | ||
33 | In case of complete protocol offload, the processing of headers(ESP and outer | |
34 | IP header) is done by the hardware and the application does not need to | |
35 | add/remove them during outbound/inbound processing. | |
36 | ||
37 | For inline offloaded outbound traffic, the application will not do the LPM | |
38 | lookup for routing, as the port on which the packet has to be forwarded will be | |
39 | part of the SA. Security parameters will be configured on that port only, and | |
40 | sending the packet on other ports could result in unencrypted packets being | |
41 | sent out. | |
42 | ||
7c673cae FG |
43 | The Path for IPsec Inbound traffic is: |
44 | ||
45 | * Read packets from the port. | |
46 | * Classify packets between IPv4 and ESP. | |
47 | * Perform Inbound SA lookup for ESP packets based on their SPI. | |
11fdf7f2 TL |
48 | * Perform Verification/Decryption (Not needed in case of inline ipsec). |
49 | * Remove ESP and outer IP header (Not needed in case of protocol offload). | |
7c673cae FG |
50 | * Inbound SP check using ACL of decrypted packets and any other IPv4 packets. |
51 | * Routing. | |
52 | * Write packet to port. | |
53 | ||
54 | The Path for the IPsec Outbound traffic is: | |
55 | ||
56 | * Read packets from the port. | |
57 | * Perform Outbound SP check using ACL of all IPv4 traffic. | |
58 | * Perform Outbound SA lookup for packets that need IPsec protection. | |
11fdf7f2 TL |
59 | * Add ESP and outer IP header (Not needed in case protocol offload). |
60 | * Perform Encryption/Digest (Not needed in case of inline ipsec). | |
7c673cae FG |
61 | * Routing. |
62 | * Write packet to port. | |
63 | ||
64 | ||
65 | Constraints | |
66 | ----------- | |
67 | ||
68 | * No IPv6 options headers. | |
69 | * No AH mode. | |
9f95a23c | 70 | * Supported algorithms: AES-CBC, AES-CTR, AES-GCM, 3DES-CBC, HMAC-SHA1 and NULL. |
7c673cae FG |
71 | * Each SA must be handle by a unique lcore (*1 RX queue per port*). |
72 | * No chained mbufs. | |
73 | ||
7c673cae FG |
74 | Compiling the Application |
75 | ------------------------- | |
76 | ||
11fdf7f2 | 77 | To compile the sample application see :doc:`compiling`. |
7c673cae | 78 | |
9f95a23c | 79 | The application is located in the ``ipsec-secgw`` sub-directory. |
7c673cae FG |
80 | |
81 | #. [Optional] Build the application for debugging: | |
82 | This option adds some extra flags, disables compiler optimizations and | |
83 | is verbose:: | |
84 | ||
85 | make DEBUG=1 | |
86 | ||
87 | ||
88 | Running the Application | |
89 | ----------------------- | |
90 | ||
91 | The application has a number of command line options:: | |
92 | ||
93 | ||
94 | ./build/ipsec-secgw [EAL options] -- | |
11fdf7f2 | 95 | -p PORTMASK -P -u PORTMASK -j FRAMESIZE |
9f95a23c | 96 | -l -w REPLAY_WINOW_SIZE -e -a |
7c673cae FG |
97 | --config (port,queue,lcore)[,(port,queue,lcore] |
98 | --single-sa SAIDX | |
9f95a23c TL |
99 | --rxoffload MASK |
100 | --txoffload MASK | |
7c673cae FG |
101 | -f CONFIG_FILE_PATH |
102 | ||
103 | Where: | |
104 | ||
105 | * ``-p PORTMASK``: Hexadecimal bitmask of ports to configure. | |
106 | ||
107 | * ``-P``: *optional*. Sets all ports to promiscuous mode so that packets are | |
108 | accepted regardless of the packet's Ethernet MAC destination address. | |
109 | Without this option, only packets with the Ethernet MAC destination address | |
110 | set to the Ethernet address of the port are accepted (default is enabled). | |
111 | ||
112 | * ``-u PORTMASK``: hexadecimal bitmask of unprotected ports | |
113 | ||
11fdf7f2 TL |
114 | * ``-j FRAMESIZE``: *optional*. Enables jumbo frames with the maximum size |
115 | specified as FRAMESIZE. If an invalid value is provided as FRAMESIZE | |
116 | then the default value 9000 is used. | |
117 | ||
9f95a23c TL |
118 | * ``-l``: enables code-path that uses librte_ipsec. |
119 | ||
120 | * ``-w REPLAY_WINOW_SIZE``: specifies the IPsec sequence number replay window | |
121 | size for each Security Association (available only with librte_ipsec | |
122 | code path). | |
123 | ||
124 | * ``-e``: enables Security Association extended sequence number processing | |
125 | (available only with librte_ipsec code path). | |
126 | ||
127 | * ``-a``: enables Security Association sequence number atomic behavior | |
128 | (available only with librte_ipsec code path). | |
129 | ||
7c673cae FG |
130 | * ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues |
131 | from which ports are mapped to which cores. | |
132 | ||
133 | * ``--single-sa SAIDX``: use a single SA for outbound traffic, bypassing the SP | |
134 | on both Inbound and Outbound. This option is meant for debugging/performance | |
135 | purposes. | |
136 | ||
9f95a23c TL |
137 | * ``--rxoffload MASK``: RX HW offload capabilities to enable/use on this port |
138 | (bitmask of DEV_RX_OFFLOAD_* values). It is an optional parameter and | |
139 | allows user to disable some of the RX HW offload capabilities. | |
140 | By default all HW RX offloads are enabled. | |
141 | ||
142 | * ``--txoffload MASK``: TX HW offload capabilities to enable/use on this port | |
143 | (bitmask of DEV_TX_OFFLOAD_* values). It is an optional parameter and | |
144 | allows user to disable some of the TX HW offload capabilities. | |
145 | By default all HW TX offloads are enabled. | |
146 | ||
7c673cae FG |
147 | * ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all |
148 | configuration items for running the application (See Configuration file | |
149 | syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified. | |
150 | **ONLY** the UNIX format configuration file is accepted. | |
151 | ||
152 | ||
153 | The mapping of lcores to port/queues is similar to other l3fwd applications. | |
154 | ||
155 | For example, given the following command line:: | |
156 | ||
157 | ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ | |
11fdf7f2 | 158 | --vdev "crypto_null" -- -p 0xf -P -u 0x3 \ |
7c673cae FG |
159 | --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ |
160 | -f /path/to/config_file \ | |
161 | ||
162 | where each options means: | |
163 | ||
164 | * The ``-l`` option enables cores 20 and 21. | |
165 | ||
166 | * The ``-n`` option sets memory 4 channels. | |
167 | ||
168 | * The ``--socket-mem`` to use 2GB on socket 1. | |
169 | ||
11fdf7f2 | 170 | * The ``--vdev "crypto_null"`` option creates virtual NULL cryptodev PMD. |
7c673cae FG |
171 | |
172 | * The ``-p`` option enables ports (detected) 0, 1, 2 and 3. | |
173 | ||
174 | * The ``-P`` option enables promiscuous mode. | |
175 | ||
176 | * The ``-u`` option sets ports 1 and 2 as unprotected, leaving 2 and 3 as protected. | |
177 | ||
178 | * The ``--config`` option enables one queue per port with the following mapping: | |
179 | ||
180 | +----------+-----------+-----------+---------------------------------------+ | |
181 | | **Port** | **Queue** | **lcore** | **Description** | | |
182 | | | | | | | |
183 | +----------+-----------+-----------+---------------------------------------+ | |
184 | | 0 | 0 | 20 | Map queue 0 from port 0 to lcore 20. | | |
185 | | | | | | | |
186 | +----------+-----------+-----------+---------------------------------------+ | |
187 | | 1 | 0 | 20 | Map queue 0 from port 1 to lcore 20. | | |
188 | | | | | | | |
189 | +----------+-----------+-----------+---------------------------------------+ | |
190 | | 2 | 0 | 21 | Map queue 0 from port 2 to lcore 21. | | |
191 | | | | | | | |
192 | +----------+-----------+-----------+---------------------------------------+ | |
193 | | 3 | 0 | 21 | Map queue 0 from port 3 to lcore 21. | | |
194 | | | | | | | |
195 | +----------+-----------+-----------+---------------------------------------+ | |
196 | ||
197 | * The ``-f /path/to/config_file`` option enables the application read and | |
198 | parse the configuration file specified, and configures the application | |
199 | with a given set of SP, SA and Routing entries accordingly. The syntax of | |
200 | the configuration file will be explained below in more detail. Please | |
201 | **note** the parser only accepts UNIX format text file. Other formats | |
202 | such as DOS/MAC format will cause a parse error. | |
203 | ||
204 | Refer to the *DPDK Getting Started Guide* for general information on running | |
205 | applications and the Environment Abstraction Layer (EAL) options. | |
206 | ||
207 | The application would do a best effort to "map" crypto devices to cores, with | |
208 | hardware devices having priority. Basically, hardware devices if present would | |
209 | be assigned to a core before software ones. | |
210 | This means that if the application is using a single core and both hardware | |
211 | and software crypto devices are detected, hardware devices will be used. | |
212 | ||
213 | A way to achieve the case where you want to force the use of virtual crypto | |
214 | devices is to whitelist the Ethernet devices needed and therefore implicitly | |
215 | blacklisting all hardware crypto devices. | |
216 | ||
217 | For example, something like the following command line: | |
218 | ||
219 | .. code-block:: console | |
220 | ||
221 | ./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \ | |
222 | -w 81:00.0 -w 81:00.1 -w 81:00.2 -w 81:00.3 \ | |
11fdf7f2 | 223 | --vdev "crypto_aesni_mb" --vdev "crypto_null" \ |
7c673cae FG |
224 | -- \ |
225 | -p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \ | |
226 | -f sample.cfg | |
227 | ||
228 | ||
229 | Configurations | |
230 | -------------- | |
231 | ||
232 | The following sections provide the syntax of configurations to initialize | |
9f95a23c | 233 | your SP, SA, Routing and Neighbour tables. |
7c673cae FG |
234 | Configurations shall be specified in the configuration file to be passed to |
235 | the application. The file is then parsed by the application. The successful | |
236 | parsing will result in the appropriate rules being applied to the tables | |
237 | accordingly. | |
238 | ||
239 | ||
240 | Configuration File Syntax | |
9f95a23c | 241 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
7c673cae FG |
242 | |
243 | As mention in the overview, the Security Policies are ACL rules. | |
244 | The application parsers the rules specified in the configuration file and | |
245 | passes them to the ACL table, and replicates them per socket in use. | |
246 | ||
247 | Following are the configuration file syntax. | |
248 | ||
249 | General rule syntax | |
250 | ^^^^^^^^^^^^^^^^^^^ | |
251 | ||
252 | The parse treats one line in the configuration file as one configuration | |
253 | item (unless the line concatenation symbol exists). Every configuration | |
9f95a23c TL |
254 | item shall follow the syntax of either SP, SA, Routing or Neighbour |
255 | rules specified below. | |
7c673cae FG |
256 | |
257 | The configuration parser supports the following special symbols: | |
258 | ||
259 | * Comment symbol **#**. Any character from this symbol to the end of | |
260 | line is treated as comment and will not be parsed. | |
261 | ||
262 | * Line concatenation symbol **\\**. This symbol shall be placed in the end | |
263 | of the line to be concatenated to the line below. Multiple lines' | |
264 | concatenation is supported. | |
265 | ||
266 | ||
267 | SP rule syntax | |
268 | ^^^^^^^^^^^^^^ | |
269 | ||
270 | The SP rule syntax is shown as follows: | |
271 | ||
272 | .. code-block:: console | |
273 | ||
274 | sp <ip_ver> <dir> esp <action> <priority> <src_ip> <dst_ip> | |
275 | <proto> <sport> <dport> | |
276 | ||
277 | ||
278 | where each options means: | |
279 | ||
280 | ``<ip_ver>`` | |
281 | ||
282 | * IP protocol version | |
283 | ||
284 | * Optional: No | |
285 | ||
286 | * Available options: | |
287 | ||
288 | * *ipv4*: IP protocol version 4 | |
289 | * *ipv6*: IP protocol version 6 | |
290 | ||
291 | ``<dir>`` | |
292 | ||
293 | * The traffic direction | |
294 | ||
295 | * Optional: No | |
296 | ||
297 | * Available options: | |
298 | ||
299 | * *in*: inbound traffic | |
300 | * *out*: outbound traffic | |
301 | ||
302 | ``<action>`` | |
303 | ||
304 | * IPsec action | |
305 | ||
306 | * Optional: No | |
307 | ||
308 | * Available options: | |
309 | ||
310 | * *protect <SA_idx>*: the specified traffic is protected by SA rule | |
311 | with id SA_idx | |
312 | * *bypass*: the specified traffic traffic is bypassed | |
313 | * *discard*: the specified traffic is discarded | |
314 | ||
315 | ``<priority>`` | |
316 | ||
317 | * Rule priority | |
318 | ||
319 | * Optional: Yes, default priority 0 will be used | |
320 | ||
321 | * Syntax: *pri <id>* | |
322 | ||
323 | ``<src_ip>`` | |
324 | ||
325 | * The source IP address and mask | |
326 | ||
327 | * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used | |
328 | ||
329 | * Syntax: | |
330 | ||
331 | * *src X.X.X.X/Y* for IPv4 | |
332 | * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 | |
333 | ||
334 | ``<dst_ip>`` | |
335 | ||
336 | * The destination IP address and mask | |
337 | ||
338 | * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used | |
339 | ||
340 | * Syntax: | |
341 | ||
342 | * *dst X.X.X.X/Y* for IPv4 | |
343 | * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 | |
344 | ||
345 | ``<proto>`` | |
346 | ||
347 | * The protocol start and end range | |
348 | ||
349 | * Optional: yes, default range of 0 to 0 will be used | |
350 | ||
351 | * Syntax: *proto X:Y* | |
352 | ||
353 | ``<sport>`` | |
354 | ||
355 | * The source port start and end range | |
356 | ||
357 | * Optional: yes, default range of 0 to 0 will be used | |
358 | ||
359 | * Syntax: *sport X:Y* | |
360 | ||
361 | ``<dport>`` | |
362 | ||
363 | * The destination port start and end range | |
364 | ||
365 | * Optional: yes, default range of 0 to 0 will be used | |
366 | ||
367 | * Syntax: *dport X:Y* | |
368 | ||
369 | Example SP rules: | |
370 | ||
371 | .. code-block:: console | |
372 | ||
373 | sp ipv4 out esp protect 105 pri 1 dst 192.168.115.0/24 sport 0:65535 \ | |
374 | dport 0:65535 | |
375 | ||
376 | sp ipv6 in esp bypass pri 1 dst 0000:0000:0000:0000:5555:5555:\ | |
377 | 0000:0000/96 sport 0:65535 dport 0:65535 | |
378 | ||
379 | ||
380 | SA rule syntax | |
381 | ^^^^^^^^^^^^^^ | |
382 | ||
383 | The successfully parsed SA rules will be stored in an array table. | |
384 | ||
385 | The SA rule syntax is shown as follows: | |
386 | ||
387 | .. code-block:: console | |
388 | ||
389 | sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key> | |
11fdf7f2 | 390 | <mode> <src_ip> <dst_ip> <action_type> <port_id> |
7c673cae FG |
391 | |
392 | where each options means: | |
393 | ||
394 | ``<dir>`` | |
395 | ||
396 | * The traffic direction | |
397 | ||
398 | * Optional: No | |
399 | ||
400 | * Available options: | |
401 | ||
402 | * *in*: inbound traffic | |
403 | * *out*: outbound traffic | |
404 | ||
405 | ``<spi>`` | |
406 | ||
407 | * The SPI number | |
408 | ||
409 | * Optional: No | |
410 | ||
411 | * Syntax: unsigned integer number | |
412 | ||
413 | ``<cipher_algo>`` | |
414 | ||
415 | * Cipher algorithm | |
416 | ||
11fdf7f2 | 417 | * Optional: Yes, unless <aead_algo> is not used |
7c673cae FG |
418 | |
419 | * Available options: | |
420 | ||
421 | * *null*: NULL algorithm | |
422 | * *aes-128-cbc*: AES-CBC 128-bit algorithm | |
11fdf7f2 | 423 | * *aes-256-cbc*: AES-CBC 256-bit algorithm |
7c673cae | 424 | * *aes-128-ctr*: AES-CTR 128-bit algorithm |
9f95a23c | 425 | * *3des-cbc*: 3DES-CBC 192-bit algorithm |
7c673cae FG |
426 | |
427 | * Syntax: *cipher_algo <your algorithm>* | |
428 | ||
429 | ``<cipher_key>`` | |
430 | ||
431 | * Cipher key, NOT available when 'null' algorithm is used | |
432 | ||
11fdf7f2 TL |
433 | * Optional: Yes, unless <aead_algo> is not used. |
434 | Must be followed by <cipher_algo> option | |
7c673cae FG |
435 | |
436 | * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. | |
437 | The number of bytes should be as same as the specified cipher algorithm | |
438 | key size. | |
439 | ||
440 | For example: *cipher_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: | |
441 | A1:B2:C3:D4* | |
442 | ||
443 | ``<auth_algo>`` | |
444 | ||
445 | * Authentication algorithm | |
446 | ||
11fdf7f2 | 447 | * Optional: Yes, unless <aead_algo> is not used |
7c673cae FG |
448 | |
449 | * Available options: | |
450 | ||
451 | * *null*: NULL algorithm | |
452 | * *sha1-hmac*: HMAC SHA1 algorithm | |
7c673cae FG |
453 | |
454 | ``<auth_key>`` | |
455 | ||
456 | * Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm | |
457 | is used. | |
458 | ||
11fdf7f2 TL |
459 | * Optional: Yes, unless <aead_algo> is not used. |
460 | Must be followed by <auth_algo> option | |
7c673cae FG |
461 | |
462 | * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. | |
463 | The number of bytes should be as same as the specified authentication | |
464 | algorithm key size. | |
465 | ||
466 | For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: | |
467 | A1:B2:C3:D4* | |
468 | ||
11fdf7f2 TL |
469 | ``<aead_algo>`` |
470 | ||
471 | * AEAD algorithm | |
472 | ||
473 | * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used | |
474 | ||
475 | * Available options: | |
476 | ||
477 | * *aes-128-gcm*: AES-GCM 128-bit algorithm | |
478 | ||
479 | * Syntax: *cipher_algo <your algorithm>* | |
480 | ||
481 | ``<aead_key>`` | |
482 | ||
483 | * Cipher key, NOT available when 'null' algorithm is used | |
484 | ||
485 | * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used. | |
486 | Must be followed by <aead_algo> option | |
487 | ||
488 | * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'. | |
489 | The number of bytes should be as same as the specified AEAD algorithm | |
490 | key size. | |
491 | ||
492 | For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4: | |
493 | A1:B2:C3:D4* | |
494 | ||
7c673cae FG |
495 | ``<mode>`` |
496 | ||
497 | * The operation mode | |
498 | ||
499 | * Optional: No | |
500 | ||
501 | * Available options: | |
502 | ||
503 | * *ipv4-tunnel*: Tunnel mode for IPv4 packets | |
504 | * *ipv6-tunnel*: Tunnel mode for IPv6 packets | |
505 | * *transport*: transport mode | |
506 | ||
507 | * Syntax: mode XXX | |
508 | ||
509 | ``<src_ip>`` | |
510 | ||
511 | * The source IP address. This option is not available when | |
512 | transport mode is used | |
513 | ||
514 | * Optional: Yes, default address 0.0.0.0 will be used | |
515 | ||
516 | * Syntax: | |
517 | ||
518 | * *src X.X.X.X* for IPv4 | |
519 | * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 | |
520 | ||
521 | ``<dst_ip>`` | |
522 | ||
523 | * The destination IP address. This option is not available when | |
524 | transport mode is used | |
525 | ||
526 | * Optional: Yes, default address 0.0.0.0 will be used | |
527 | ||
528 | * Syntax: | |
529 | ||
530 | * *dst X.X.X.X* for IPv4 | |
531 | * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6 | |
532 | ||
11fdf7f2 TL |
533 | ``<type>`` |
534 | ||
535 | * Action type to specify the security action. This option specify | |
536 | the SA to be performed with look aside protocol offload to HW | |
537 | accelerator or protocol offload on ethernet device or inline | |
538 | crypto processing on the ethernet device during transmission. | |
539 | ||
540 | * Optional: Yes, default type *no-offload* | |
541 | ||
542 | * Available options: | |
543 | ||
544 | * *lookaside-protocol-offload*: look aside protocol offload to HW accelerator | |
545 | * *inline-protocol-offload*: inline protocol offload on ethernet device | |
546 | * *inline-crypto-offload*: inline crypto processing on ethernet device | |
547 | * *no-offload*: no offloading to hardware | |
548 | ||
549 | ``<port_id>`` | |
550 | ||
551 | * Port/device ID of the ethernet/crypto accelerator for which the SA is | |
552 | configured. For *inline-crypto-offload* and *inline-protocol-offload*, this | |
553 | port will be used for routing. The routing table will not be referred in | |
554 | this case. | |
555 | ||
556 | * Optional: No, if *type* is not *no-offload* | |
557 | ||
558 | * Syntax: | |
559 | ||
560 | * *port_id X* X is a valid device number in decimal | |
561 | ||
562 | ||
7c673cae FG |
563 | Example SA rules: |
564 | ||
565 | .. code-block:: console | |
566 | ||
567 | sa out 5 cipher_algo null auth_algo null mode ipv4-tunnel \ | |
568 | src 172.16.1.5 dst 172.16.2.5 | |
569 | ||
570 | sa out 25 cipher_algo aes-128-cbc \ | |
571 | cipher_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ | |
572 | auth_algo sha1-hmac \ | |
573 | auth_key c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3:c3 \ | |
574 | mode ipv6-tunnel \ | |
575 | src 1111:1111:1111:1111:1111:1111:1111:5555 \ | |
576 | dst 2222:2222:2222:2222:2222:2222:2222:5555 | |
577 | ||
11fdf7f2 TL |
578 | sa in 105 aead_algo aes-128-gcm \ |
579 | aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \ | |
7c673cae FG |
580 | mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 |
581 | ||
11fdf7f2 TL |
582 | sa out 5 cipher_algo aes-128-cbc cipher_key 0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0 \ |
583 | auth_algo sha1-hmac auth_key 0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0 \ | |
584 | mode ipv4-tunnel src 172.16.1.5 dst 172.16.2.5 \ | |
585 | type lookaside-protocol-offload port_id 4 | |
586 | ||
9f95a23c TL |
587 | sa in 35 aead_algo aes-128-gcm \ |
588 | aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \ | |
589 | mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5 \ | |
590 | type inline-crypto-offload port_id 0 | |
591 | ||
7c673cae FG |
592 | Routing rule syntax |
593 | ^^^^^^^^^^^^^^^^^^^ | |
594 | ||
595 | The Routing rule syntax is shown as follows: | |
596 | ||
597 | .. code-block:: console | |
598 | ||
599 | rt <ip_ver> <src_ip> <dst_ip> <port> | |
600 | ||
601 | ||
602 | where each options means: | |
603 | ||
604 | ``<ip_ver>`` | |
605 | ||
606 | * IP protocol version | |
607 | ||
608 | * Optional: No | |
609 | ||
610 | * Available options: | |
611 | ||
612 | * *ipv4*: IP protocol version 4 | |
613 | * *ipv6*: IP protocol version 6 | |
614 | ||
615 | ``<src_ip>`` | |
616 | ||
617 | * The source IP address and mask | |
618 | ||
619 | * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used | |
620 | ||
621 | * Syntax: | |
622 | ||
623 | * *src X.X.X.X/Y* for IPv4 | |
624 | * *src XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 | |
625 | ||
626 | ``<dst_ip>`` | |
627 | ||
628 | * The destination IP address and mask | |
629 | ||
630 | * Optional: Yes, default address 0.0.0.0 and mask of 0 will be used | |
631 | ||
632 | * Syntax: | |
633 | ||
634 | * *dst X.X.X.X/Y* for IPv4 | |
635 | * *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX/Y* for IPv6 | |
636 | ||
637 | ``<port>`` | |
638 | ||
639 | * The traffic output port id | |
640 | ||
641 | * Optional: yes, default output port 0 will be used | |
642 | ||
643 | * Syntax: *port X* | |
644 | ||
645 | Example SP rules: | |
646 | ||
647 | .. code-block:: console | |
648 | ||
649 | rt ipv4 dst 172.16.1.5/32 port 0 | |
650 | ||
651 | rt ipv6 dst 1111:1111:1111:1111:1111:1111:1111:5555/116 port 0 | |
9f95a23c TL |
652 | |
653 | Neighbour rule syntax | |
654 | ^^^^^^^^^^^^^^^^^^^^^ | |
655 | ||
656 | The Neighbour rule syntax is shown as follows: | |
657 | ||
658 | .. code-block:: console | |
659 | ||
660 | neigh <port> <dst_mac> | |
661 | ||
662 | ||
663 | where each options means: | |
664 | ||
665 | ``<port>`` | |
666 | ||
667 | * The output port id | |
668 | ||
669 | * Optional: No | |
670 | ||
671 | * Syntax: *port X* | |
672 | ||
673 | ``<dst_mac>`` | |
674 | ||
675 | * The destination ethernet address to use for that port | |
676 | ||
677 | * Optional: No | |
678 | ||
679 | * Syntax: | |
680 | ||
681 | * XX:XX:XX:XX:XX:XX | |
682 | ||
683 | Example Neighbour rules: | |
684 | ||
685 | .. code-block:: console | |
686 | ||
687 | neigh port 0 DE:AD:BE:EF:01:02 | |
688 | ||
689 | Test directory | |
690 | -------------- | |
691 | ||
692 | The test directory contains scripts for testing the various encryption | |
693 | algorithms. | |
694 | ||
695 | The purpose of the scripts is to automate ipsec-secgw testing | |
696 | using another system running linux as a DUT. | |
697 | ||
698 | The user must setup the following environment variables: | |
699 | ||
700 | * ``SGW_PATH``: path to the ipsec-secgw binary to test. | |
701 | ||
702 | * ``REMOTE_HOST``: IP address/hostname of the DUT. | |
703 | ||
704 | * ``REMOTE_IFACE``: interface name for the test-port on the DUT. | |
705 | ||
706 | * ``ETH_DEV``: ethernet device to be used on the SUT by DPDK ('-w <pci-id>') | |
707 | ||
708 | Also the user can optionally setup: | |
709 | ||
710 | * ``SGW_LCORE``: lcore to run ipsec-secgw on (default value is 0) | |
711 | ||
712 | * ``CRYPTO_DEV``: crypto device to be used ('-w <pci-id>'). If none specified | |
713 | appropriate vdevs will be created by the script | |
714 | ||
715 | Note that most of the tests require the appropriate crypto PMD/device to be | |
716 | available. | |
717 | ||
718 | Server configuration | |
719 | ~~~~~~~~~~~~~~~~~~~~ | |
720 | ||
721 | Two servers are required for the tests, SUT and DUT. | |
722 | ||
723 | Make sure the user from the SUT can ssh to the DUT without entering the password. | |
724 | To enable this feature keys must be setup on the DUT. | |
725 | ||
726 | ``ssh-keygen`` will make a private & public key pair on the SUT. | |
727 | ||
728 | ``ssh-copy-id`` <user name>@<target host name> on the SUT will copy the public | |
729 | key to the DUT. It will ask for credentials so that it can upload the public key. | |
730 | ||
731 | The SUT and DUT are connected through at least 2 NIC ports. | |
732 | ||
733 | One NIC port is expected to be managed by linux on both machines and will be | |
734 | used as a control path. | |
735 | ||
736 | The second NIC port (test-port) should be bound to DPDK on the SUT, and should | |
737 | be managed by linux on the DUT. | |
738 | ||
739 | The script starts ``ipsec-secgw`` with 2 NIC devices: ``test-port`` and | |
740 | ``tap vdev``. | |
741 | ||
742 | It then configures the local tap interface and the remote interface and IPsec | |
743 | policies in the following way: | |
744 | ||
745 | Traffic going over the test-port in both directions has to be protected by IPsec. | |
746 | ||
747 | Traffic going over the TAP port in both directions does not have to be protected. | |
748 | ||
749 | i.e: | |
750 | ||
751 | DUT OS(NIC1)--(IPsec)-->(NIC1)ipsec-secgw(TAP)--(plain)-->(TAP)SUT OS | |
752 | ||
753 | SUT OS(TAP)--(plain)-->(TAP)psec-secgw(NIC1)--(IPsec)-->(NIC1)DUT OS | |
754 | ||
755 | It then tries to perform some data transfer using the scheme described above. | |
756 | ||
757 | usage | |
758 | ~~~~~ | |
759 | ||
760 | In the ipsec-secgw/test directory | |
761 | ||
762 | to run one test for IPv4 or IPv6 | |
763 | ||
764 | /bin/bash linux_test(4|6).sh <ipsec_mode> | |
765 | ||
766 | to run all tests for IPv4 or IPv6 | |
767 | ||
768 | /bin/bash run_test.sh -4|-6 | |
769 | ||
770 | For the list of available modes please refer to run_test.sh. |