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 * ... 82 */ 83 84 enum { 85 RTE_SATP_LOG2_IPV, 86 RTE_SATP_LOG2_PROTO, 87 RTE_SATP_LOG2_DIR, 88 RTE_SATP_LOG2_MODE, 89 RTE_SATP_LOG2_SQN = RTE_SATP_LOG2_MODE + 2, 90 RTE_SATP_LOG2_ESN, 91 RTE_SATP_LOG2_ECN, 92 RTE_SATP_LOG2_DSCP 93 }; 94 95 #define RTE_IPSEC_SATP_IPV_MASK (1ULL << RTE_SATP_LOG2_IPV) 96 #define RTE_IPSEC_SATP_IPV4 (0ULL << RTE_SATP_LOG2_IPV) 97 #define RTE_IPSEC_SATP_IPV6 (1ULL << RTE_SATP_LOG2_IPV) 98 99 #define RTE_IPSEC_SATP_PROTO_MASK (1ULL << RTE_SATP_LOG2_PROTO) 100 #define RTE_IPSEC_SATP_PROTO_AH (0ULL << RTE_SATP_LOG2_PROTO) 101 #define RTE_IPSEC_SATP_PROTO_ESP (1ULL << RTE_SATP_LOG2_PROTO) 102 103 #define RTE_IPSEC_SATP_DIR_MASK (1ULL << RTE_SATP_LOG2_DIR) 104 #define RTE_IPSEC_SATP_DIR_IB (0ULL << RTE_SATP_LOG2_DIR) 105 #define RTE_IPSEC_SATP_DIR_OB (1ULL << RTE_SATP_LOG2_DIR) 106 107 #define RTE_IPSEC_SATP_MODE_MASK (3ULL << RTE_SATP_LOG2_MODE) 108 #define RTE_IPSEC_SATP_MODE_TRANS (0ULL << RTE_SATP_LOG2_MODE) 109 #define RTE_IPSEC_SATP_MODE_TUNLV4 (1ULL << RTE_SATP_LOG2_MODE) 110 #define RTE_IPSEC_SATP_MODE_TUNLV6 (2ULL << RTE_SATP_LOG2_MODE) 111 112 #define RTE_IPSEC_SATP_SQN_MASK (1ULL << RTE_SATP_LOG2_SQN) 113 #define RTE_IPSEC_SATP_SQN_RAW (0ULL << RTE_SATP_LOG2_SQN) 114 #define RTE_IPSEC_SATP_SQN_ATOM (1ULL << RTE_SATP_LOG2_SQN) 115 116 #define RTE_IPSEC_SATP_ESN_MASK (1ULL << RTE_SATP_LOG2_ESN) 117 #define RTE_IPSEC_SATP_ESN_DISABLE (0ULL << RTE_SATP_LOG2_ESN) 118 #define RTE_IPSEC_SATP_ESN_ENABLE (1ULL << RTE_SATP_LOG2_ESN) 119 120 #define RTE_IPSEC_SATP_ECN_MASK (1ULL << RTE_SATP_LOG2_ECN) 121 #define RTE_IPSEC_SATP_ECN_DISABLE (0ULL << RTE_SATP_LOG2_ECN) 122 #define RTE_IPSEC_SATP_ECN_ENABLE (1ULL << RTE_SATP_LOG2_ECN) 123 124 #define RTE_IPSEC_SATP_DSCP_MASK (1ULL << RTE_SATP_LOG2_DSCP) 125 #define RTE_IPSEC_SATP_DSCP_DISABLE (0ULL << RTE_SATP_LOG2_DSCP) 126 #define RTE_IPSEC_SATP_DSCP_ENABLE (1ULL << RTE_SATP_LOG2_DSCP) 127 128 /** 129 * get type of given SA 130 * @return 131 * SA type value. 132 */ 133 uint64_t 134 rte_ipsec_sa_type(const struct rte_ipsec_sa *sa); 135 136 /** 137 * Calculate required SA size based on provided input parameters. 138 * @param prm 139 * Parameters that will be used to initialise SA object. 140 * @return 141 * - Actual size required for SA with given parameters. 142 * - -EINVAL if the parameters are invalid. 143 */ 144 int 145 rte_ipsec_sa_size(const struct rte_ipsec_sa_prm *prm); 146 147 /** 148 * initialise SA based on provided input parameters. 149 * @param sa 150 * SA object to initialise. 151 * @param prm 152 * Parameters used to initialise given SA object. 153 * @param size 154 * size of the provided buffer for SA. 155 * @return 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. 159 */ 160 int 161 rte_ipsec_sa_init(struct rte_ipsec_sa *sa, const struct rte_ipsec_sa_prm *prm, 162 uint32_t size); 163 164 /** 165 * cleanup SA 166 * @param sa 167 * Pointer to SA object to de-initialize. 168 */ 169 void 170 rte_ipsec_sa_fini(struct rte_ipsec_sa *sa); 171 172 #ifdef __cplusplus 173 } 174 #endif 175 176 #endif /* _RTE_IPSEC_SA_H_ */ 177