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
rte_ipsec_pkt_crypto_prepare(const struct rte_ipsec_session * ss,struct rte_mbuf * mb[],struct rte_crypto_op * cop[],uint16_t num)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
rte_ipsec_pkt_cpu_prepare(const struct rte_ipsec_session * ss,struct rte_mbuf * mb[],uint16_t num)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
rte_ipsec_pkt_process(const struct rte_ipsec_session * ss,struct rte_mbuf * mb[],uint16_t num)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