lib/librte_ipsec/rte_ipsec.h

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