1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2018 Intel Corporation 3 */ 4 5 #ifndef _RTE_IPSEC_SA_H_ 6 #define _RTE_IPSEC_SA_H_ 7 8 /** 9 * @file rte_ipsec_sa.h 10 * 11 * Defines API to manage IPsec Security Association (SA) objects. 12 */ 13 14 #include <rte_common.h> 15 #include <rte_cryptodev.h> 16 #include <rte_security.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** 23 * An opaque structure to represent Security Association (SA). 24 */ 25 struct rte_ipsec_sa; 26 27 /** 28 * SA initialization parameters. 29 */ 30 struct rte_ipsec_sa_prm { 31 32 uint64_t userdata; /**< provided and interpreted by user */ 33 uint64_t flags; /**< see RTE_IPSEC_SAFLAG_* below */ 34 /** ipsec configuration */ 35 struct rte_security_ipsec_xform ipsec_xform; 36 /** crypto session configuration */ 37 struct rte_crypto_sym_xform *crypto_xform; 38 union { 39 struct { 40 uint8_t hdr_len; /**< tunnel header len */ 41 uint8_t hdr_l3_off; /**< offset for IPv4/IPv6 header */ 42 uint8_t next_proto; /**< next header protocol */ 43 const void *hdr; /**< tunnel header template */ 44 } tun; /**< tunnel mode related parameters */ 45 struct { 46 uint8_t proto; /**< next header protocol */ 47 } trs; /**< transport mode related parameters */ 48 }; 49 }; 50 51 /** 52 * Indicates that SA will(/will not) need an 'atomic' access 53 * to sequence number and replay window. 54 * 'atomic' here means: 55 * functions: 56 * - rte_ipsec_pkt_crypto_prepare 57 * - rte_ipsec_pkt_process 58 * can be safely used in MT environment, as long as the user can guarantee 59 * that they obey multiple readers/single writer model for SQN+replay_window 60 * operations. 61 * To be more specific: 62 * for outbound SA there are no restrictions. 63 * for inbound SA the caller has to guarantee that at any given moment 64 * only one thread is executing rte_ipsec_pkt_process() for given SA. 65 * Note that it is caller responsibility to maintain correct order 66 * of packets to be processed. 67 * In other words - it is a caller responsibility to serialize process() 68 * invocations. 69 */ 70 #define RTE_IPSEC_SAFLAG_SQN_ATOM (1ULL << 0) 71 72 /** 73 * SA type is an 64-bit value that contain the following information: 74 * - IP version (IPv4/IPv6) 75 * - IPsec proto (ESP/AH) 76 * - inbound/outbound 77 * - mode (TRANSPORT/TUNNEL) 78 * - for TUNNEL outer IP version (IPv4/IPv6) 79 * - are SA SQN operations 'atomic' 80 * - ESN enabled/disabled 81 * - NAT-T UDP encapsulated (TUNNEL mode only) 82 * ... 83 */ 84 85 enum { 86 RTE_SATP_LOG2_IPV, 87 RTE_SATP_LOG2_PROTO, 88 RTE_SATP_LOG2_DIR, 89 RTE_SATP_LOG2_MODE, 90 RTE_SATP_LOG2_SQN = RTE_SATP_LOG2_MODE + 2, 91 RTE_SATP_LOG2_ESN, 92 RTE_SATP_LOG2_ECN, 93 RTE_SATP_LOG2_DSCP, 94 RTE_SATP_LOG2_NATT 95 }; 96 97 #define RTE_IPSEC_SATP_IPV_MASK (1ULL << RTE_SATP_LOG2_IPV) 98 #define RTE_IPSEC_SATP_IPV4 (0ULL << RTE_SATP_LOG2_IPV) 99 #define RTE_IPSEC_SATP_IPV6 (1ULL << RTE_SATP_LOG2_IPV) 100 101 #define RTE_IPSEC_SATP_PROTO_MASK (1ULL << RTE_SATP_LOG2_PROTO) 102 #define RTE_IPSEC_SATP_PROTO_AH (0ULL << RTE_SATP_LOG2_PROTO) 103 #define RTE_IPSEC_SATP_PROTO_ESP (1ULL << RTE_SATP_LOG2_PROTO) 104 105 #define RTE_IPSEC_SATP_DIR_MASK (1ULL << RTE_SATP_LOG2_DIR) 106 #define RTE_IPSEC_SATP_DIR_IB (0ULL << RTE_SATP_LOG2_DIR) 107 #define RTE_IPSEC_SATP_DIR_OB (1ULL << RTE_SATP_LOG2_DIR) 108 109 #define RTE_IPSEC_SATP_MODE_MASK (3ULL << RTE_SATP_LOG2_MODE) 110 #define RTE_IPSEC_SATP_MODE_TRANS (0ULL << RTE_SATP_LOG2_MODE) 111 #define RTE_IPSEC_SATP_MODE_TUNLV4 (1ULL << RTE_SATP_LOG2_MODE) 112 #define RTE_IPSEC_SATP_MODE_TUNLV6 (2ULL << RTE_SATP_LOG2_MODE) 113 114 #define RTE_IPSEC_SATP_SQN_MASK (1ULL << RTE_SATP_LOG2_SQN) 115 #define RTE_IPSEC_SATP_SQN_RAW (0ULL << RTE_SATP_LOG2_SQN) 116 #define RTE_IPSEC_SATP_SQN_ATOM (1ULL << RTE_SATP_LOG2_SQN) 117 118 #define RTE_IPSEC_SATP_ESN_MASK (1ULL << RTE_SATP_LOG2_ESN) 119 #define RTE_IPSEC_SATP_ESN_DISABLE (0ULL << RTE_SATP_LOG2_ESN) 120 #define RTE_IPSEC_SATP_ESN_ENABLE (1ULL << RTE_SATP_LOG2_ESN) 121 122 #define RTE_IPSEC_SATP_ECN_MASK (1ULL << RTE_SATP_LOG2_ECN) 123 #define RTE_IPSEC_SATP_ECN_DISABLE (0ULL << RTE_SATP_LOG2_ECN) 124 #define RTE_IPSEC_SATP_ECN_ENABLE (1ULL << RTE_SATP_LOG2_ECN) 125 126 #define RTE_IPSEC_SATP_DSCP_MASK (1ULL << RTE_SATP_LOG2_DSCP) 127 #define RTE_IPSEC_SATP_DSCP_DISABLE (0ULL << RTE_SATP_LOG2_DSCP) 128 #define RTE_IPSEC_SATP_DSCP_ENABLE (1ULL << RTE_SATP_LOG2_DSCP) 129 130 #define RTE_IPSEC_SATP_NATT_MASK (1ULL << RTE_SATP_LOG2_NATT) 131 #define RTE_IPSEC_SATP_NATT_DISABLE (0ULL << RTE_SATP_LOG2_NATT) 132 #define RTE_IPSEC_SATP_NATT_ENABLE (1ULL << RTE_SATP_LOG2_NATT) 133 134 135 /** 136 * get type of given SA 137 * @return 138 * SA type value. 139 */ 140 uint64_t 141 rte_ipsec_sa_type(const struct rte_ipsec_sa *sa); 142 143 /** 144 * Calculate required SA size based on provided input parameters. 145 * @param prm 146 * Parameters that will be used to initialise SA object. 147 * @return 148 * - Actual size required for SA with given parameters. 149 * - -EINVAL if the parameters are invalid. 150 */ 151 int 152 rte_ipsec_sa_size(const struct rte_ipsec_sa_prm *prm); 153 154 /** 155 * initialise SA based on provided input parameters. 156 * @param sa 157 * SA object to initialise. 158 * @param prm 159 * Parameters used to initialise given SA object. 160 * @param size 161 * size of the provided buffer for SA. 162 * @return 163 * - Actual size of SA object if operation completed successfully. 164 * - -EINVAL if the parameters are invalid. 165 * - -ENOSPC if the size of the provided buffer is not big enough. 166 */ 167 int 168 rte_ipsec_sa_init(struct rte_ipsec_sa *sa, const struct rte_ipsec_sa_prm *prm, 169 uint32_t size); 170 171 /** 172 * cleanup SA 173 * @param sa 174 * Pointer to SA object to de-initialize. 175 */ 176 void 177 rte_ipsec_sa_fini(struct rte_ipsec_sa *sa); 178 179 #ifdef __cplusplus 180 } 181 #endif 182 183 #endif /* _RTE_IPSEC_SA_H_ */ 184