doc/guides/prog_guide/ipsec_lib.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 IPsec Packet Processing Library
   5 ===============================
   6
   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
  13 for this library.
  14
  15 SA level API
  16 ------------
  17
  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.
  21
  22 To be more specific:
  23
  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.
  28
  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.
  31
  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
  34 the crypto-device.
  35
  36 The expected API call sequence for data-path processing would be:
  37
  38 .. code-block:: c
  39
  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(...);
  47
  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.
  51
  52 .. note::
  53
  54     For more details about the IPsec API, please refer to the *DPDK API Reference*.
  55
  56 The current implementation supports all four currently defined
  57 rte_security types:
  58
  59 RTE_SECURITY_ACTION_TYPE_NONE
  60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  61
  62 In that mode the library functions perform
  63
  64 * for inbound packets:
  65
  66   - check SQN
  67   - prepare *rte_crypto_op* structure for each input packet
  68   - verify that integity check and decryption performed by crypto device
  69     completed successfully
  70   - check padding data
  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
  74
  75 * for outbound packets:
  76
  77   - generate SQN and IV
  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
  83
  84 RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  86
  87 In that mode the library functions perform
  88
  89 * for inbound packets:
  90
  91   - verify that integity check and decryption performed by *rte_security*
  92     device completed successfully
  93   - check SQN
  94   - check padding data
  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
  98
  99 * for outbound packets:
 100
 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 inidicate 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     secuirty device specific data with the packet
 108
 109 RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL
 110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 111
 112 In that mode the library functions perform
 113
 114 * for inbound packets:
 115
 116   - verify that integity check and decryption performed by *rte_security*
 117     device completed successfully
 118
 119 * for outbound packets:
 120
 121   - update *ol_flags* inside *struct  rte_mbuf* to inidicate 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     secuirty device specific data with the packet
 125
 126 RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
 127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 128
 129 In that mode the library functions perform
 130
 131 * for inbound packets:
 132
 133   - prepare *rte_crypto_op* structure for each input packet
 134   - verify that integity check and decryption performed by crypto device
 135     completed successfully
 136
 137 * for outbound packets:
 138
 139   - prepare *rte_crypto_op* structure for each input packet
 140   - verify that crypto device operations (encryption, ICV generation)
 141     were completed successfully
 142
 143 To accommodate future custom implementations function pointers
 144 model is used for both *crypto_prepare* and *process* implementations.
 145
 146
 147 Supported features
 148 ------------------
 149
 150 *  ESP protocol tunnel mode both IPv4/IPv6.
 151
 152 *  ESP protocol transport mode both IPv4/IPv6.
 153
 154 *  ESN and replay window.
 155
 156 *  algorithms: 3DES-CBC, AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1, NULL.
 157
 158
 159 Limitations
 160 -----------
 161
 162 The following features are not properly supported in the current version:
 163
 164 *  ESP transport mode for IPv6 packets with extension headers.
 165 *  Multi-segment packets.
 166 *  Updates of the fields in inner IP header for tunnel mode
 167    (as described in RFC 4301, section 5.1.2).
 168 *  Hard/soft limit for SA lifetime (time interval/byte count).