Branch data Line data Source code
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 : : struct rte_ipsec_session;
21 : :
22 : : /**
23 : : * IPsec state for stateless processing of a batch of IPsec packets.
24 : : */
25 : : struct rte_ipsec_state {
26 : : /**
27 : : * 64 bit sequence number to be used for the first packet of the
28 : : * batch of packets.
29 : : */
30 : : uint64_t sqn;
31 : : };
32 : :
33 : : /**
34 : : * IPsec session specific functions that will be used to:
35 : : * - prepare - for input mbufs and given IPsec session prepare crypto ops
36 : : * that can be enqueued into the cryptodev associated with given session
37 : : * (see *rte_ipsec_pkt_crypto_prepare* below for more details).
38 : : * - prepare_stateless - similar to prepare, but further processing is done
39 : : * based on IPsec state provided by the 'state' parameter.
40 : : * - process - finalize processing of packets after crypto-dev finished
41 : : * with them or process packets that are subjects to inline IPsec offload
42 : : * (see rte_ipsec_pkt_process for more details).
43 : : */
44 : : struct rte_ipsec_sa_pkt_func {
45 : : union {
46 : : uint16_t (*async)(const struct rte_ipsec_session *ss,
47 : : struct rte_mbuf *mb[],
48 : : struct rte_crypto_op *cop[],
49 : : uint16_t num);
50 : : uint16_t (*sync)(const struct rte_ipsec_session *ss,
51 : : struct rte_mbuf *mb[],
52 : : uint16_t num);
53 : : } prepare;
54 : : union {
55 : : uint16_t (*async)(const struct rte_ipsec_session *ss,
56 : : struct rte_mbuf *mb[],
57 : : struct rte_crypto_op *cop[],
58 : : uint16_t num,
59 : : struct rte_ipsec_state *state);
60 : : uint16_t (*sync)(const struct rte_ipsec_session *ss,
61 : : struct rte_mbuf *mb[],
62 : : uint16_t num,
63 : : struct rte_ipsec_state *state);
64 : : } prepare_stateless;
65 : : uint16_t (*process)(const struct rte_ipsec_session *ss,
66 : : struct rte_mbuf *mb[],
67 : : uint16_t num);
68 : : };
69 : :
70 : : /**
71 : : * rte_ipsec_session is an aggregate structure that defines particular
72 : : * IPsec Security Association IPsec (SA) on given security/crypto device:
73 : : * - pointer to the SA object
74 : : * - security session action type
75 : : * - pointer to security/crypto session, plus other related data
76 : : * - session/device specific functions to prepare/process IPsec packets.
77 : : */
78 : : struct __rte_cache_aligned rte_ipsec_session {
79 : : /**
80 : : * SA that session belongs to.
81 : : * Note that multiple sessions can belong to the same SA.
82 : : */
83 : : struct rte_ipsec_sa *sa;
84 : : /** session action type */
85 : : enum rte_security_session_action_type type;
86 : : /** session and related data */
87 : : union {
88 : : struct {
89 : : struct rte_cryptodev_sym_session *ses;
90 : : uint8_t dev_id;
91 : : } crypto;
92 : : struct {
93 : : struct rte_security_session *ses;
94 : : struct rte_security_ctx *ctx;
95 : : uint32_t ol_flags;
96 : : } security;
97 : : };
98 : : /** functions to prepare/process IPsec packets */
99 : : struct rte_ipsec_sa_pkt_func pkt_func;
100 : : };
101 : :
102 : : /**
103 : : * Checks that inside given rte_ipsec_session crypto/security fields
104 : : * are filled correctly and setups function pointers based on these values.
105 : : * Expects that all fields except IPsec processing function pointers
106 : : * (*pkt_func*) will be filled correctly by caller.
107 : : * @param ss
108 : : * Pointer to the *rte_ipsec_session* object
109 : : * @return
110 : : * - Zero if operation completed successfully.
111 : : * - -EINVAL if the parameters are invalid.
112 : : */
113 : : int
114 : : rte_ipsec_session_prepare(struct rte_ipsec_session *ss);
115 : :
116 : : /**
117 : : * For input mbufs and given IPsec session prepare crypto ops that can be
118 : : * enqueued into the cryptodev associated with given session.
119 : : * expects that for each input packet:
120 : : * - l2_len, l3_len are setup correctly
121 : : * Note that erroneous mbufs are not freed by the function,
122 : : * but are placed beyond last valid mbuf in the *mb* array.
123 : : * It is a user responsibility to handle them further.
124 : : * @param ss
125 : : * Pointer to the *rte_ipsec_session* object the packets belong to.
126 : : * @param mb
127 : : * The address of an array of *num* pointers to *rte_mbuf* structures
128 : : * which contain the input packets.
129 : : * @param cop
130 : : * The address of an array of *num* pointers to the output *rte_crypto_op*
131 : : * structures.
132 : : * @param num
133 : : * The maximum number of packets to process.
134 : : * @return
135 : : * Number of successfully processed packets, with error code set in rte_errno.
136 : : */
137 : : static inline uint16_t
138 : : rte_ipsec_pkt_crypto_prepare(const struct rte_ipsec_session *ss,
139 : : struct rte_mbuf *mb[], struct rte_crypto_op *cop[], uint16_t num)
140 : : {
141 : 0 : return ss->pkt_func.prepare.async(ss, mb, cop, num);
142 : : }
143 : :
144 : : static inline uint16_t
145 : : rte_ipsec_pkt_cpu_prepare(const struct rte_ipsec_session *ss,
146 : : struct rte_mbuf *mb[], uint16_t num)
147 : : {
148 : : return ss->pkt_func.prepare.sync(ss, mb, num);
149 : : }
150 : :
151 : : /**
152 : : * Same as *rte_ipsec_pkt_crypto_prepare*, but processing is done based on
153 : : * IPsec state provided by the 'state' parameter. Internal IPsec state won't
154 : : * be updated when this API is called.
155 : : *
156 : : * For input mbufs and given IPsec session prepare crypto ops that can be
157 : : * enqueued into the cryptodev associated with given session.
158 : : * expects that for each input packet:
159 : : * - l2_len, l3_len are setup correctly
160 : : * Note that erroneous mbufs are not freed by the function,
161 : : * but are placed beyond last valid mbuf in the *mb* array.
162 : : * It is a user responsibility to handle them further.
163 : : * @param ss
164 : : * Pointer to the *rte_ipsec_session* object the packets belong to.
165 : : * @param mb
166 : : * The address of an array of *num* pointers to *rte_mbuf* structures
167 : : * which contain the input packets.
168 : : * @param cop
169 : : * The address of an array of *num* pointers to the output *rte_crypto_op*
170 : : * structures.
171 : : * @param num
172 : : * The maximum number of packets to process.
173 : : * @param state
174 : : * The IPsec state to be used for processing current batch of packets.
175 : : * @return
176 : : * Number of successfully processed packets, with error code set in rte_errno.
177 : : */
178 : : __rte_experimental
179 : : static inline uint16_t
180 : : rte_ipsec_pkt_crypto_prepare_stateless(const struct rte_ipsec_session *ss,
181 : : struct rte_mbuf *mb[], struct rte_crypto_op *cop[], uint16_t num,
182 : : struct rte_ipsec_state *state)
183 : : {
184 : 0 : return ss->pkt_func.prepare_stateless.async(ss, mb, cop, num, state);
185 : : }
186 : :
187 : : /**
188 : : * Same as *rte_ipsec_pkt_crypto_prepare_stateless*, but processing is done
189 : : * in synchronous mode.
190 : : *
191 : : * @param ss
192 : : * Pointer to the *rte_ipsec_session* object the packets belong to.
193 : : * @param mb
194 : : * The address of an array of *num* pointers to *rte_mbuf* structures
195 : : * which contain the input packets.
196 : : * @param num
197 : : * The maximum number of packets to process.
198 : : * @param state
199 : : * The IPsec state to be used for processing current batch of packets.
200 : : * @return
201 : : * Number of successfully processed packets, with error code set in rte_errno.
202 : : */
203 : : __rte_experimental
204 : : static inline uint16_t
205 : : rte_ipsec_pkt_cpu_prepare_stateless(const struct rte_ipsec_session *ss,
206 : : struct rte_mbuf *mb[], uint16_t num, struct rte_ipsec_state *state)
207 : : {
208 : : return ss->pkt_func.prepare_stateless.sync(ss, mb, num, state);
209 : : }
210 : :
211 : : /**
212 : : * Finalise processing of packets after crypto-dev finished with them or
213 : : * process packets that are subjects to inline IPsec offload.
214 : : * Expects that for each input packet:
215 : : * - l2_len, l3_len are setup correctly
216 : : * Output mbufs will be:
217 : : * inbound - decrypted & authenticated, ESP(AH) related headers removed,
218 : : * *l2_len* and *l3_len* fields are updated.
219 : : * outbound - appropriate mbuf fields (ol_flags, tx_offloads, etc.)
220 : : * properly setup, if necessary - IP headers updated, ESP(AH) fields added,
221 : : * Note that erroneous mbufs are not freed by the function,
222 : : * but are placed beyond last valid mbuf in the *mb* array.
223 : : * It is a user responsibility to handle them further.
224 : : * @param ss
225 : : * Pointer to the *rte_ipsec_session* object the packets belong to.
226 : : * @param mb
227 : : * The address of an array of *num* pointers to *rte_mbuf* structures
228 : : * which contain the input packets.
229 : : * @param num
230 : : * The maximum number of packets to process.
231 : : * @return
232 : : * Number of successfully processed packets, with error code set in rte_errno.
233 : : */
234 : : static inline uint16_t
235 : : rte_ipsec_pkt_process(const struct rte_ipsec_session *ss, struct rte_mbuf *mb[],
236 : : uint16_t num)
237 : : {
238 : 0 : return ss->pkt_func.process(ss, mb, num);
239 : : }
240 : :
241 : :
242 : : /**
243 : : * Enable per SA telemetry for a specific SA.
244 : : * Note that this function is not thread safe
245 : : * @param sa
246 : : * Pointer to the *rte_ipsec_sa* object that will have telemetry enabled.
247 : : * @return
248 : : * 0 on success, negative value otherwise.
249 : : */
250 : : int
251 : : rte_ipsec_telemetry_sa_add(const struct rte_ipsec_sa *sa);
252 : :
253 : : /**
254 : : * Disable per SA telemetry for a specific SA.
255 : : * Note that this function is not thread safe
256 : : * @param sa
257 : : * Pointer to the *rte_ipsec_sa* object that will have telemetry disabled.
258 : : */
259 : : void
260 : : rte_ipsec_telemetry_sa_del(const struct rte_ipsec_sa *sa);
261 : :
262 : : #include <rte_ipsec_group.h>
263 : :
264 : : #ifdef __cplusplus
265 : : extern "C" {
266 : : #endif
267 : :
268 : : #ifdef __cplusplus
269 : : }
270 : : #endif
271 : :
272 : : #endif /* _RTE_IPSEC_H_ */
|
