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