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 /**
  53  * Indicates that SA will(/will not) need an 'atomic' access
  54  * to sequence number and replay window.
  55  * 'atomic' here means:
  56  * functions:
  57  *  - rte_ipsec_pkt_crypto_prepare
  58  *  - rte_ipsec_pkt_process
  59  * can be safely used in MT environment, as long as the user can guarantee
  60  * that they obey multiple readers/single writer model for SQN+replay_window
  61  * operations.
  62  * To be more specific:
  63  * for outbound SA there are no restrictions.
  64  * for inbound SA the caller has to guarantee that at any given moment
  65  * only one thread is executing rte_ipsec_pkt_process() for given SA.
  66  * Note that it is caller responsibility to maintain correct order
  67  * of packets to be processed.
  68  * In other words - it is a caller responsibility to serialize process()
  69  * invocations.
  70  */
  71 #define RTE_IPSEC_SAFLAG_SQN_ATOM       (1ULL << 0)
  72
  73 /**
  74  * SA type is an 64-bit value that contain the following information:
  75  * - IP version (IPv4/IPv6)
  76  * - IPsec proto (ESP/AH)
  77  * - inbound/outbound
  78  * - mode (TRANSPORT/TUNNEL)
  79  * - for TUNNEL outer IP version (IPv4/IPv6)
  80  * - are SA SQN operations 'atomic'
  81  * - ESN enabled/disabled
  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_NUM
  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 /**
 131  * get type of given SA
 132  * @return
 133  *   SA type value.
 134  */
 135 __rte_experimental
 136 uint64_t
 137 rte_ipsec_sa_type(const struct rte_ipsec_sa *sa);
 138
 139 /**
 140  * Calculate required SA size based on provided input parameters.
 141  * @param prm
 142  *   Parameters that will be used to initialise SA object.
 143  * @return
 144  *   - Actual size required for SA with given parameters.
 145  *   - -EINVAL if the parameters are invalid.
 146  */
 147 __rte_experimental
 148 int
 149 rte_ipsec_sa_size(const struct rte_ipsec_sa_prm *prm);
 150
 151 /**
 152  * initialise SA based on provided input parameters.
 153  * @param sa
 154  *   SA object to initialise.
 155  * @param prm
 156  *   Parameters used to initialise given SA object.
 157  * @param size
 158  *   size of the provided buffer for SA.
 159  * @return
 160  *   - Actual size of SA object if operation completed successfully.
 161  *   - -EINVAL if the parameters are invalid.
 162  *   - -ENOSPC if the size of the provided buffer is not big enough.
 163  */
 164 __rte_experimental
 165 int
 166 rte_ipsec_sa_init(struct rte_ipsec_sa *sa, const struct rte_ipsec_sa_prm *prm,
 167         uint32_t size);
 168
 169 /**
 170  * cleanup SA
 171  * @param sa
 172  *   Pointer to SA object to de-initialize.
 173  */
 174 __rte_experimental
 175 void
 176 rte_ipsec_sa_fini(struct rte_ipsec_sa *sa);
 177
 178 #ifdef __cplusplus
 179 }
 180 #endif
 181
 182 #endif /* _RTE_IPSEC_SA_H_ */