lib/librte_ipsec/rte_ipsec_sa.h

   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  * @b EXPERIMENTAL: this API may change without prior notice
  11  *
  12  * Defines API to manage IPsec Security Association (SA) objects.
  13  */
  14
  15 #include <rte_common.h>
  16 #include <rte_cryptodev.h>
  17 #include <rte_security.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 /**
  24  * An opaque structure to represent Security Association (SA).
  25  */
  26 struct rte_ipsec_sa;
  27
  28 /**
  29  * SA initialization parameters.
  30  */
  31 struct rte_ipsec_sa_prm {
  32
  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;
  39         union {
  40                 struct {
  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 */
  46                 struct {
  47                         uint8_t proto;  /**< next header protocol */
  48                 } trs; /**< transport mode related parameters */
  49         };
  50
  51         /**
  52          * window size to enable sequence replay attack handling.
  53          * replay checking is disabled if the window size is 0.
  54          */
  55         uint32_t replay_win_sz;
  56 };
  57
  58 /**
  59  * Indicates that SA will(/will not) need an 'atomic' access
  60  * to sequence number and replay window.
  61  * 'atomic' here means:
  62  * functions:
  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
  67  * operations.
  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()
  75  * invocations.
  76  */
  77 #define RTE_IPSEC_SAFLAG_SQN_ATOM       (1ULL << 0)
  78
  79 /**
  80  * SA type is an 64-bit value that contain the following information:
  81  * - IP version (IPv4/IPv6)
  82  * - IPsec proto (ESP/AH)
  83  * - inbound/outbound
  84  * - mode (TRANSPORT/TUNNEL)
  85  * - for TUNNEL outer IP version (IPv4/IPv6)
  86  * - are SA SQN operations 'atomic'
  87  * - ESN enabled/disabled
  88  * ...
  89  */
  90
  91 enum {
  92         RTE_SATP_LOG2_IPV,
  93         RTE_SATP_LOG2_PROTO,
  94         RTE_SATP_LOG2_DIR,
  95         RTE_SATP_LOG2_MODE,
  96         RTE_SATP_LOG2_SQN = RTE_SATP_LOG2_MODE + 2,
  97         RTE_SATP_LOG2_ESN,
  98         RTE_SATP_LOG2_ECN,
  99         RTE_SATP_LOG2_DSCP,
 100         RTE_SATP_LOG2_NUM
 101 };
 102
 103 #define RTE_IPSEC_SATP_IPV_MASK         (1ULL << RTE_SATP_LOG2_IPV)
 104 #define RTE_IPSEC_SATP_IPV4             (0ULL << RTE_SATP_LOG2_IPV)
 105 #define RTE_IPSEC_SATP_IPV6             (1ULL << RTE_SATP_LOG2_IPV)
 106
 107 #define RTE_IPSEC_SATP_PROTO_MASK       (1ULL << RTE_SATP_LOG2_PROTO)
 108 #define RTE_IPSEC_SATP_PROTO_AH         (0ULL << RTE_SATP_LOG2_PROTO)
 109 #define RTE_IPSEC_SATP_PROTO_ESP        (1ULL << RTE_SATP_LOG2_PROTO)
 110
 111 #define RTE_IPSEC_SATP_DIR_MASK         (1ULL << RTE_SATP_LOG2_DIR)
 112 #define RTE_IPSEC_SATP_DIR_IB           (0ULL << RTE_SATP_LOG2_DIR)
 113 #define RTE_IPSEC_SATP_DIR_OB           (1ULL << RTE_SATP_LOG2_DIR)
 114
 115 #define RTE_IPSEC_SATP_MODE_MASK        (3ULL << RTE_SATP_LOG2_MODE)
 116 #define RTE_IPSEC_SATP_MODE_TRANS       (0ULL << RTE_SATP_LOG2_MODE)
 117 #define RTE_IPSEC_SATP_MODE_TUNLV4      (1ULL << RTE_SATP_LOG2_MODE)
 118 #define RTE_IPSEC_SATP_MODE_TUNLV6      (2ULL << RTE_SATP_LOG2_MODE)
 119
 120 #define RTE_IPSEC_SATP_SQN_MASK         (1ULL << RTE_SATP_LOG2_SQN)
 121 #define RTE_IPSEC_SATP_SQN_RAW          (0ULL << RTE_SATP_LOG2_SQN)
 122 #define RTE_IPSEC_SATP_SQN_ATOM         (1ULL << RTE_SATP_LOG2_SQN)
 123
 124 #define RTE_IPSEC_SATP_ESN_MASK         (1ULL << RTE_SATP_LOG2_ESN)
 125 #define RTE_IPSEC_SATP_ESN_DISABLE      (0ULL << RTE_SATP_LOG2_ESN)
 126 #define RTE_IPSEC_SATP_ESN_ENABLE       (1ULL << RTE_SATP_LOG2_ESN)
 127
 128 #define RTE_IPSEC_SATP_ECN_MASK         (1ULL << RTE_SATP_LOG2_ECN)
 129 #define RTE_IPSEC_SATP_ECN_DISABLE      (0ULL << RTE_SATP_LOG2_ECN)
 130 #define RTE_IPSEC_SATP_ECN_ENABLE       (1ULL << RTE_SATP_LOG2_ECN)
 131
 132 #define RTE_IPSEC_SATP_DSCP_MASK        (1ULL << RTE_SATP_LOG2_DSCP)
 133 #define RTE_IPSEC_SATP_DSCP_DISABLE     (0ULL << RTE_SATP_LOG2_DSCP)
 134 #define RTE_IPSEC_SATP_DSCP_ENABLE      (1ULL << RTE_SATP_LOG2_DSCP)
 135
 136 /**
 137  * get type of given SA
 138  * @return
 139  *   SA type value.
 140  */
 141 __rte_experimental
 142 uint64_t
 143 rte_ipsec_sa_type(const struct rte_ipsec_sa *sa);
 144
 145 /**
 146  * Calculate required SA size based on provided input parameters.
 147  * @param prm
 148  *   Parameters that will be used to initialise SA object.
 149  * @return
 150  *   - Actual size required for SA with given parameters.
 151  *   - -EINVAL if the parameters are invalid.
 152  */
 153 __rte_experimental
 154 int
 155 rte_ipsec_sa_size(const struct rte_ipsec_sa_prm *prm);
 156
 157 /**
 158  * initialise SA based on provided input parameters.
 159  * @param sa
 160  *   SA object to initialise.
 161  * @param prm
 162  *   Parameters used to initialise given SA object.
 163  * @param size
 164  *   size of the provided buffer for SA.
 165  * @return
 166  *   - Actual size of SA object if operation completed successfully.
 167  *   - -EINVAL if the parameters are invalid.
 168  *   - -ENOSPC if the size of the provided buffer is not big enough.
 169  */
 170 __rte_experimental
 171 int
 172 rte_ipsec_sa_init(struct rte_ipsec_sa *sa, const struct rte_ipsec_sa_prm *prm,
 173         uint32_t size);
 174
 175 /**
 176  * cleanup SA
 177  * @param sa
 178  *   Pointer to SA object to de-initialize.
 179  */
 180 __rte_experimental
 181 void
 182 rte_ipsec_sa_fini(struct rte_ipsec_sa *sa);
 183
 184 #ifdef __cplusplus
 185 }
 186 #endif
 187
 188 #endif /* _RTE_IPSEC_SA_H_ */