1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Intel Corporation
5 #ifndef _RTE_IPSEC_SA_H_
6 #define _RTE_IPSEC_SA_H_
10 * @b EXPERIMENTAL: this API may change without prior notice
12 * Defines API to manage IPsec Security Association (SA) objects.
15 #include <rte_common.h>
16 #include <rte_cryptodev.h>
17 #include <rte_security.h>
24 * An opaque structure to represent Security Association (SA).
29 * SA initialization parameters.
31 struct rte_ipsec_sa_prm {
33 uint64_t userdata; /**< provided and interpreted by user */
34 uint64_t flags; /**< see RTE_IPSEC_SAFLAG_* below */
35 /** ipsec configuration */
36 struct rte_security_ipsec_xform ipsec_xform;
37 /** crypto session configuration */
38 struct rte_crypto_sym_xform *crypto_xform;
41 uint8_t hdr_len; /**< tunnel header len */
42 uint8_t hdr_l3_off; /**< offset for IPv4/IPv6 header */
43 uint8_t next_proto; /**< next header protocol */
44 const void *hdr; /**< tunnel header template */
45 } tun; /**< tunnel mode related parameters */
47 uint8_t proto; /**< next header protocol */
48 } trs; /**< transport mode related parameters */
52 * window size to enable sequence replay attack handling.
53 * replay checking is disabled if the window size is 0.
55 uint32_t replay_win_sz;
59 * Indicates that SA will(/will not) need an 'atomic' access
60 * to sequence number and replay window.
61 * 'atomic' here means:
63 * - rte_ipsec_pkt_crypto_prepare
64 * - rte_ipsec_pkt_process
65 * can be safely used in MT environment, as long as the user can guarantee
66 * that they obey multiple readers/single writer model for SQN+replay_window
68 * To be more specific:
69 * for outbound SA there are no restrictions.
70 * for inbound SA the caller has to guarantee that at any given moment
71 * only one thread is executing rte_ipsec_pkt_process() for given SA.
72 * Note that it is caller responsibility to maintain correct order
73 * of packets to be processed.
74 * In other words - it is a caller responsibility to serialize process()
77 #define RTE_IPSEC_SAFLAG_SQN_ATOM (1ULL << 0)
80 * SA type is an 64-bit value that contain the following information:
81 * - IP version (IPv4/IPv6)
82 * - IPsec proto (ESP/AH)
84 * - mode (TRANSPORT/TUNNEL)
85 * - for TUNNEL outer IP version (IPv4/IPv6)
86 * - are SA SQN operations 'atomic'
87 * - ESN enabled/disabled
96 RTE_SATP_LOG2_SQN = RTE_SATP_LOG2_MODE + 2,
101 #define RTE_IPSEC_SATP_IPV_MASK (1ULL << RTE_SATP_LOG2_IPV)
102 #define RTE_IPSEC_SATP_IPV4 (0ULL << RTE_SATP_LOG2_IPV)
103 #define RTE_IPSEC_SATP_IPV6 (1ULL << RTE_SATP_LOG2_IPV)
105 #define RTE_IPSEC_SATP_PROTO_MASK (1ULL << RTE_SATP_LOG2_PROTO)
106 #define RTE_IPSEC_SATP_PROTO_AH (0ULL << RTE_SATP_LOG2_PROTO)
107 #define RTE_IPSEC_SATP_PROTO_ESP (1ULL << RTE_SATP_LOG2_PROTO)
109 #define RTE_IPSEC_SATP_DIR_MASK (1ULL << RTE_SATP_LOG2_DIR)
110 #define RTE_IPSEC_SATP_DIR_IB (0ULL << RTE_SATP_LOG2_DIR)
111 #define RTE_IPSEC_SATP_DIR_OB (1ULL << RTE_SATP_LOG2_DIR)
113 #define RTE_IPSEC_SATP_MODE_MASK (3ULL << RTE_SATP_LOG2_MODE)
114 #define RTE_IPSEC_SATP_MODE_TRANS (0ULL << RTE_SATP_LOG2_MODE)
115 #define RTE_IPSEC_SATP_MODE_TUNLV4 (1ULL << RTE_SATP_LOG2_MODE)
116 #define RTE_IPSEC_SATP_MODE_TUNLV6 (2ULL << RTE_SATP_LOG2_MODE)
118 #define RTE_IPSEC_SATP_SQN_MASK (1ULL << RTE_SATP_LOG2_SQN)
119 #define RTE_IPSEC_SATP_SQN_RAW (0ULL << RTE_SATP_LOG2_SQN)
120 #define RTE_IPSEC_SATP_SQN_ATOM (1ULL << RTE_SATP_LOG2_SQN)
122 #define RTE_IPSEC_SATP_ESN_MASK (1ULL << RTE_SATP_LOG2_ESN)
123 #define RTE_IPSEC_SATP_ESN_DISABLE (0ULL << RTE_SATP_LOG2_ESN)
124 #define RTE_IPSEC_SATP_ESN_ENABLE (1ULL << RTE_SATP_LOG2_ESN)
127 * get type of given SA
133 rte_ipsec_sa_type(const struct rte_ipsec_sa *sa);
136 * Calculate required SA size based on provided input parameters.
138 * Parameters that will be used to initialise SA object.
140 * - Actual size required for SA with given parameters.
141 * - -EINVAL if the parameters are invalid.
145 rte_ipsec_sa_size(const struct rte_ipsec_sa_prm *prm);
148 * initialise SA based on provided input parameters.
150 * SA object to initialise.
152 * Parameters used to initialise given SA object.
154 * size of the provided buffer for SA.
156 * - Actual size of SA object if operation completed successfully.
157 * - -EINVAL if the parameters are invalid.
158 * - -ENOSPC if the size of the provided buffer is not big enough.
162 rte_ipsec_sa_init(struct rte_ipsec_sa *sa, const struct rte_ipsec_sa_prm *prm,
168 * Pointer to SA object to de-initialize.
172 rte_ipsec_sa_fini(struct rte_ipsec_sa *sa);
178 #endif /* _RTE_IPSEC_SA_H_ */