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 162 /** 163 * Enable per SA telemetry for a specific SA. 164 * Note that this function is not thread safe 165 * @param sa 166 * Pointer to the *rte_ipsec_sa* object that will have telemetry enabled. 167 * @return 168 * 0 on success, negative value otherwise. 169 */ 170 __rte_experimental 171 int 172 rte_ipsec_telemetry_sa_add(const struct rte_ipsec_sa *sa); 173 174 /** 175 * Disable per SA telemetry for a specific SA. 176 * Note that this function is not thread safe 177 * @param sa 178 * Pointer to the *rte_ipsec_sa* object that will have telemetry disabled. 179 */ 180 __rte_experimental 181 void 182 rte_ipsec_telemetry_sa_del(const struct rte_ipsec_sa *sa); 183 184 #include <rte_ipsec_group.h> 185 186 #ifdef __cplusplus 187 } 188 #endif 189 190 #endif /* _RTE_IPSEC_H_ */ 191