-.. BSD LICENSE
- Copyright(c) 2016 Intel Corporation. All rights reserved.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of Intel Corporation nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2016-2017 Intel Corporation.
IPsec Security Gateway Sample Application
=========================================
Thus, traffic received on an Unprotected or Protected port is consider
Inbound or Outbound respectively.
+The application also supports complete IPSec protocol offload to hardware
+(Look aside crypto accelarator or using ethernet device). It also support
+inline ipsec processing by the supported ethernet device during transmission.
+These modes can be selected during the SA creation configuration.
+
+In case of complete protocol offload, the processing of headers(ESP and outer
+IP header) is done by the hardware and the application does not need to
+add/remove them during outbound/inbound processing.
+
+For inline offloaded outbound traffic, the application will not do the LPM
+lookup for routing, as the port on which the packet has to be forwarded will be
+part of the SA. Security parameters will be configured on that port only, and
+sending the packet on other ports could result in unencrypted packets being
+sent out.
+
The Path for IPsec Inbound traffic is:
* Read packets from the port.
* Classify packets between IPv4 and ESP.
* Perform Inbound SA lookup for ESP packets based on their SPI.
-* Perform Verification/Decryption.
-* Remove ESP and outer IP header
+* Perform Verification/Decryption (Not needed in case of inline ipsec).
+* Remove ESP and outer IP header (Not needed in case of protocol offload).
* Inbound SP check using ACL of decrypted packets and any other IPv4 packets.
* Routing.
* Write packet to port.
* Read packets from the port.
* Perform Outbound SP check using ACL of all IPv4 traffic.
* Perform Outbound SA lookup for packets that need IPsec protection.
-* Add ESP and outer IP header.
-* Perform Encryption/Digest.
+* Add ESP and outer IP header (Not needed in case protocol offload).
+* Perform Encryption/Digest (Not needed in case of inline ipsec).
* Routing.
* Write packet to port.
* Each SA must be handle by a unique lcore (*1 RX queue per port*).
* No chained mbufs.
-
Compiling the Application
-------------------------
-To compile the application:
-
-#. Go to the sample application directory::
-
- export RTE_SDK=/path/to/rte_sdk
- cd ${RTE_SDK}/examples/ipsec-secgw
+To compile the sample application see :doc:`compiling`.
-#. Set the target (a default target is used if not specified). For example::
-
-
- export RTE_TARGET=x86_64-native-linuxapp-gcc
-
- See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
-
-#. Build the application::
-
- make
+The application is located in the ``rpsec-secgw`` sub-directory.
#. [Optional] Build the application for debugging:
This option adds some extra flags, disables compiler optimizations and
./build/ipsec-secgw [EAL options] --
- -p PORTMASK -P -u PORTMASK
+ -p PORTMASK -P -u PORTMASK -j FRAMESIZE
--config (port,queue,lcore)[,(port,queue,lcore]
--single-sa SAIDX
-f CONFIG_FILE_PATH
* ``-u PORTMASK``: hexadecimal bitmask of unprotected ports
+* ``-j FRAMESIZE``: *optional*. Enables jumbo frames with the maximum size
+ specified as FRAMESIZE. If an invalid value is provided as FRAMESIZE
+ then the default value 9000 is used.
+
* ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues
from which ports are mapped to which cores.
For example, given the following command line::
./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \
- --vdev "cryptodev_null_pmd" -- -p 0xf -P -u 0x3 \
+ --vdev "crypto_null" -- -p 0xf -P -u 0x3 \
--config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \
-f /path/to/config_file \
* The ``--socket-mem`` to use 2GB on socket 1.
-* The ``--vdev "cryptodev_null_pmd"`` option creates virtual NULL cryptodev PMD.
+* The ``--vdev "crypto_null"`` option creates virtual NULL cryptodev PMD.
* The ``-p`` option enables ports (detected) 0, 1, 2 and 3.
./build/ipsec-secgw -l 20,21 -n 4 --socket-mem 0,2048 \
-w 81:00.0 -w 81:00.1 -w 81:00.2 -w 81:00.3 \
- --vdev "cryptodev_aesni_mb_pmd" --vdev "cryptodev_null_pmd" \
+ --vdev "crypto_aesni_mb" --vdev "crypto_null" \
-- \
-p 0xf -P -u 0x3 --config="(0,0,20),(1,0,20),(2,0,21),(3,0,21)" \
-f sample.cfg
.. code-block:: console
sa <dir> <spi> <cipher_algo> <cipher_key> <auth_algo> <auth_key>
- <mode> <src_ip> <dst_ip>
+ <mode> <src_ip> <dst_ip> <action_type> <port_id>
where each options means:
* Cipher algorithm
- * Optional: No
+ * Optional: Yes, unless <aead_algo> is not used
* Available options:
* *null*: NULL algorithm
* *aes-128-cbc*: AES-CBC 128-bit algorithm
+ * *aes-256-cbc*: AES-CBC 256-bit algorithm
* *aes-128-ctr*: AES-CTR 128-bit algorithm
- * *aes-128-gcm*: AES-GCM 128-bit algorithm
* Syntax: *cipher_algo <your algorithm>*
* Cipher key, NOT available when 'null' algorithm is used
- * Optional: No, must followed by <cipher_algo> option
+ * Optional: Yes, unless <aead_algo> is not used.
+ Must be followed by <cipher_algo> option
* Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
The number of bytes should be as same as the specified cipher algorithm
* Authentication algorithm
- * Optional: No
+ * Optional: Yes, unless <aead_algo> is not used
* Available options:
* *null*: NULL algorithm
* *sha1-hmac*: HMAC SHA1 algorithm
- * *aes-128-gcm*: AES-GCM 128-bit algorithm
``<auth_key>``
* Authentication key, NOT available when 'null' or 'aes-128-gcm' algorithm
is used.
- * Optional: No, must followed by <auth_algo> option
+ * Optional: Yes, unless <aead_algo> is not used.
+ Must be followed by <auth_algo> option
* Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
The number of bytes should be as same as the specified authentication
For example: *auth_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
A1:B2:C3:D4*
+``<aead_algo>``
+
+ * AEAD algorithm
+
+ * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used
+
+ * Available options:
+
+ * *aes-128-gcm*: AES-GCM 128-bit algorithm
+
+ * Syntax: *cipher_algo <your algorithm>*
+
+``<aead_key>``
+
+ * Cipher key, NOT available when 'null' algorithm is used
+
+ * Optional: Yes, unless <cipher_algo> and <auth_algo> are not used.
+ Must be followed by <aead_algo> option
+
+ * Syntax: Hexadecimal bytes (0x0-0xFF) concatenate by colon symbol ':'.
+ The number of bytes should be as same as the specified AEAD algorithm
+ key size.
+
+ For example: *aead_key A1:B2:C3:D4:A1:B2:C3:D4:A1:B2:C3:D4:
+ A1:B2:C3:D4*
+
``<mode>``
* The operation mode
* *dst X.X.X.X* for IPv4
* *dst XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX:XXXX* for IPv6
+``<type>``
+
+ * Action type to specify the security action. This option specify
+ the SA to be performed with look aside protocol offload to HW
+ accelerator or protocol offload on ethernet device or inline
+ crypto processing on the ethernet device during transmission.
+
+ * Optional: Yes, default type *no-offload*
+
+ * Available options:
+
+ * *lookaside-protocol-offload*: look aside protocol offload to HW accelerator
+ * *inline-protocol-offload*: inline protocol offload on ethernet device
+ * *inline-crypto-offload*: inline crypto processing on ethernet device
+ * *no-offload*: no offloading to hardware
+
+ ``<port_id>``
+
+ * Port/device ID of the ethernet/crypto accelerator for which the SA is
+ configured. For *inline-crypto-offload* and *inline-protocol-offload*, this
+ port will be used for routing. The routing table will not be referred in
+ this case.
+
+ * Optional: No, if *type* is not *no-offload*
+
+ * Syntax:
+
+ * *port_id X* X is a valid device number in decimal
+
+
Example SA rules:
.. code-block:: console
src 1111:1111:1111:1111:1111:1111:1111:5555 \
dst 2222:2222:2222:2222:2222:2222:2222:5555
- sa in 105 cipher_algo aes-128-gcm \
- cipher_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
- auth_algo aes-128-gcm \
+ sa in 105 aead_algo aes-128-gcm \
+ aead_key de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef:de:ad:be:ef \
mode ipv4-tunnel src 172.16.2.5 dst 172.16.1.5
+ 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 \
+ 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 \
+ mode ipv4-tunnel src 172.16.1.5 dst 172.16.2.5 \
+ type lookaside-protocol-offload port_id 4
+
Routing rule syntax
^^^^^^^^^^^^^^^^^^^
Code Review / deb_dpdk.git / blobdiff