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