lib/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  *
  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_ */