lib/librte_security/rte_security.h

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