1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2018 Intel Corporation.
4 IPsec Packet Processing Library
5 ===============================
7 DPDK provides a library for IPsec data-path processing.
8 The library utilizes the existing DPDK crypto-dev and
9 security API to provide the application with a transparent and
10 high performant IPsec packet processing API.
11 The library is concentrated on data-path protocols processing
12 (ESP and AH), IKE protocol(s) implementation is out of scope
18 This API operates on the IPsec Security Association (SA) level.
19 It provides functionality that allows user for given SA to process
20 inbound and outbound IPsec packets.
24 * for inbound ESP/AH packets perform decryption, authentication, integrity checking, remove ESP/AH related headers
25 * for outbound packets perform payload encryption, attach ICV, update/add IP headers, add ESP/AH headers/trailers,
26 * setup related mbuf fields (ol_flags, tx_offloads, etc.).
27 * initialize/un-initialize given SA based on user provided parameters.
29 The SA level API is based on top of crypto-dev/security API and relies on
30 them to perform actual cipher and integrity checking.
32 Due to the nature of the crypto-dev API (enqueue/dequeue model) the library
33 introduces an asynchronous API for IPsec packets destined to be processed by
36 The expected API call sequence for data-path processing would be:
40 /* enqueue for processing by crypto-device */
41 rte_ipsec_pkt_crypto_prepare(...);
42 rte_cryptodev_enqueue_burst(...);
43 /* dequeue from crypto-device and do final processing (if any) */
44 rte_cryptodev_dequeue_burst(...);
45 rte_ipsec_pkt_crypto_group(...); /* optional */
46 rte_ipsec_pkt_process(...);
48 For packets destined for inline processing no extra overhead
49 is required and the synchronous API call: rte_ipsec_pkt_process()
50 is sufficient for that case.
54 For more details about the IPsec API, please refer to the *DPDK API Reference*.
56 The current implementation supports all four currently defined
59 RTE_SECURITY_ACTION_TYPE_NONE
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62 In that mode the library functions perform
64 * for inbound packets:
67 - prepare *rte_crypto_op* structure for each input packet
68 - verify that integrity check and decryption performed by crypto device
69 completed successfully
71 - remove outer IP header (tunnel mode) / update IP header (transport mode)
72 - remove ESP header and trailer, padding, IV and ICV data
73 - update SA replay window
75 * for outbound packets:
78 - add outer IP header (tunnel mode) / update IP header (transport mode)
79 - add ESP header and trailer, padding and IV data
80 - prepare *rte_crypto_op* structure for each input packet
81 - verify that crypto device operations (encryption, ICV generation)
82 were completed successfully
84 RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO
85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87 In that mode the library functions perform
89 * for inbound packets:
91 - verify that integrity check and decryption performed by *rte_security*
92 device completed successfully
95 - remove outer IP header (tunnel mode) / update IP header (transport mode)
96 - remove ESP header and trailer, padding, IV and ICV data
97 - update SA replay window
99 * for outbound packets:
101 - generate SQN and IV
102 - add outer IP header (tunnel mode) / update IP header (transport mode)
103 - add ESP header and trailer, padding and IV data
104 - update *ol_flags* inside *struct rte_mbuf* to indicate that
105 inline-crypto processing has to be performed by HW on this packet
106 - invoke *rte_security* device specific *set_pkt_metadata()* to associate
107 security device specific data with the packet
109 RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL
110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112 In that mode the library functions perform
114 * for inbound packets:
116 - verify that integrity check and decryption performed by *rte_security*
117 device completed successfully
119 * for outbound packets:
121 - update *ol_flags* inside *struct rte_mbuf* to indicate that
122 inline-crypto processing has to be performed by HW on this packet
123 - invoke *rte_security* device specific *set_pkt_metadata()* to associate
124 security device specific data with the packet
126 RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129 In that mode the library functions perform
131 * for inbound packets:
133 - prepare *rte_crypto_op* structure for each input packet
134 - verify that integrity check and decryption performed by crypto device
135 completed successfully
137 * for outbound packets:
139 - prepare *rte_crypto_op* structure for each input packet
140 - verify that crypto device operations (encryption, ICV generation)
141 were completed successfully
143 To accommodate future custom implementations function pointers
144 model is used for both *crypto_prepare* and *process* implementations.
149 SA database(SAD) is a table with <key, value> pairs.
151 Value is an opaque user provided pointer to the user defined SA data structure.
153 According to RFC4301 each SA can be uniquely identified by a key
156 - security parameter index(SPI)
157 - or SPI and destination IP(DIP)
158 - or SPI, DIP and source IP(SIP)
160 In case of multiple matches, longest matching key will be returned.
165 librte_ipsec SAD implementation provides ability to create/destroy SAD tables.
167 To create SAD table user has to specify how many entries of each key type is
168 required and IP protocol type (IPv4/IPv6).
174 struct rte_ipsec_sad *sad;
175 struct rte_ipsec_sad_conf conf;
178 conf.max_sa[RTE_IPSEC_SAD_SPI_ONLY] = some_nb_rules_spi_only;
179 conf.max_sa[RTE_IPSEC_SAD_SPI_DIP] = some_nb_rules_spi_dip;
180 conf.max_sa[RTE_IPSEC_SAD_SPI_DIP_SIP] = some_nb_rules_spi_dip_sip;
181 conf.flags = RTE_IPSEC_SAD_FLAG_RW_CONCURRENCY;
183 sad = rte_ipsec_sad_create("test", &conf);
187 for more information please refer to ipsec library API reference
192 Library also provides methods to add or delete key/value pairs from the SAD.
193 To add user has to specify key, key type and a value which is an opaque pointer to SA.
194 The key type reflects a set of tuple fields that will be used for lookup of the SA.
195 As mentioned above there are 3 types of a key and the representation of a key type is:
199 RTE_IPSEC_SAD_SPI_ONLY,
200 RTE_IPSEC_SAD_SPI_DIP,
201 RTE_IPSEC_SAD_SPI_DIP_SIP,
203 As an example, to add new entry into the SAD for IPv4 addresses:
207 struct rte_ipsec_sa *sa;
208 union rte_ipsec_sad_key key;
210 key.v4.spi = rte_cpu_to_be_32(spi_val);
211 if (key_type >= RTE_IPSEC_SAD_SPI_DIP) /* DIP is optional*/
212 key.v4.dip = rte_cpu_to_be_32(dip_val);
213 if (key_type == RTE_IPSEC_SAD_SPI_DIP_SIP) /* SIP is optional*/
214 key.v4.sip = rte_cpu_to_be_32(sip_val);
216 rte_ipsec_sad_add(sad, &key, key_type, sa);
220 By performance reason it is better to keep spi/dip/sip in net byte order
221 to eliminate byteswap on lookup
223 To delete user has to specify key and key type.
225 Delete code would look like:
229 union rte_ipsec_sad_key key;
231 key.v4.spi = rte_cpu_to_be_32(necessary_spi);
232 if (key_type >= RTE_IPSEC_SAD_SPI_DIP) /* DIP is optional*/
233 key.v4.dip = rte_cpu_to_be_32(necessary_dip);
234 if (key_type == RTE_IPSEC_SAD_SPI_DIP_SIP) /* SIP is optional*/
235 key.v4.sip = rte_cpu_to_be_32(necessary_sip);
237 rte_ipsec_sad_del(sad, &key, key_type);
242 Library provides lookup by the given {SPI,DIP,SIP} tuple of
243 inbound ipsec packet as a key.
245 The search key is represented by:
249 union rte_ipsec_sad_key {
250 struct rte_ipsec_sadv4_key v4;
251 struct rte_ipsec_sadv6_key v6;
254 where v4 is a tuple for IPv4:
258 struct rte_ipsec_sadv4_key {
264 and v6 is a tuple for IPv6:
268 struct rte_ipsec_sadv6_key {
274 As an example, lookup related code could look like that:
279 union rte_ipsec_sad_key keys[BURST_SZ];
280 const union rte_ipsec_sad_key *keys_p[BURST_SZ];
281 void *vals[BURST_SZ];
283 for (i = 0; i < BURST_SZ_MAX; i++) {
284 keys[i].v4.spi = esp_hdr[i]->spi;
285 keys[i].v4.dip = ipv4_hdr[i]->dst_addr;
286 keys[i].v4.sip = ipv4_hdr[i]->src_addr;
287 keys_p[i] = &keys[i];
289 rte_ipsec_sad_lookup(sad, keys_p, vals, BURST_SZ);
291 for (i = 0; i < BURST_SZ_MAX; i++) {
293 printf("SA not found for key index %d\n", i);
295 printf("SA pointer is %p\n", vals[i]);
302 * ESP protocol tunnel mode both IPv4/IPv6.
304 * ESP protocol transport mode both IPv4/IPv6.
306 * ESN and replay window.
308 * algorithms: 3DES-CBC, AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1, NULL.
314 The following features are not properly supported in the current version:
316 * Hard/soft limit for SA lifetime (time interval/byte count).