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