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 int __rte_experimental
  88 rte_ipsec_session_prepare(struct rte_ipsec_session *ss);
  89
  90 /**
  91  * For input mbufs and given IPsec session prepare crypto ops that can be
  92  * enqueued into the cryptodev associated with given session.
  93  * expects that for each input packet:
  94  *      - l2_len, l3_len are setup correctly
  95  * Note that erroneous mbufs are not freed by the function,
  96  * but are placed beyond last valid mbuf in the *mb* array.
  97  * It is a user responsibility to handle them further.
  98  * @param ss
  99  *   Pointer to the *rte_ipsec_session* object the packets belong to.
 100  * @param mb
 101  *   The address of an array of *num* pointers to *rte_mbuf* structures
 102  *   which contain the input packets.
 103  * @param cop
 104  *   The address of an array of *num* pointers to the output *rte_crypto_op*
 105  *   structures.
 106  * @param num
 107  *   The maximum number of packets to process.
 108  * @return
 109  *   Number of successfully processed packets, with error code set in rte_errno.
 110  */
 111 static inline uint16_t __rte_experimental
 112 rte_ipsec_pkt_crypto_prepare(const struct rte_ipsec_session *ss,
 113         struct rte_mbuf *mb[], struct rte_crypto_op *cop[], uint16_t num)
 114 {
 115         return ss->pkt_func.prepare(ss, mb, cop, num);
 116 }
 117
 118 /**
 119  * Finalise processing of packets after crypto-dev finished with them or
 120  * process packets that are subjects to inline IPsec offload.
 121  * Expects that for each input packet:
 122  *      - l2_len, l3_len are setup correctly
 123  * Output mbufs will be:
 124  * inbound - decrypted & authenticated, ESP(AH) related headers removed,
 125  * *l2_len* and *l3_len* fields are updated.
 126  * outbound - appropriate mbuf fields (ol_flags, tx_offloads, etc.)
 127  * properly setup, if necessary - IP headers updated, ESP(AH) fields added,
 128  * Note that erroneous mbufs are not freed by the function,
 129  * but are placed beyond last valid mbuf in the *mb* array.
 130  * It is a user responsibility to handle them further.
 131  * @param ss
 132  *   Pointer to the *rte_ipsec_session* object the packets belong to.
 133  * @param mb
 134  *   The address of an array of *num* pointers to *rte_mbuf* structures
 135  *   which contain the input packets.
 136  * @param num
 137  *   The maximum number of packets to process.
 138  * @return
 139  *   Number of successfully processed packets, with error code set in rte_errno.
 140  */
 141 static inline uint16_t __rte_experimental
 142 rte_ipsec_pkt_process(const struct rte_ipsec_session *ss, struct rte_mbuf *mb[],
 143         uint16_t num)
 144 {
 145         return ss->pkt_func.process(ss, mb, num);
 146 }
 147
 148 #ifdef __cplusplus
 149 }
 150 #endif
 151
 152 #endif /* _RTE_IPSEC_H_ */