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 integrity 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 integrity 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 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
 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 integrity 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 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
 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 integrity 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 SA database API
 147 ----------------
 148
 149 SA database(SAD) is a table with <key, value> pairs.
 150
 151 Value is an opaque user provided pointer to the user defined SA data structure.
 152
 153 According to RFC4301 each SA can be uniquely identified by a key
 154 which is either:
 155
 156   - security parameter index(SPI)
 157   - or SPI and destination IP(DIP)
 158   - or SPI, DIP and source IP(SIP)
 159
 160 In case of multiple matches, longest matching key will be returned.
 161
 162 Create/destroy
 163 ~~~~~~~~~~~~~~
 164
 165 librte_ipsec SAD implementation provides ability to create/destroy SAD tables.
 166
 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).
 169 As an example:
 170
 171
 172 .. code-block:: c
 173
 174     struct rte_ipsec_sad *sad;
 175     struct rte_ipsec_sad_conf conf;
 176
 177     conf.socket_id = -1;
 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;
 182
 183     sad = rte_ipsec_sad_create("test", &conf);
 184
 185 .. note::
 186
 187     for more information please refer to ipsec library API reference
 188
 189 Supported features
 190 ------------------
 191
 192 *  ESP protocol tunnel mode both IPv4/IPv6.
 193
 194 *  ESP protocol transport mode both IPv4/IPv6.
 195
 196 *  ESN and replay window.
 197
 198 *  algorithms: 3DES-CBC, AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1, NULL.
 199
 200
 201 Limitations
 202 -----------
 203
 204 The following features are not properly supported in the current version:
 205
 206 *  Hard/soft limit for SA lifetime (time interval/byte count).