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