lib/librte_ipsec/rte_ipsec.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2018-2020 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_IPSEC_H_
   6 #define _RTE_IPSEC_H_
   7
   8 /**
   9  * @file rte_ipsec.h
  10  *
  11  * RTE IPsec support.
  12  *
  13  * @warning
  14  * @b EXPERIMENTAL:
  15  * All functions in this file may be changed or removed without prior notice.
  16  *
  17  * librte_ipsec provides a framework for data-path IPsec protocol
  18  * processing (ESP/AH).
  19  */
  20
  21 #include <rte_ipsec_sa.h>
  22 #include <rte_mbuf.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 struct rte_ipsec_session;
  29
  30 /**
  31  * IPsec session specific functions that will be used to:
  32  * - prepare - for input mbufs and given IPsec session prepare crypto ops
  33  *   that can be enqueued into the cryptodev associated with given session
  34  *   (see *rte_ipsec_pkt_crypto_prepare* below for more details).
  35  * - process - finalize processing of packets after crypto-dev finished
  36  *   with them or process packets that are subjects to inline IPsec offload
  37  *   (see rte_ipsec_pkt_process for more details).
  38  */
  39 struct rte_ipsec_sa_pkt_func {
  40         union {
  41                 uint16_t (*async)(const struct rte_ipsec_session *ss,
  42                                 struct rte_mbuf *mb[],
  43                                 struct rte_crypto_op *cop[],
  44                                 uint16_t num);
  45                 uint16_t (*sync)(const struct rte_ipsec_session *ss,
  46                                 struct rte_mbuf *mb[],
  47                                 uint16_t num);
  48         } prepare;
  49         uint16_t (*process)(const struct rte_ipsec_session *ss,
  50                                 struct rte_mbuf *mb[],
  51                                 uint16_t num);
  52 };
  53
  54 /**
  55  * rte_ipsec_session is an aggregate structure that defines particular
  56  * IPsec Security Association IPsec (SA) on given security/crypto device:
  57  * - pointer to the SA object
  58  * - security session action type
  59  * - pointer to security/crypto session, plus other related data
  60  * - session/device specific functions to prepare/process IPsec packets.
  61  */
  62 struct rte_ipsec_session {
  63         /**
  64          * SA that session belongs to.
  65          * Note that multiple sessions can belong to the same SA.
  66          */
  67         struct rte_ipsec_sa *sa;
  68         /** session action type */
  69         enum rte_security_session_action_type type;
  70         /** session and related data */
  71         union {
  72                 struct {
  73                         struct rte_cryptodev_sym_session *ses;
  74                         uint8_t dev_id;
  75                 } crypto;
  76                 struct {
  77                         struct rte_security_session *ses;
  78                         struct rte_security_ctx *ctx;
  79                         uint32_t ol_flags;
  80                 } security;
  81         };
  82         /** functions to prepare/process IPsec packets */
  83         struct rte_ipsec_sa_pkt_func pkt_func;
  84 } __rte_cache_aligned;
  85
  86 /**
  87  * Checks that inside given rte_ipsec_session crypto/security fields
  88  * are filled correctly and setups function pointers based on these values.
  89  * Expects that all fields except IPsec processing function pointers
  90  * (*pkt_func*) will be filled correctly by caller.
  91  * @param ss
  92  *   Pointer to the *rte_ipsec_session* object
  93  * @return
  94  *   - Zero if operation completed successfully.
  95  *   - -EINVAL if the parameters are invalid.
  96  */
  97 __rte_experimental
  98 int
  99 rte_ipsec_session_prepare(struct rte_ipsec_session *ss);
 100
 101 /**
 102  * For input mbufs and given IPsec session prepare crypto ops that can be
 103  * enqueued into the cryptodev associated with given session.
 104  * expects that for each input packet:
 105  *      - l2_len, l3_len are setup correctly
 106  * Note that erroneous mbufs are not freed by the function,
 107  * but are placed beyond last valid mbuf in the *mb* array.
 108  * It is a user responsibility to handle them further.
 109  * @param ss
 110  *   Pointer to the *rte_ipsec_session* object the packets belong to.
 111  * @param mb
 112  *   The address of an array of *num* pointers to *rte_mbuf* structures
 113  *   which contain the input packets.
 114  * @param cop
 115  *   The address of an array of *num* pointers to the output *rte_crypto_op*
 116  *   structures.
 117  * @param num
 118  *   The maximum number of packets to process.
 119  * @return
 120  *   Number of successfully processed packets, with error code set in rte_errno.
 121  */
 122 __rte_experimental
 123 static inline uint16_t
 124 rte_ipsec_pkt_crypto_prepare(const struct rte_ipsec_session *ss,
 125         struct rte_mbuf *mb[], struct rte_crypto_op *cop[], uint16_t num)
 126 {
 127         return ss->pkt_func.prepare.async(ss, mb, cop, num);
 128 }
 129
 130 __rte_experimental
 131 static inline uint16_t
 132 rte_ipsec_pkt_cpu_prepare(const struct rte_ipsec_session *ss,
 133         struct rte_mbuf *mb[], uint16_t num)
 134 {
 135         return ss->pkt_func.prepare.sync(ss, mb, num);
 136 }
 137
 138 /**
 139  * Finalise processing of packets after crypto-dev finished with them or
 140  * process packets that are subjects to inline IPsec offload.
 141  * Expects that for each input packet:
 142  *      - l2_len, l3_len are setup correctly
 143  * Output mbufs will be:
 144  * inbound - decrypted & authenticated, ESP(AH) related headers removed,
 145  * *l2_len* and *l3_len* fields are updated.
 146  * outbound - appropriate mbuf fields (ol_flags, tx_offloads, etc.)
 147  * properly setup, if necessary - IP headers updated, ESP(AH) fields added,
 148  * Note that erroneous mbufs are not freed by the function,
 149  * but are placed beyond last valid mbuf in the *mb* array.
 150  * It is a user responsibility to handle them further.
 151  * @param ss
 152  *   Pointer to the *rte_ipsec_session* object the packets belong to.
 153  * @param mb
 154  *   The address of an array of *num* pointers to *rte_mbuf* structures
 155  *   which contain the input packets.
 156  * @param num
 157  *   The maximum number of packets to process.
 158  * @return
 159  *   Number of successfully processed packets, with error code set in rte_errno.
 160  */
 161 __rte_experimental
 162 static inline uint16_t
 163 rte_ipsec_pkt_process(const struct rte_ipsec_session *ss, struct rte_mbuf *mb[],
 164         uint16_t num)
 165 {
 166         return ss->pkt_func.process(ss, mb, num);
 167 }
 168
 169 #include <rte_ipsec_group.h>
 170
 171 #ifdef __cplusplus
 172 }
 173 #endif
 174
 175 #endif /* _RTE_IPSEC_H_ */