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_compat.h> 18 #include <rte_ipsec_sa.h> 19 #include <rte_mbuf.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 struct rte_ipsec_session; 26 27 /** 28 * IPsec session specific functions that will be used to: 29 * - prepare - for input mbufs and given IPsec session prepare crypto ops 30 * that can be enqueued into the cryptodev associated with given session 31 * (see *rte_ipsec_pkt_crypto_prepare* below for more details). 32 * - process - finalize processing of packets after crypto-dev finished 33 * with them or process packets that are subjects to inline IPsec offload 34 * (see rte_ipsec_pkt_process for more details). 35 */ 36 struct rte_ipsec_sa_pkt_func { 37 union { 38 uint16_t (*async)(const struct rte_ipsec_session *ss, 39 struct rte_mbuf *mb[], 40 struct rte_crypto_op *cop[], 41 uint16_t num); 42 uint16_t (*sync)(const struct rte_ipsec_session *ss, 43 struct rte_mbuf *mb[], 44 uint16_t num); 45 } prepare; 46 uint16_t (*process)(const struct rte_ipsec_session *ss, 47 struct rte_mbuf *mb[], 48 uint16_t num); 49 }; 50 51 /** 52 * rte_ipsec_session is an aggregate structure that defines particular 53 * IPsec Security Association IPsec (SA) on given security/crypto device: 54 * - pointer to the SA object 55 * - security session action type 56 * - pointer to security/crypto session, plus other related data 57 * - session/device specific functions to prepare/process IPsec packets. 58 */ 59 struct rte_ipsec_session { 60 /** 61 * SA that session belongs to. 62 * Note that multiple sessions can belong to the same SA. 63 */ 64 struct rte_ipsec_sa *sa; 65 /** session action type */ 66 enum rte_security_session_action_type type; 67 /** session and related data */ 68 union { 69 struct { 70 struct rte_cryptodev_sym_session *ses; 71 uint8_t dev_id; 72 } crypto; 73 struct { 74 struct rte_security_session *ses; 75 struct rte_security_ctx *ctx; 76 uint32_t ol_flags; 77 } security; 78 }; 79 /** functions to prepare/process IPsec packets */ 80 struct rte_ipsec_sa_pkt_func pkt_func; 81 } __rte_cache_aligned; 82 83 /** 84 * Checks that inside given rte_ipsec_session crypto/security fields 85 * are filled correctly and setups function pointers based on these values. 86 * Expects that all fields except IPsec processing function pointers 87 * (*pkt_func*) will be filled correctly by caller. 88 * @param ss 89 * Pointer to the *rte_ipsec_session* object 90 * @return 91 * - Zero if operation completed successfully. 92 * - -EINVAL if the parameters are invalid. 93 */ 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 static inline uint16_t 119 rte_ipsec_pkt_crypto_prepare(const struct rte_ipsec_session *ss, 120 struct rte_mbuf *mb[], struct rte_crypto_op *cop[], uint16_t num) 121 { 122 return ss->pkt_func.prepare.async(ss, mb, cop, num); 123 } 124 125 static inline uint16_t 126 rte_ipsec_pkt_cpu_prepare(const struct rte_ipsec_session *ss, 127 struct rte_mbuf *mb[], uint16_t num) 128 { 129 return ss->pkt_func.prepare.sync(ss, mb, num); 130 } 131 132 /** 133 * Finalise processing of packets after crypto-dev finished with them or 134 * process packets that are subjects to inline IPsec offload. 135 * Expects that for each input packet: 136 * - l2_len, l3_len are setup correctly 137 * Output mbufs will be: 138 * inbound - decrypted & authenticated, ESP(AH) related headers removed, 139 * *l2_len* and *l3_len* fields are updated. 140 * outbound - appropriate mbuf fields (ol_flags, tx_offloads, etc.) 141 * properly setup, if necessary - IP headers updated, ESP(AH) fields added, 142 * Note that erroneous mbufs are not freed by the function, 143 * but are placed beyond last valid mbuf in the *mb* array. 144 * It is a user responsibility to handle them further. 145 * @param ss 146 * Pointer to the *rte_ipsec_session* object the packets belong to. 147 * @param mb 148 * The address of an array of *num* pointers to *rte_mbuf* structures 149 * which contain the input packets. 150 * @param num 151 * The maximum number of packets to process. 152 * @return 153 * Number of successfully processed packets, with error code set in rte_errno. 154 */ 155 static inline uint16_t 156 rte_ipsec_pkt_process(const struct rte_ipsec_session *ss, struct rte_mbuf *mb[], 157 uint16_t num) 158 { 159 return ss->pkt_func.process(ss, mb, num); 160 } 161 162 163 /** 164 * Enable per SA telemetry for a specific SA. 165 * Note that this function is not thread safe 166 * @param sa 167 * Pointer to the *rte_ipsec_sa* object that will have telemetry enabled. 168 * @return 169 * 0 on success, negative value otherwise. 170 */ 171 __rte_experimental 172 int 173 rte_ipsec_telemetry_sa_add(const struct rte_ipsec_sa *sa); 174 175 /** 176 * Disable per SA telemetry for a specific SA. 177 * Note that this function is not thread safe 178 * @param sa 179 * Pointer to the *rte_ipsec_sa* object that will have telemetry disabled. 180 */ 181 __rte_experimental 182 void 183 rte_ipsec_telemetry_sa_del(const struct rte_ipsec_sa *sa); 184 185 #include <rte_ipsec_group.h> 186 187 #ifdef __cplusplus 188 } 189 #endif 190 191 #endif /* _RTE_IPSEC_H_ */ 192