lib/librte_security/rte_security.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2017 NXP.
   3  * Copyright(c) 2017 Intel Corporation.
   4  */
   5
   6 #ifndef _RTE_SECURITY_H_
   7 #define _RTE_SECURITY_H_
   8
   9 /**
  10  * @file rte_security.h
  11  * @b EXPERIMENTAL: this API may change without prior notice
  12  *
  13  * RTE Security Common Definitions
  14  *
  15  */
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 #include <sys/types.h>
  22
  23 #include <netinet/in.h>
  24 #include <netinet/ip.h>
  25 #include <netinet/ip6.h>
  26
  27 #include <rte_compat.h>
  28 #include <rte_common.h>
  29 #include <rte_crypto.h>
  30 #include <rte_mbuf.h>
  31 #include <rte_memory.h>
  32 #include <rte_mempool.h>
  33
  34 /** IPSec protocol mode */
  35 enum rte_security_ipsec_sa_mode {
  36         RTE_SECURITY_IPSEC_SA_MODE_TRANSPORT = 1,
  37         /**< IPSec Transport mode */
  38         RTE_SECURITY_IPSEC_SA_MODE_TUNNEL,
  39         /**< IPSec Tunnel mode */
  40 };
  41
  42 /** IPSec Protocol */
  43 enum rte_security_ipsec_sa_protocol {
  44         RTE_SECURITY_IPSEC_SA_PROTO_AH = 1,
  45         /**< AH protocol */
  46         RTE_SECURITY_IPSEC_SA_PROTO_ESP,
  47         /**< ESP protocol */
  48 };
  49
  50 /** IPSEC tunnel type */
  51 enum rte_security_ipsec_tunnel_type {
  52         RTE_SECURITY_IPSEC_TUNNEL_IPV4 = 1,
  53         /**< Outer header is IPv4 */
  54         RTE_SECURITY_IPSEC_TUNNEL_IPV6,
  55         /**< Outer header is IPv6 */
  56 };
  57
  58 /**
  59  * Security context for crypto/eth devices
  60  *
  61  * Security instance for each driver to register security operations.
  62  * The application can get the security context from the crypto/eth device id
  63  * using the APIs rte_cryptodev_get_sec_ctx()/rte_eth_dev_get_sec_ctx()
  64  * This structure is used to identify the device(crypto/eth) for which the
  65  * security operations need to be performed.
  66  */
  67 struct rte_security_ctx {
  68         void *device;
  69         /**< Crypto/ethernet device attached */
  70         const struct rte_security_ops *ops;
  71         /**< Pointer to security ops for the device */
  72         uint16_t sess_cnt;
  73         /**< Number of sessions attached to this context */
  74 };
  75
  76 /**
  77  * IPSEC tunnel parameters
  78  *
  79  * These parameters are used to build outbound tunnel headers.
  80  */
  81 struct rte_security_ipsec_tunnel_param {
  82         enum rte_security_ipsec_tunnel_type type;
  83         /**< Tunnel type: IPv4 or IPv6 */
  84         RTE_STD_C11
  85         union {
  86                 struct {
  87                         struct in_addr src_ip;
  88                         /**< IPv4 source address */
  89                         struct in_addr dst_ip;
  90                         /**< IPv4 destination address */
  91                         uint8_t dscp;
  92                         /**< IPv4 Differentiated Services Code Point */
  93                         uint8_t df;
  94                         /**< IPv4 Don't Fragment bit */
  95                         uint8_t ttl;
  96                         /**< IPv4 Time To Live */
  97                 } ipv4;
  98                 /**< IPv4 header parameters */
  99                 struct {
 100                         struct in6_addr src_addr;
 101                         /**< IPv6 source address */
 102                         struct in6_addr dst_addr;
 103                         /**< IPv6 destination address */
 104                         uint8_t dscp;
 105                         /**< IPv6 Differentiated Services Code Point */
 106                         uint32_t flabel;
 107                         /**< IPv6 flow label */
 108                         uint8_t hlimit;
 109                         /**< IPv6 hop limit */
 110                 } ipv6;
 111                 /**< IPv6 header parameters */
 112         };
 113 };
 114
 115 /**
 116  * IPsec Security Association option flags
 117  */
 118 struct rte_security_ipsec_sa_options {
 119         /**< Extended Sequence Numbers (ESN)
 120          *
 121          * * 1: Use extended (64 bit) sequence numbers
 122          * * 0: Use normal sequence numbers
 123          */
 124         uint32_t esn : 1;
 125
 126         /**< UDP encapsulation
 127          *
 128          * * 1: Do UDP encapsulation/decapsulation so that IPSEC packets can
 129          *      traverse through NAT boxes.
 130          * * 0: No UDP encapsulation
 131          */
 132         uint32_t udp_encap : 1;
 133
 134         /**< Copy DSCP bits
 135          *
 136          * * 1: Copy IPv4 or IPv6 DSCP bits from inner IP header to
 137          *      the outer IP header in encapsulation, and vice versa in
 138          *      decapsulation.
 139          * * 0: Do not change DSCP field.
 140          */
 141         uint32_t copy_dscp : 1;
 142
 143         /**< Copy IPv6 Flow Label
 144          *
 145          * * 1: Copy IPv6 flow label from inner IPv6 header to the
 146          *      outer IPv6 header.
 147          * * 0: Outer header is not modified.
 148          */
 149         uint32_t copy_flabel : 1;
 150
 151         /**< Copy IPv4 Don't Fragment bit
 152          *
 153          * * 1: Copy the DF bit from the inner IPv4 header to the outer
 154          *      IPv4 header.
 155          * * 0: Outer header is not modified.
 156          */
 157         uint32_t copy_df : 1;
 158
 159         /**< Decrement inner packet Time To Live (TTL) field
 160          *
 161          * * 1: In tunnel mode, decrement inner packet IPv4 TTL or
 162          *      IPv6 Hop Limit after tunnel decapsulation, or before tunnel
 163          *      encapsulation.
 164          * * 0: Inner packet is not modified.
 165          */
 166         uint32_t dec_ttl : 1;
 167 };
 168
 169 /** IPSec security association direction */
 170 enum rte_security_ipsec_sa_direction {
 171         RTE_SECURITY_IPSEC_SA_DIR_EGRESS,
 172         /**< Encrypt and generate digest */
 173         RTE_SECURITY_IPSEC_SA_DIR_INGRESS,
 174         /**< Verify digest and decrypt */
 175 };
 176
 177 /**
 178  * IPsec security association configuration data.
 179  *
 180  * This structure contains data required to create an IPsec SA security session.
 181  */
 182 struct rte_security_ipsec_xform {
 183         uint32_t spi;
 184         /**< SA security parameter index */
 185         uint32_t salt;
 186         /**< SA salt */
 187         struct rte_security_ipsec_sa_options options;
 188         /**< various SA options */
 189         enum rte_security_ipsec_sa_direction direction;
 190         /**< IPSec SA Direction - Egress/Ingress */
 191         enum rte_security_ipsec_sa_protocol proto;
 192         /**< IPsec SA Protocol - AH/ESP */
 193         enum rte_security_ipsec_sa_mode mode;
 194         /**< IPsec SA Mode - transport/tunnel */
 195         struct rte_security_ipsec_tunnel_param tunnel;
 196         /**< Tunnel parameters, NULL for transport mode */
 197         uint64_t esn_soft_limit;
 198         /**< ESN for which the overflow event need to be raised */
 199 };
 200
 201 /**
 202  * MACsec security session configuration
 203  */
 204 struct rte_security_macsec_xform {
 205         /** To be Filled */
 206         int dummy;
 207 };
 208
 209 /**
 210  * Security session action type.
 211  */
 212 enum rte_security_session_action_type {
 213         RTE_SECURITY_ACTION_TYPE_NONE,
 214         /**< No security actions */
 215         RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO,
 216         /**< Crypto processing for security protocol is processed inline
 217          * during transmission
 218          */
 219         RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL,
 220         /**< All security protocol processing is performed inline during
 221          * transmission
 222          */
 223         RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
 224         /**< All security protocol processing including crypto is performed
 225          * on a lookaside accelerator
 226          */
 227 };
 228
 229 /** Security session protocol definition */
 230 enum rte_security_session_protocol {
 231         RTE_SECURITY_PROTOCOL_IPSEC = 1,
 232         /**< IPsec Protocol */
 233         RTE_SECURITY_PROTOCOL_MACSEC,
 234         /**< MACSec Protocol */
 235 };
 236
 237 /**
 238  * Security session configuration
 239  */
 240 struct rte_security_session_conf {
 241         enum rte_security_session_action_type action_type;
 242         /**< Type of action to be performed on the session */
 243         enum rte_security_session_protocol protocol;
 244         /**< Security protocol to be configured */
 245         RTE_STD_C11
 246         union {
 247                 struct rte_security_ipsec_xform ipsec;
 248                 struct rte_security_macsec_xform macsec;
 249         };
 250         /**< Configuration parameters for security session */
 251         struct rte_crypto_sym_xform *crypto_xform;
 252         /**< Security Session Crypto Transformations */
 253         void *userdata;
 254         /**< Application specific userdata to be saved with session */
 255 };
 256
 257 struct rte_security_session {
 258         void *sess_private_data;
 259         /**< Private session material */
 260 };
 261
 262 /**
 263  * Create security session as specified by the session configuration
 264  *
 265  * @param   instance    security instance
 266  * @param   conf        session configuration parameters
 267  * @param   mp          mempool to allocate session objects from
 268  * @return
 269  *  - On success, pointer to session
 270  *  - On failure, NULL
 271  */
 272 struct rte_security_session * __rte_experimental
 273 rte_security_session_create(struct rte_security_ctx *instance,
 274                             struct rte_security_session_conf *conf,
 275                             struct rte_mempool *mp);
 276
 277 /**
 278  * Update security session as specified by the session configuration
 279  *
 280  * @param   instance    security instance
 281  * @param   sess        session to update parameters
 282  * @param   conf        update configuration parameters
 283  * @return
 284  *  - On success returns 0
 285  *  - On failure return errno
 286  */
 287 int __rte_experimental
 288 rte_security_session_update(struct rte_security_ctx *instance,
 289                             struct rte_security_session *sess,
 290                             struct rte_security_session_conf *conf);
 291
 292 /**
 293  * Get the size of the security session data for a device.
 294  *
 295  * @param   instance    security instance.
 296  *
 297  * @return
 298  *   - Size of the private data, if successful
 299  *   - 0 if device is invalid or does not support the operation.
 300  */
 301 unsigned int __rte_experimental
 302 rte_security_session_get_size(struct rte_security_ctx *instance);
 303
 304 /**
 305  * Free security session header and the session private data and
 306  * return it to its original mempool.
 307  *
 308  * @param   instance    security instance
 309  * @param   sess        security session to freed
 310  *
 311  * @return
 312  *  - 0 if successful.
 313  *  - -EINVAL if session is NULL.
 314  *  - -EBUSY if not all device private data has been freed.
 315  */
 316 int __rte_experimental
 317 rte_security_session_destroy(struct rte_security_ctx *instance,
 318                              struct rte_security_session *sess);
 319
 320 /**
 321  *  Updates the buffer with device-specific defined metadata
 322  *
 323  * @param       instance        security instance
 324  * @param       sess            security session
 325  * @param       mb              packet mbuf to set metadata on.
 326  * @param       params          device-specific defined parameters
 327  *                              required for metadata
 328  *
 329  * @return
 330  *  - On success, zero.
 331  *  - On failure, a negative value.
 332  */
 333 int __rte_experimental
 334 rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
 335                               struct rte_security_session *sess,
 336                               struct rte_mbuf *mb, void *params);
 337
 338 /**
 339  * Get userdata associated with the security session. Device specific metadata
 340  * provided would be used to uniquely identify the security session being
 341  * referred to. This userdata would be registered while creating the session,
 342  * and application can use this to identify the SA etc.
 343  *
 344  * Device specific metadata would be set in mbuf for inline processed inbound
 345  * packets. In addition, the same metadata would be set for IPsec events
 346  * reported by rte_eth_event framework.
 347  *
 348  * @param   instance    security instance
 349  * @param   md          device-specific metadata
 350  *
 351  * @return
 352  *  - On success, userdata
 353  *  - On failure, NULL
 354  */
 355 void * __rte_experimental
 356 rte_security_get_userdata(struct rte_security_ctx *instance, uint64_t md);
 357
 358 /**
 359  * Attach a session to a symmetric crypto operation
 360  *
 361  * @param       sym_op  crypto operation
 362  * @param       sess    security session
 363  */
 364 static inline int __rte_experimental
 365 __rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
 366                               struct rte_security_session *sess)
 367 {
 368         sym_op->sec_session = sess;
 369
 370         return 0;
 371 }
 372
 373 static inline void * __rte_experimental
 374 get_sec_session_private_data(const struct rte_security_session *sess)
 375 {
 376         return sess->sess_private_data;
 377 }
 378
 379 static inline void __rte_experimental
 380 set_sec_session_private_data(struct rte_security_session *sess,
 381                              void *private_data)
 382 {
 383         sess->sess_private_data = private_data;
 384 }
 385
 386 /**
 387  * Attach a session to a crypto operation.
 388  * This API is needed only in case of RTE_SECURITY_SESS_CRYPTO_PROTO_OFFLOAD
 389  * For other rte_security_session_action_type, ol_flags in rte_mbuf may be
 390  * defined to perform security operations.
 391  *
 392  * @param       op      crypto operation
 393  * @param       sess    security session
 394  */
 395 static inline int __rte_experimental
 396 rte_security_attach_session(struct rte_crypto_op *op,
 397                             struct rte_security_session *sess)
 398 {
 399         if (unlikely(op->type != RTE_CRYPTO_OP_TYPE_SYMMETRIC))
 400                 return -EINVAL;
 401
 402         op->sess_type =  RTE_CRYPTO_OP_SECURITY_SESSION;
 403
 404         return __rte_security_attach_session(op->sym, sess);
 405 }
 406
 407 struct rte_security_macsec_stats {
 408         uint64_t reserved;
 409 };
 410
 411 struct rte_security_ipsec_stats {
 412         uint64_t reserved;
 413
 414 };
 415
 416 struct rte_security_stats {
 417         enum rte_security_session_protocol protocol;
 418         /**< Security protocol to be configured */
 419
 420         RTE_STD_C11
 421         union {
 422                 struct rte_security_macsec_stats macsec;
 423                 struct rte_security_ipsec_stats ipsec;
 424         };
 425 };
 426
 427 /**
 428  * Get security session statistics
 429  *
 430  * @param       instance        security instance
 431  * @param       sess            security session
 432  * @param       stats           statistics
 433  * @return
 434  *  - On success return 0
 435  *  - On failure errno
 436  */
 437 int __rte_experimental
 438 rte_security_session_stats_get(struct rte_security_ctx *instance,
 439                                struct rte_security_session *sess,
 440                                struct rte_security_stats *stats);
 441
 442 /**
 443  * Security capability definition
 444  */
 445 struct rte_security_capability {
 446         enum rte_security_session_action_type action;
 447         /**< Security action type*/
 448         enum rte_security_session_protocol protocol;
 449         /**< Security protocol */
 450         RTE_STD_C11
 451         union {
 452                 struct {
 453                         enum rte_security_ipsec_sa_protocol proto;
 454                         /**< IPsec SA protocol */
 455                         enum rte_security_ipsec_sa_mode mode;
 456                         /**< IPsec SA mode */
 457                         enum rte_security_ipsec_sa_direction direction;
 458                         /**< IPsec SA direction */
 459                         struct rte_security_ipsec_sa_options options;
 460                         /**< IPsec SA supported options */
 461                 } ipsec;
 462                 /**< IPsec capability */
 463                 struct {
 464                         /* To be Filled */
 465                         int dummy;
 466                 } macsec;
 467                 /**< MACsec capability */
 468         };
 469
 470         const struct rte_cryptodev_capabilities *crypto_capabilities;
 471         /**< Corresponding crypto capabilities for security capability  */
 472
 473         uint32_t ol_flags;
 474         /**< Device offload flags */
 475 };
 476
 477 #define RTE_SECURITY_TX_OLOAD_NEED_MDATA        0x00000001
 478 /**< HW needs metadata update, see rte_security_set_pkt_metadata().
 479  */
 480
 481 #define RTE_SECURITY_TX_HW_TRAILER_OFFLOAD      0x00000002
 482 /**< HW constructs trailer of packets
 483  * Transmitted packets will have the trailer added to them
 484  * by hardawre. The next protocol field will be based on
 485  * the mbuf->inner_esp_next_proto field.
 486  */
 487 #define RTE_SECURITY_RX_HW_TRAILER_OFFLOAD      0x00010000
 488 /**< HW removes trailer of packets
 489  * Received packets have no trailer, the next protocol field
 490  * is supplied in the mbuf->inner_esp_next_proto field.
 491  * Inner packet is not modified.
 492  */
 493
 494 /**
 495  * Security capability index used to query a security instance for a specific
 496  * security capability
 497  */
 498 struct rte_security_capability_idx {
 499         enum rte_security_session_action_type action;
 500         enum rte_security_session_protocol protocol;
 501
 502         RTE_STD_C11
 503         union {
 504                 struct {
 505                         enum rte_security_ipsec_sa_protocol proto;
 506                         enum rte_security_ipsec_sa_mode mode;
 507                         enum rte_security_ipsec_sa_direction direction;
 508                 } ipsec;
 509         };
 510 };
 511
 512 /**
 513  *  Returns array of security instance capabilities
 514  *
 515  * @param       instance        Security instance.
 516  *
 517  * @return
 518  *   - Returns array of security capabilities.
 519  *   - Return NULL if no capabilities available.
 520  */
 521 const struct rte_security_capability * __rte_experimental
 522 rte_security_capabilities_get(struct rte_security_ctx *instance);
 523
 524 /**
 525  * Query if a specific capability is available on security instance
 526  *
 527  * @param       instance        security instance.
 528  * @param       idx             security capability index to match against
 529  *
 530  * @return
 531  *   - Returns pointer to security capability on match of capability
 532  *     index criteria.
 533  *   - Return NULL if the capability not matched on security instance.
 534  */
 535 const struct rte_security_capability * __rte_experimental
 536 rte_security_capability_get(struct rte_security_ctx *instance,
 537                             struct rte_security_capability_idx *idx);
 538
 539 #ifdef __cplusplus
 540 }
 541 #endif
 542
 543 #endif /* _RTE_SECURITY_H_ */