1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2018 Cavium Networks 3 */ 4 5 #ifndef _RTE_CRYPTO_ASYM_H_ 6 #define _RTE_CRYPTO_ASYM_H_ 7 8 /** 9 * @file rte_crypto_asym.h 10 * 11 * RTE Definitions for Asymmetric Cryptography 12 * 13 * Defines asymmetric algorithms and modes, as well as supported 14 * asymmetric crypto operations. 15 */ 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include <string.h> 22 #include <stdint.h> 23 24 #include <rte_memory.h> 25 #include <rte_mempool.h> 26 #include <rte_common.h> 27 28 #include "rte_crypto_sym.h" 29 30 struct rte_cryptodev_asym_session; 31 32 /** asym xform type name strings */ 33 __rte_deprecated 34 extern const char * 35 rte_crypto_asym_xform_strings[]; 36 37 /** asym key exchange operation type name strings */ 38 extern const char * 39 rte_crypto_asym_ke_strings[]; 40 41 /** asym operations type name strings */ 42 extern const char * 43 rte_crypto_asym_op_strings[]; 44 45 #define RTE_CRYPTO_ASYM_FLAG_PUB_KEY_NO_PADDING RTE_BIT32(0) 46 /**< 47 * Flag to denote public key will be returned without leading zero bytes 48 * and if the flag is not set, public key will be padded to the left with 49 * zeros to the size of the underlying algorithm (default) 50 */ 51 #define RTE_CRYPTO_ASYM_FLAG_SHARED_KEY_NO_PADDING RTE_BIT32(1) 52 /**< 53 * Flag to denote shared secret will be returned without leading zero bytes 54 * and if the flag is not set, shared secret will be padded to the left with 55 * zeros to the size of the underlying algorithm (default) 56 */ 57 58 /** 59 * List of elliptic curves. This enum aligns with 60 * TLS "Supported Groups" registry (previously known as 61 * NamedCurve registry). FFDH groups are not, and will not 62 * be included in this list. 63 * Deprecation for selected curve in TLS does not deprecate 64 * the selected curve in Cryptodev. 65 * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml 66 */ 67 enum rte_crypto_curve_id { 68 RTE_CRYPTO_EC_GROUP_SECP192R1 = 19, 69 RTE_CRYPTO_EC_GROUP_SECP224R1 = 21, 70 RTE_CRYPTO_EC_GROUP_SECP256R1 = 23, 71 RTE_CRYPTO_EC_GROUP_SECP384R1 = 24, 72 RTE_CRYPTO_EC_GROUP_SECP521R1 = 25 73 }; 74 75 /** 76 * Asymmetric crypto transformation types. 77 * Each xform type maps to one asymmetric algorithm 78 * performing specific operation 79 * 80 */ 81 enum rte_crypto_asym_xform_type { 82 RTE_CRYPTO_ASYM_XFORM_UNSPECIFIED = 0, 83 /**< Invalid xform. */ 84 RTE_CRYPTO_ASYM_XFORM_NONE, 85 /**< Xform type None. 86 * May be supported by PMD to support 87 * passthrough op for debugging purpose. 88 * if xform_type none , op_type is disregarded. 89 */ 90 RTE_CRYPTO_ASYM_XFORM_RSA, 91 /**< RSA. Performs Encrypt, Decrypt, Sign and Verify. 92 * Refer to rte_crypto_asym_op_type 93 */ 94 RTE_CRYPTO_ASYM_XFORM_DH, 95 /**< Diffie-Hellman. 96 * Performs Key Generate and Shared Secret Compute. 97 * Refer to rte_crypto_asym_op_type 98 */ 99 RTE_CRYPTO_ASYM_XFORM_DSA, 100 /**< Digital Signature Algorithm 101 * Performs Signature Generation and Verification. 102 * Refer to rte_crypto_asym_op_type 103 */ 104 RTE_CRYPTO_ASYM_XFORM_MODINV, 105 /**< Modular Multiplicative Inverse 106 * Perform Modular Multiplicative Inverse b^(-1) mod n 107 */ 108 RTE_CRYPTO_ASYM_XFORM_MODEX, 109 /**< Modular Exponentiation 110 * Perform Modular Exponentiation b^e mod n 111 */ 112 RTE_CRYPTO_ASYM_XFORM_ECDSA, 113 /**< Elliptic Curve Digital Signature Algorithm 114 * Perform Signature Generation and Verification. 115 */ 116 RTE_CRYPTO_ASYM_XFORM_ECDH, 117 /**< Elliptic Curve Diffie Hellman */ 118 RTE_CRYPTO_ASYM_XFORM_ECPM, 119 /**< Elliptic Curve Point Multiplication */ 120 RTE_CRYPTO_ASYM_XFORM_ECFPM, 121 /**< Elliptic Curve Fixed Point Multiplication */ 122 RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END 123 /**< End of list */ 124 }; 125 126 /** 127 * Asymmetric crypto operation type variants 128 */ 129 enum rte_crypto_asym_op_type { 130 RTE_CRYPTO_ASYM_OP_ENCRYPT, 131 /**< Asymmetric Encrypt operation */ 132 RTE_CRYPTO_ASYM_OP_DECRYPT, 133 /**< Asymmetric Decrypt operation */ 134 RTE_CRYPTO_ASYM_OP_SIGN, 135 /**< Signature Generation operation */ 136 RTE_CRYPTO_ASYM_OP_VERIFY, 137 /**< Signature Verification operation */ 138 RTE_CRYPTO_ASYM_OP_LIST_END 139 }; 140 141 /** 142 * Asymmetric crypto key exchange operation type 143 */ 144 enum rte_crypto_asym_ke_type { 145 RTE_CRYPTO_ASYM_KE_PRIV_KEY_GENERATE, 146 /**< Private Key generation operation */ 147 RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE, 148 /**< Public Key generation operation */ 149 RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE, 150 /**< Shared Secret compute operation */ 151 RTE_CRYPTO_ASYM_KE_PUB_KEY_VERIFY 152 /**< Public Key Verification - can be used for 153 * elliptic curve point validation. 154 */ 155 }; 156 157 /** 158 * Padding types for RSA signature. 159 */ 160 enum rte_crypto_rsa_padding_type { 161 RTE_CRYPTO_RSA_PADDING_NONE = 0, 162 /**< RSA no padding scheme */ 163 RTE_CRYPTO_RSA_PADDING_PKCS1_5, 164 /**< RSA PKCS#1 PKCS1-v1_5 padding scheme. For signatures block type 01, 165 * for encryption block type 02 are used. 166 */ 167 RTE_CRYPTO_RSA_PADDING_OAEP, 168 /**< RSA PKCS#1 OAEP padding scheme */ 169 RTE_CRYPTO_RSA_PADDING_PSS, 170 /**< RSA PKCS#1 PSS padding scheme */ 171 RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END 172 }; 173 174 /** 175 * RSA private key type enumeration 176 * 177 * enumerates private key format required to perform RSA crypto 178 * transform. 179 * 180 */ 181 enum rte_crypto_rsa_priv_key_type { 182 RTE_RSA_KEY_TYPE_EXP, 183 /**< RSA private key is an exponent */ 184 RTE_RSA_KEY_TYPE_QT, 185 /**< RSA private key is in quintuple format 186 * See rte_crypto_rsa_priv_key_qt 187 */ 188 }; 189 190 /** 191 * Buffer to hold crypto params required for asym operations. 192 * 193 * These buffers can be used for both input to PMD and output from PMD. When 194 * used for output from PMD, application has to ensure the buffer is large 195 * enough to hold the target data. 196 * 197 * If an operation requires the PMD to generate a random number, 198 * and the device supports CSRNG, 'data' should be set to NULL. 199 * The crypto parameter in question will not be used by the PMD, 200 * as it is internally generated. 201 */ 202 typedef struct rte_crypto_param_t { 203 uint8_t *data; 204 /**< pointer to buffer holding data */ 205 rte_iova_t iova; 206 /**< IO address of data buffer */ 207 size_t length; 208 /**< length of data in bytes */ 209 } rte_crypto_param; 210 211 /** Unsigned big-integer in big-endian format */ 212 typedef rte_crypto_param rte_crypto_uint; 213 214 /** 215 * Structure for elliptic curve point 216 */ 217 struct rte_crypto_ec_point { 218 rte_crypto_param x; 219 /**< X coordinate */ 220 rte_crypto_param y; 221 /**< Y coordinate */ 222 }; 223 224 /** 225 * Structure describing RSA private key in quintuple format. 226 * See PKCS V1.5 RSA Cryptography Standard. 227 */ 228 struct rte_crypto_rsa_priv_key_qt { 229 rte_crypto_uint p; 230 /**< the first factor */ 231 rte_crypto_uint q; 232 /**< the second factor */ 233 rte_crypto_uint dP; 234 /**< the first factor's CRT exponent */ 235 rte_crypto_uint dQ; 236 /**< the second's factor's CRT exponent */ 237 rte_crypto_uint qInv; 238 /**< the CRT coefficient */ 239 }; 240 241 /** 242 * RSA padding type 243 */ 244 struct rte_crypto_rsa_padding { 245 enum rte_crypto_rsa_padding_type type; 246 /**< RSA padding scheme to be used for transform */ 247 enum rte_crypto_auth_algorithm hash; 248 /**< 249 * RSA padding hash algorithm 250 * Valid hash algorithms are: 251 * MD5, SHA1, SHA224, SHA256, SHA384, SHA512 252 * 253 * When a specific padding type is selected, the following rules apply: 254 * - RTE_CRYPTO_RSA_PADDING_NONE: 255 * This field is ignored by the PMD 256 * 257 * - RTE_CRYPTO_RSA_PADDING_PKCS1_5: 258 * When signing an operation this field is used to determine value 259 * of the DigestInfo structure, therefore specifying which algorithm 260 * was used to create the message digest. 261 * When doing encryption/decryption this field is ignored for this 262 * padding type. 263 * 264 * - RTE_CRYPTO_RSA_PADDING_OAEP 265 * This field shall be set with the hash algorithm used 266 * in the padding scheme 267 * 268 * - RTE_CRYPTO_RSA_PADDING_PSS 269 * This field shall be set with the hash algorithm used 270 * in the padding scheme (and to create the input message digest) 271 */ 272 enum rte_crypto_auth_algorithm mgf1hash; 273 /**< 274 * Hash algorithm to be used for mask generation if the 275 * padding scheme is either OAEP or PSS. If the padding 276 * scheme is unspecified a data hash algorithm is used 277 * for mask generation. Valid hash algorithms are: 278 * MD5, SHA1, SHA224, SHA256, SHA384, SHA512 279 */ 280 uint16_t pss_saltlen; 281 /**< 282 * RSA PSS padding salt length 283 * 284 * Used only when RTE_CRYPTO_RSA_PADDING_PSS padding is selected, 285 * otherwise ignored. 286 */ 287 rte_crypto_param oaep_label; 288 /**< 289 * RSA OAEP padding optional label 290 * 291 * Used only when RTE_CRYPTO_RSA_PADDING_OAEP padding is selected, 292 * otherwise ignored. If label.data == NULL, a default 293 * label (empty string) is used. 294 */ 295 }; 296 297 /** 298 * Asymmetric RSA transform data 299 * 300 * Structure describing RSA xform params 301 * 302 */ 303 struct rte_crypto_rsa_xform { 304 rte_crypto_uint n; 305 /**< the RSA modulus */ 306 rte_crypto_uint e; 307 /**< the RSA public exponent */ 308 309 enum rte_crypto_rsa_priv_key_type key_type; 310 311 RTE_STD_C11 312 union { 313 rte_crypto_uint d; 314 /**< the RSA private exponent */ 315 struct rte_crypto_rsa_priv_key_qt qt; 316 /**< qt - Private key in quintuple format */ 317 }; 318 }; 319 320 /** 321 * Asymmetric Modular exponentiation transform data 322 * 323 * Structure describing modular exponentiation xform param 324 * 325 */ 326 struct rte_crypto_modex_xform { 327 rte_crypto_uint modulus; 328 /**< Modulus data for modexp transform operation */ 329 rte_crypto_uint exponent; 330 /**< Exponent of the modexp transform operation */ 331 }; 332 333 /** 334 * Asymmetric modular multiplicative inverse transform operation 335 * 336 * Structure describing modular multiplicative inverse transform 337 * 338 */ 339 struct rte_crypto_modinv_xform { 340 rte_crypto_uint modulus; 341 /**< Modulus data for modular multiplicative inverse operation */ 342 }; 343 344 /** 345 * Asymmetric DH transform data 346 * 347 * Structure describing deffie-hellman xform params 348 * 349 */ 350 struct rte_crypto_dh_xform { 351 rte_crypto_uint p; 352 /**< Prime modulus data */ 353 rte_crypto_uint g; 354 /**< DH Generator */ 355 }; 356 357 /** 358 * Asymmetric Digital Signature transform operation 359 * 360 * Structure describing DSA xform params 361 * 362 */ 363 struct rte_crypto_dsa_xform { 364 rte_crypto_uint p; 365 /**< Prime modulus */ 366 rte_crypto_uint q; 367 /**< Order of the subgroup */ 368 rte_crypto_uint g; 369 /**< Generator of the subgroup */ 370 rte_crypto_uint x; 371 /**< x: Private key of the signer */ 372 }; 373 374 /** 375 * Asymmetric elliptic curve transform data 376 * 377 * Structure describing all EC based xform params 378 * 379 */ 380 struct rte_crypto_ec_xform { 381 enum rte_crypto_curve_id curve_id; 382 /**< Pre-defined ec groups */ 383 }; 384 385 /** 386 * Operations params for modular operations: 387 * exponentiation and multiplicative inverse 388 * 389 */ 390 struct rte_crypto_mod_op_param { 391 rte_crypto_uint base; 392 /** Base of modular exponentiation/multiplicative inverse */ 393 rte_crypto_uint result; 394 /** Result of modular exponentiation/multiplicative inverse */ 395 }; 396 397 /** 398 * RSA operation params 399 * 400 */ 401 struct rte_crypto_rsa_op_param { 402 enum rte_crypto_asym_op_type op_type; 403 /**< Type of RSA operation for transform */ 404 405 rte_crypto_param message; 406 /**< 407 * Pointer to input data 408 * - to be encrypted for RSA public encrypt. 409 * - to be signed for RSA sign generation. 410 * - to be authenticated for RSA sign verification. 411 * 412 * Pointer to output data 413 * - for RSA private decrypt. 414 * In this case the underlying array should have been 415 * allocated with enough memory to hold plaintext output 416 * (i.e. must be at least RSA key size). The message.length 417 * field should be 0 and will be overwritten by the PMD 418 * with the decrypted length. 419 */ 420 421 rte_crypto_param cipher; 422 /**< 423 * Pointer to input data 424 * - to be decrypted for RSA private decrypt. 425 * 426 * Pointer to output data 427 * - for RSA public encrypt. 428 * In this case the underlying array should have been allocated 429 * with enough memory to hold ciphertext output (i.e. must be 430 * at least RSA key size). The cipher.length field should 431 * be 0 and will be overwritten by the PMD with the encrypted length. 432 * 433 * When RTE_CRYPTO_RSA_PADDING_NONE and RTE_CRYPTO_ASYM_OP_VERIFY 434 * selected, this is an output of decrypted signature. 435 */ 436 437 rte_crypto_param sign; 438 /**< 439 * Pointer to input data 440 * - to be verified for RSA public decrypt. 441 * 442 * Pointer to output data 443 * - for RSA private encrypt. 444 * In this case the underlying array should have been allocated 445 * with enough memory to hold signature output (i.e. must be 446 * at least RSA key size). The sign.length field should 447 * be 0 and will be overwritten by the PMD with the signature length. 448 */ 449 450 struct rte_crypto_rsa_padding padding; 451 /**< RSA padding information */ 452 }; 453 454 /** 455 * Diffie-Hellman Operations params. 456 * @note: 457 */ 458 struct rte_crypto_dh_op_param { 459 enum rte_crypto_asym_ke_type ke_type; 460 /**< Key exchange operation type */ 461 rte_crypto_uint priv_key; 462 /**< 463 * Output - generated private key when ke_type is 464 * RTE_CRYPTO_ASYM_KE_PRIV_KEY_GENERATE. 465 * 466 * Input - private key when ke_type is one of: 467 * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE, 468 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. 469 * 470 * In case priv_key.length is 0 and ke_type is set with 471 * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE, CSRNG capable 472 * device will generate a private key and use it for public 473 * key generation. 474 */ 475 rte_crypto_uint pub_key; 476 /**< 477 * Output - generated public key when ke_type is 478 * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE. 479 * 480 * Input - peer's public key when ke_type is 481 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. 482 */ 483 rte_crypto_uint shared_secret; 484 /**< 485 * Output - calculated shared secret when ke_type is 486 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. 487 */ 488 }; 489 490 /** 491 * Elliptic Curve Diffie-Hellman Operations params. 492 */ 493 struct rte_crypto_ecdh_op_param { 494 enum rte_crypto_asym_ke_type ke_type; 495 /**< Key exchange operation type */ 496 rte_crypto_uint priv_key; 497 /**< 498 * Output - generated private key when ke_type is 499 * RTE_CRYPTO_ASYM_KE_PRIVATE_KEY_GENERATE. 500 * 501 * Input - private key when ke_type is one of: 502 * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE, 503 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. 504 * 505 * In case priv_key.length is 0 and ke_type is set with 506 * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE, CSRNG capable 507 * device will generate private key and use it for public 508 * key generation. 509 */ 510 struct rte_crypto_ec_point pub_key; 511 /**< 512 * Output - generated public key when ke_type is 513 * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE. 514 * 515 * Input - peer's public key, when ke_type is one of: 516 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE, 517 * RTE_CRYPTO_ASYM_KE_EC_PUBLIC_KEY_VERIFY. 518 */ 519 struct rte_crypto_ec_point shared_secret; 520 /**< 521 * Output - calculated shared secret when ke_type is 522 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. 523 */ 524 }; 525 526 /** 527 * DSA Operations params 528 * 529 */ 530 struct rte_crypto_dsa_op_param { 531 enum rte_crypto_asym_op_type op_type; 532 /**< Signature Generation or Verification */ 533 rte_crypto_param message; 534 /**< input message to be signed or verified */ 535 rte_crypto_uint k; 536 /**< Per-message secret number, which is an integer 537 * in the interval (1, q-1). 538 * If the random number is generated by the PMD, 539 * the 'rte_crypto_param.data' parameter should be set to NULL. 540 */ 541 rte_crypto_uint r; 542 /**< dsa sign component 'r' value 543 * 544 * output if op_type = sign generate, 545 * input if op_type = sign verify 546 */ 547 rte_crypto_uint s; 548 /**< dsa sign component 's' value 549 * 550 * output if op_type = sign generate, 551 * input if op_type = sign verify 552 */ 553 rte_crypto_uint y; 554 /**< y : Public key of the signer. 555 * y = g^x mod p 556 */ 557 }; 558 559 /** 560 * ECDSA operation params 561 */ 562 struct rte_crypto_ecdsa_op_param { 563 enum rte_crypto_asym_op_type op_type; 564 /**< Signature generation or verification */ 565 566 rte_crypto_uint pkey; 567 /**< Private key of the signer for signature generation */ 568 569 struct rte_crypto_ec_point q; 570 /**< Public key of the signer for verification */ 571 572 rte_crypto_param message; 573 /**< Input message digest to be signed or verified */ 574 575 rte_crypto_uint k; 576 /**< The ECDSA per-message secret number, which is an integer 577 * in the interval (1, n-1). 578 * If the random number is generated by the PMD, 579 * the 'rte_crypto_param.data' parameter should be set to NULL. 580 */ 581 582 rte_crypto_uint r; 583 /**< r component of elliptic curve signature 584 * output : for signature generation 585 * input : for signature verification 586 */ 587 rte_crypto_uint s; 588 /**< s component of elliptic curve signature 589 * output : for signature generation 590 * input : for signature verification 591 */ 592 }; 593 594 /** 595 * Structure for EC point multiplication operation param 596 */ 597 struct rte_crypto_ecpm_op_param { 598 struct rte_crypto_ec_point p; 599 /**< x and y coordinates of input point */ 600 601 struct rte_crypto_ec_point r; 602 /**< x and y coordinates of resultant point */ 603 604 rte_crypto_param scalar; 605 /**< Scalar to multiply the input point */ 606 }; 607 608 /** 609 * Asymmetric crypto transform data 610 * 611 * Structure describing asym xforms. 612 */ 613 struct rte_crypto_asym_xform { 614 struct rte_crypto_asym_xform *next; 615 /**< Pointer to next xform to set up xform chain.*/ 616 enum rte_crypto_asym_xform_type xform_type; 617 /**< Asymmetric crypto transform */ 618 619 RTE_STD_C11 620 union { 621 struct rte_crypto_rsa_xform rsa; 622 /**< RSA xform parameters */ 623 624 struct rte_crypto_modex_xform modex; 625 /**< Modular Exponentiation xform parameters */ 626 627 struct rte_crypto_modinv_xform modinv; 628 /**< Modular Multiplicative Inverse xform parameters */ 629 630 struct rte_crypto_dh_xform dh; 631 /**< DH xform parameters */ 632 633 struct rte_crypto_dsa_xform dsa; 634 /**< DSA xform parameters */ 635 636 struct rte_crypto_ec_xform ec; 637 /**< EC xform parameters, used by elliptic curve based 638 * operations. 639 */ 640 }; 641 }; 642 643 /** 644 * Asymmetric Cryptographic Operation. 645 * 646 * Structure describing asymmetric crypto operation params. 647 * 648 */ 649 struct rte_crypto_asym_op { 650 RTE_STD_C11 651 union { 652 struct rte_cryptodev_asym_session *session; 653 /**< Handle for the initialised session context */ 654 struct rte_crypto_asym_xform *xform; 655 /**< Session-less API crypto operation parameters */ 656 }; 657 658 RTE_STD_C11 659 union { 660 struct rte_crypto_rsa_op_param rsa; 661 struct rte_crypto_mod_op_param modex; 662 struct rte_crypto_mod_op_param modinv; 663 struct rte_crypto_dh_op_param dh; 664 struct rte_crypto_ecdh_op_param ecdh; 665 struct rte_crypto_dsa_op_param dsa; 666 struct rte_crypto_ecdsa_op_param ecdsa; 667 struct rte_crypto_ecpm_op_param ecpm; 668 }; 669 uint16_t flags; 670 /**< 671 * Asymmetric crypto operation flags. 672 * Please refer to the RTE_CRYPTO_ASYM_FLAG_*. 673 */ 674 }; 675 676 #ifdef __cplusplus 677 } 678 #endif 679 680 #endif /* _RTE_CRYPTO_ASYM_H_ */ 681