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_NUM
  99 };
 100
 101 #define RTE_IPSEC_SATP_IPV_MASK         (1ULL << RTE_SATP_LOG2_IPV)
 102 #define RTE_IPSEC_SATP_IPV4             (0ULL << RTE_SATP_LOG2_IPV)
 103 #define RTE_IPSEC_SATP_IPV6             (1ULL << RTE_SATP_LOG2_IPV)
 104
 105 #define RTE_IPSEC_SATP_PROTO_MASK       (1ULL << RTE_SATP_LOG2_PROTO)
 106 #define RTE_IPSEC_SATP_PROTO_AH         (0ULL << RTE_SATP_LOG2_PROTO)
 107 #define RTE_IPSEC_SATP_PROTO_ESP        (1ULL << RTE_SATP_LOG2_PROTO)
 108
 109 #define RTE_IPSEC_SATP_DIR_MASK         (1ULL << RTE_SATP_LOG2_DIR)
 110 #define RTE_IPSEC_SATP_DIR_IB           (0ULL << RTE_SATP_LOG2_DIR)
 111 #define RTE_IPSEC_SATP_DIR_OB           (1ULL << RTE_SATP_LOG2_DIR)
 112
 113 #define RTE_IPSEC_SATP_MODE_MASK        (3ULL << RTE_SATP_LOG2_MODE)
 114 #define RTE_IPSEC_SATP_MODE_TRANS       (0ULL << RTE_SATP_LOG2_MODE)
 115 #define RTE_IPSEC_SATP_MODE_TUNLV4      (1ULL << RTE_SATP_LOG2_MODE)
 116 #define RTE_IPSEC_SATP_MODE_TUNLV6      (2ULL << RTE_SATP_LOG2_MODE)
 117
 118 #define RTE_IPSEC_SATP_SQN_MASK         (1ULL << RTE_SATP_LOG2_SQN)
 119 #define RTE_IPSEC_SATP_SQN_RAW          (0ULL << RTE_SATP_LOG2_SQN)
 120 #define RTE_IPSEC_SATP_SQN_ATOM         (1ULL << RTE_SATP_LOG2_SQN)
 121
 122 #define RTE_IPSEC_SATP_ESN_MASK         (1ULL << RTE_SATP_LOG2_ESN)
 123 #define RTE_IPSEC_SATP_ESN_DISABLE      (0ULL << RTE_SATP_LOG2_ESN)
 124 #define RTE_IPSEC_SATP_ESN_ENABLE       (1ULL << RTE_SATP_LOG2_ESN)
 125
 126 /**
 127  * get type of given SA
 128  * @return
 129  *   SA type value.
 130  */
 131 uint64_t __rte_experimental
 132 rte_ipsec_sa_type(const struct rte_ipsec_sa *sa);
 133
 134 /**
 135  * Calculate required SA size based on provided input parameters.
 136  * @param prm
 137  *   Parameters that will be used to initialise SA object.
 138  * @return
 139  *   - Actual size required for SA with given parameters.
 140  *   - -EINVAL if the parameters are invalid.
 141  */
 142 int __rte_experimental
 143 rte_ipsec_sa_size(const struct rte_ipsec_sa_prm *prm);
 144
 145 /**
 146  * initialise SA based on provided input parameters.
 147  * @param sa
 148  *   SA object to initialise.
 149  * @param prm
 150  *   Parameters used to initialise given SA object.
 151  * @param size
 152  *   size of the provided buffer for SA.
 153  * @return
 154  *   - Actual size of SA object if operation completed successfully.
 155  *   - -EINVAL if the parameters are invalid.
 156  *   - -ENOSPC if the size of the provided buffer is not big enough.
 157  */
 158 int __rte_experimental
 159 rte_ipsec_sa_init(struct rte_ipsec_sa *sa, const struct rte_ipsec_sa_prm *prm,
 160         uint32_t size);
 161
 162 /**
 163  * cleanup SA
 164  * @param sa
 165  *   Pointer to SA object to de-initialize.
 166  */
 167 void __rte_experimental
 168 rte_ipsec_sa_fini(struct rte_ipsec_sa *sa);
 169
 170 #ifdef __cplusplus
 171 }
 172 #endif
 173
 174 #endif /* _RTE_IPSEC_SA_H_ */