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