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