.. SPDX-License-Identifier: BSD-3-Clause
- Copyright(c) 2018 Intel Corporation.
+ Copyright(c) 2018-2020 Intel Corporation.
IPsec Packet Processing Library
===============================
- check SQN
- prepare *rte_crypto_op* structure for each input packet
- - verify that integity check and decryption performed by crypto device
+ - verify that integrity check and decryption performed by crypto device
completed successfully
- check padding data
- remove outer IP header (tunnel mode) / update IP header (transport mode)
- verify that crypto device operations (encryption, ICV generation)
were completed successfully
+RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In that mode the library functions perform same operations as in
+``RTE_SECURITY_ACTION_TYPE_NONE``. The only difference is that crypto operations
+are performed with CPU crypto synchronous API.
+
+
RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* for inbound packets:
- - verify that integity check and decryption performed by *rte_security*
+ - verify that integrity check and decryption performed by *rte_security*
device completed successfully
- check SQN
- check padding data
- generate SQN and IV
- add outer IP header (tunnel mode) / update IP header (transport mode)
- add ESP header and trailer, padding and IV data
- - update *ol_flags* inside *struct rte_mbuf* to inidicate that
+ - update *ol_flags* inside *struct rte_mbuf* to indicate that
inline-crypto processing has to be performed by HW on this packet
- invoke *rte_security* device specific *set_pkt_metadata()* to associate
- secuirty device specific data with the packet
+ security device specific data with the packet
RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* for inbound packets:
- - verify that integity check and decryption performed by *rte_security*
+ - verify that integrity check and decryption performed by *rte_security*
device completed successfully
* for outbound packets:
- - update *ol_flags* inside *struct rte_mbuf* to inidicate that
+ - update *ol_flags* inside *struct rte_mbuf* to indicate that
inline-crypto processing has to be performed by HW on this packet
- invoke *rte_security* device specific *set_pkt_metadata()* to associate
- secuirty device specific data with the packet
+ security device specific data with the packet
RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* for inbound packets:
- prepare *rte_crypto_op* structure for each input packet
- - verify that integity check and decryption performed by crypto device
+ - verify that integrity check and decryption performed by crypto device
completed successfully
* for outbound packets:
To accommodate future custom implementations function pointers
model is used for both *crypto_prepare* and *process* implementations.
+SA database API
+----------------
+
+SA database(SAD) is a table with <key, value> pairs.
+
+Value is an opaque user provided pointer to the user defined SA data structure.
+
+According to RFC4301 each SA can be uniquely identified by a key
+which is either:
+
+ - security parameter index(SPI)
+ - or SPI and destination IP(DIP)
+ - or SPI, DIP and source IP(SIP)
+
+In case of multiple matches, longest matching key will be returned.
+
+Create/destroy
+~~~~~~~~~~~~~~
+
+librte_ipsec SAD implementation provides ability to create/destroy SAD tables.
+
+To create SAD table user has to specify how many entries of each key type is
+required and IP protocol type (IPv4/IPv6).
+As an example:
+
+
+.. code-block:: c
+
+ struct rte_ipsec_sad *sad;
+ struct rte_ipsec_sad_conf conf;
+
+ conf.socket_id = -1;
+ conf.max_sa[RTE_IPSEC_SAD_SPI_ONLY] = some_nb_rules_spi_only;
+ conf.max_sa[RTE_IPSEC_SAD_SPI_DIP] = some_nb_rules_spi_dip;
+ conf.max_sa[RTE_IPSEC_SAD_SPI_DIP_SIP] = some_nb_rules_spi_dip_sip;
+ conf.flags = RTE_IPSEC_SAD_FLAG_RW_CONCURRENCY;
+
+ sad = rte_ipsec_sad_create("test", &conf);
+
+.. note::
+
+ for more information please refer to ipsec library API reference
+
+Add/delete rules
+~~~~~~~~~~~~~~~~
+
+Library also provides methods to add or delete key/value pairs from the SAD.
+To add user has to specify key, key type and a value which is an opaque pointer to SA.
+The key type reflects a set of tuple fields that will be used for lookup of the SA.
+As mentioned above there are 3 types of a key and the representation of a key type is:
+
+.. code-block:: c
+
+ RTE_IPSEC_SAD_SPI_ONLY,
+ RTE_IPSEC_SAD_SPI_DIP,
+ RTE_IPSEC_SAD_SPI_DIP_SIP,
+
+As an example, to add new entry into the SAD for IPv4 addresses:
+
+.. code-block:: c
+
+ struct rte_ipsec_sa *sa;
+ union rte_ipsec_sad_key key;
+
+ key.v4.spi = rte_cpu_to_be_32(spi_val);
+ if (key_type >= RTE_IPSEC_SAD_SPI_DIP) /* DIP is optional*/
+ key.v4.dip = rte_cpu_to_be_32(dip_val);
+ if (key_type == RTE_IPSEC_SAD_SPI_DIP_SIP) /* SIP is optional*/
+ key.v4.sip = rte_cpu_to_be_32(sip_val);
+
+ rte_ipsec_sad_add(sad, &key, key_type, sa);
+
+.. note::
+
+ By performance reason it is better to keep spi/dip/sip in net byte order
+ to eliminate byteswap on lookup
+
+To delete user has to specify key and key type.
+
+Delete code would look like:
+
+.. code-block:: c
+
+ union rte_ipsec_sad_key key;
+
+ key.v4.spi = rte_cpu_to_be_32(necessary_spi);
+ if (key_type >= RTE_IPSEC_SAD_SPI_DIP) /* DIP is optional*/
+ key.v4.dip = rte_cpu_to_be_32(necessary_dip);
+ if (key_type == RTE_IPSEC_SAD_SPI_DIP_SIP) /* SIP is optional*/
+ key.v4.sip = rte_cpu_to_be_32(necessary_sip);
+
+ rte_ipsec_sad_del(sad, &key, key_type);
+
+
+Lookup
+~~~~~~
+Library provides lookup by the given {SPI,DIP,SIP} tuple of
+inbound ipsec packet as a key.
+
+The search key is represented by:
+
+.. code-block:: c
+
+ union rte_ipsec_sad_key {
+ struct rte_ipsec_sadv4_key v4;
+ struct rte_ipsec_sadv6_key v6;
+ };
+
+where v4 is a tuple for IPv4:
+
+.. code-block:: c
+
+ struct rte_ipsec_sadv4_key {
+ uint32_t spi;
+ uint32_t dip;
+ uint32_t sip;
+ };
+
+and v6 is a tuple for IPv6:
+
+.. code-block:: c
+
+ struct rte_ipsec_sadv6_key {
+ uint32_t spi;
+ uint8_t dip[16];
+ uint8_t sip[16];
+ };
+
+As an example, lookup related code could look like that:
+
+.. code-block:: c
+
+ int i;
+ union rte_ipsec_sad_key keys[BURST_SZ];
+ const union rte_ipsec_sad_key *keys_p[BURST_SZ];
+ void *vals[BURST_SZ];
+
+ for (i = 0; i < BURST_SZ_MAX; i++) {
+ keys[i].v4.spi = esp_hdr[i]->spi;
+ keys[i].v4.dip = ipv4_hdr[i]->dst_addr;
+ keys[i].v4.sip = ipv4_hdr[i]->src_addr;
+ keys_p[i] = &keys[i];
+ }
+ rte_ipsec_sad_lookup(sad, keys_p, vals, BURST_SZ);
+
+ for (i = 0; i < BURST_SZ_MAX; i++) {
+ if (vals[i] == NULL)
+ printf("SA not found for key index %d\n", i);
+ else
+ printf("SA pointer is %p\n", vals[i]);
+ }
+
Supported features
------------------
* ESN and replay window.
-* algorithms: AES-CBC, AES-GCM, HMAC-SHA1, NULL.
+* algorithms: 3DES-CBC, AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1, NULL.
Limitations
The following features are not properly supported in the current version:
-* ESP transport mode for IPv6 packets with extension headers.
-* Multi-segment packets.
-* Updates of the fields in inner IP header for tunnel mode
- (as described in RFC 4301, section 5.1.2).
* Hard/soft limit for SA lifetime (time interval/byte count).
git.droids-corp.org / dpdk.git / blobdiff