lib/cryptodev/rte_crypto_asym.h

   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  * Asymmetric RSA transform data
 240  *
 241  * Structure describing RSA xform params
 242  *
 243  */
 244 struct rte_crypto_rsa_xform {
 245         rte_crypto_uint n;
 246         /**< the RSA modulus */
 247         rte_crypto_uint e;
 248         /**< the RSA public exponent */
 249
 250         enum rte_crypto_rsa_priv_key_type key_type;
 251
 252         RTE_STD_C11
 253         union {
 254                 rte_crypto_uint d;
 255                 /**< the RSA private exponent */
 256                 struct rte_crypto_rsa_priv_key_qt qt;
 257                 /**< qt - Private key in quintuple format */
 258         };
 259 };
 260
 261 /**
 262  * Asymmetric Modular exponentiation transform data
 263  *
 264  * Structure describing modular exponentiation xform param
 265  *
 266  */
 267 struct rte_crypto_modex_xform {
 268         rte_crypto_uint modulus;
 269         /**< Modulus data for modexp transform operation */
 270         rte_crypto_uint exponent;
 271         /**< Exponent of the modexp transform operation */
 272 };
 273
 274 /**
 275  * Asymmetric modular multiplicative inverse transform operation
 276  *
 277  * Structure describing modular multiplicative inverse transform
 278  *
 279  */
 280 struct rte_crypto_modinv_xform {
 281         rte_crypto_uint modulus;
 282         /**< Modulus data for modular multiplicative inverse operation */
 283 };
 284
 285 /**
 286  * Asymmetric DH transform data
 287  *
 288  * Structure describing deffie-hellman xform params
 289  *
 290  */
 291 struct rte_crypto_dh_xform {
 292         rte_crypto_uint p;
 293         /**< Prime modulus data */
 294         rte_crypto_uint g;
 295         /**< DH Generator */
 296 };
 297
 298 /**
 299  * Asymmetric Digital Signature transform operation
 300  *
 301  * Structure describing DSA xform params
 302  *
 303  */
 304 struct rte_crypto_dsa_xform {
 305         rte_crypto_uint p;
 306         /**< Prime modulus */
 307         rte_crypto_uint q;
 308         /**< Order of the subgroup */
 309         rte_crypto_uint g;
 310         /**< Generator of the subgroup */
 311         rte_crypto_uint x;
 312         /**< x: Private key of the signer */
 313 };
 314
 315 /**
 316  * Asymmetric elliptic curve transform data
 317  *
 318  * Structure describing all EC based xform params
 319  *
 320  */
 321 struct rte_crypto_ec_xform {
 322         enum rte_crypto_curve_id curve_id;
 323         /**< Pre-defined ec groups */
 324 };
 325
 326 /**
 327  * Operations params for modular operations:
 328  * exponentiation and multiplicative inverse
 329  *
 330  */
 331 struct rte_crypto_mod_op_param {
 332         rte_crypto_uint base;
 333         /** Base of modular exponentiation/multiplicative inverse */
 334         rte_crypto_uint result;
 335         /** Result of modular exponentiation/multiplicative inverse */
 336 };
 337
 338 /**
 339  * RSA operation params
 340  *
 341  */
 342 struct rte_crypto_rsa_op_param {
 343         enum rte_crypto_asym_op_type op_type;
 344         /**< Type of RSA operation for transform */
 345
 346         rte_crypto_param message;
 347         /**<
 348          * Pointer to input data
 349          * - to be encrypted for RSA public encrypt.
 350          * - to be signed for RSA sign generation.
 351          * - to be authenticated for RSA sign verification.
 352          *
 353          * Pointer to output data
 354          * - for RSA private decrypt.
 355          * In this case the underlying array should have been
 356          * allocated with enough memory to hold plaintext output
 357          * (i.e. must be at least RSA key size). The message.length
 358          * field should be 0 and will be overwritten by the PMD
 359          * with the decrypted length.
 360          *
 361          * All data is in Octet-string network byte order format.
 362          */
 363
 364         rte_crypto_param cipher;
 365         /**<
 366          * Pointer to input data
 367          * - to be decrypted for RSA private decrypt.
 368          *
 369          * Pointer to output data
 370          * - for RSA public encrypt.
 371          * In this case the underlying array should have been allocated
 372          * with enough memory to hold ciphertext output (i.e. must be
 373          * at least RSA key size). The cipher.length field should
 374          * be 0 and will be overwritten by the PMD with the encrypted length.
 375          *
 376          * All data is in Octet-string network byte order format.
 377          */
 378
 379         rte_crypto_param sign;
 380         /**<
 381          * Pointer to input data
 382          * - to be verified for RSA public decrypt.
 383          *
 384          * Pointer to output data
 385          * - for RSA private encrypt.
 386          * In this case the underlying array should have been allocated
 387          * with enough memory to hold signature output (i.e. must be
 388          * at least RSA key size). The sign.length field should
 389          * be 0 and will be overwritten by the PMD with the signature length.
 390          *
 391          * All data is in Octet-string network byte order format.
 392          */
 393
 394         enum rte_crypto_rsa_padding_type pad;
 395         /**< RSA padding scheme to be used for transform */
 396
 397         enum rte_crypto_auth_algorithm md;
 398         /**<
 399          * RSA padding hash algorithm
 400          * Valid hash algorithms are:
 401          * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
 402          *
 403          * When a specific padding type is selected, the following rule apply:
 404          * - RTE_CRYPTO_RSA_PADDING_NONE:
 405          * This field is ignored by the PMD
 406          *
 407          * - RTE_CRYPTO_RSA_PADDING_PKCS1_5:
 408          * For sign operation, this field is used to determine value
 409          * of the DigestInfo structure, therefore specifying which algorithm
 410          * was used to create the message digest.
 411          * For encryption/decryption, this field is ignored for this
 412          * padding type.
 413          *
 414          * - RTE_CRYPTO_RSA_PADDING_OAEP
 415          * This field shall be set with the hash algorithm used
 416          * in the padding scheme
 417          *
 418          * - RTE_CRYPTO_RSA_PADDING_PSS
 419          * This field shall be set with the hash algorithm used
 420          * in the padding scheme (and to create the input message digest)
 421          */
 422
 423         enum rte_crypto_auth_algorithm mgf1md;
 424         /**<
 425          * Hash algorithm to be used for mask generation if
 426          * padding scheme is either OAEP or PSS. If padding
 427          * scheme is unspecified data hash algorithm is used
 428          * for mask generation. Valid hash algorithms are:
 429          * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
 430          */
 431 };
 432
 433 /**
 434  * Diffie-Hellman Operations params.
 435  * @note:
 436  */
 437 struct rte_crypto_dh_op_param {
 438         enum rte_crypto_asym_ke_type ke_type;
 439         /**< Key exchange operation type */
 440         rte_crypto_uint priv_key;
 441         /**<
 442          * Output - generated private key when ke_type is
 443          * RTE_CRYPTO_ASYM_KE_PRIV_KEY_GENERATE.
 444          *
 445          * Input - private key when ke_type is one of:
 446          * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE,
 447          * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
 448          *
 449          * In case priv_key.length is 0 and ke_type is set with
 450          * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE, CSRNG capable
 451          * device will generate a private key and use it for public
 452          * key generation.
 453          */
 454         rte_crypto_uint pub_key;
 455         /**<
 456          * Output - generated public key when ke_type is
 457          * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE.
 458          *
 459          * Input - peer's public key when ke_type is
 460          * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
 461          */
 462         rte_crypto_uint shared_secret;
 463         /**<
 464          * Output - calculated shared secret when ke_type is
 465          * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
 466          */
 467 };
 468
 469 /**
 470  * Elliptic Curve Diffie-Hellman Operations params.
 471  */
 472 struct rte_crypto_ecdh_op_param {
 473         enum rte_crypto_asym_ke_type ke_type;
 474         /**< Key exchange operation type */
 475         rte_crypto_uint priv_key;
 476         /**<
 477          * Output - generated private key when ke_type is
 478          * RTE_CRYPTO_ASYM_KE_PRIVATE_KEY_GENERATE.
 479          *
 480          * Input - private key when ke_type is one of:
 481          * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE,
 482          * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
 483          *
 484          * In case priv_key.length is 0 and ke_type is set with
 485          * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE, CSRNG capable
 486          * device will generate private key and use it for public
 487          * key generation.
 488          */
 489         struct rte_crypto_ec_point pub_key;
 490         /**<
 491          * Output - generated public key when ke_type is
 492          * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE.
 493          *
 494          * Input - peer's public key, when ke_type is one of:
 495          * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE,
 496          * RTE_CRYPTO_ASYM_KE_EC_PUBLIC_KEY_VERIFY.
 497          */
 498         struct rte_crypto_ec_point shared_secret;
 499         /**<
 500          * Output - calculated shared secret when ke_type is
 501          * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
 502          */
 503 };
 504
 505 /**
 506  * DSA Operations params
 507  *
 508  */
 509 struct rte_crypto_dsa_op_param {
 510         enum rte_crypto_asym_op_type op_type;
 511         /**< Signature Generation or Verification */
 512         rte_crypto_param message;
 513         /**< input message to be signed or verified */
 514         rte_crypto_uint k;
 515         /**< Per-message secret number, which is an integer
 516          * in the interval (1, q-1).
 517          * If the random number is generated by the PMD,
 518          * the 'rte_crypto_param.data' parameter should be set to NULL.
 519          */
 520         rte_crypto_uint r;
 521         /**< dsa sign component 'r' value
 522          *
 523          * output if op_type = sign generate,
 524          * input if op_type = sign verify
 525          */
 526         rte_crypto_uint s;
 527         /**< dsa sign component 's' value
 528          *
 529          * output if op_type = sign generate,
 530          * input if op_type = sign verify
 531          */
 532         rte_crypto_uint y;
 533         /**< y : Public key of the signer.
 534          * y = g^x mod p
 535          */
 536 };
 537
 538 /**
 539  * ECDSA operation params
 540  */
 541 struct rte_crypto_ecdsa_op_param {
 542         enum rte_crypto_asym_op_type op_type;
 543         /**< Signature generation or verification */
 544
 545         rte_crypto_uint pkey;
 546         /**< Private key of the signer for signature generation */
 547
 548         struct rte_crypto_ec_point q;
 549         /**< Public key of the signer for verification */
 550
 551         rte_crypto_param message;
 552         /**< Input message digest to be signed or verified */
 553
 554         rte_crypto_uint k;
 555         /**< The ECDSA per-message secret number, which is an integer
 556          * in the interval (1, n-1).
 557          * If the random number is generated by the PMD,
 558          * the 'rte_crypto_param.data' parameter should be set to NULL.
 559          */
 560
 561         rte_crypto_uint r;
 562         /**< r component of elliptic curve signature
 563          *     output : for signature generation
 564          *     input  : for signature verification
 565          */
 566         rte_crypto_uint s;
 567         /**< s component of elliptic curve signature
 568          *     output : for signature generation
 569          *     input  : for signature verification
 570          */
 571 };
 572
 573 /**
 574  * Structure for EC point multiplication operation param
 575  */
 576 struct rte_crypto_ecpm_op_param {
 577         struct rte_crypto_ec_point p;
 578         /**< x and y coordinates of input point */
 579
 580         struct rte_crypto_ec_point r;
 581         /**< x and y coordinates of resultant point */
 582
 583         rte_crypto_param scalar;
 584         /**< Scalar to multiply the input point */
 585 };
 586
 587 /**
 588  * Asymmetric crypto transform data
 589  *
 590  * Structure describing asym xforms.
 591  */
 592 struct rte_crypto_asym_xform {
 593         struct rte_crypto_asym_xform *next;
 594         /**< Pointer to next xform to set up xform chain.*/
 595         enum rte_crypto_asym_xform_type xform_type;
 596         /**< Asymmetric crypto transform */
 597
 598         RTE_STD_C11
 599         union {
 600                 struct rte_crypto_rsa_xform rsa;
 601                 /**< RSA xform parameters */
 602
 603                 struct rte_crypto_modex_xform modex;
 604                 /**< Modular Exponentiation xform parameters */
 605
 606                 struct rte_crypto_modinv_xform modinv;
 607                 /**< Modular Multiplicative Inverse xform parameters */
 608
 609                 struct rte_crypto_dh_xform dh;
 610                 /**< DH xform parameters */
 611
 612                 struct rte_crypto_dsa_xform dsa;
 613                 /**< DSA xform parameters */
 614
 615                 struct rte_crypto_ec_xform ec;
 616                 /**< EC xform parameters, used by elliptic curve based
 617                  * operations.
 618                  */
 619         };
 620 };
 621
 622 /**
 623  * Asymmetric Cryptographic Operation.
 624  *
 625  * Structure describing asymmetric crypto operation params.
 626  *
 627  */
 628 struct rte_crypto_asym_op {
 629         RTE_STD_C11
 630         union {
 631                 struct rte_cryptodev_asym_session *session;
 632                 /**< Handle for the initialised session context */
 633                 struct rte_crypto_asym_xform *xform;
 634                 /**< Session-less API crypto operation parameters */
 635         };
 636
 637         RTE_STD_C11
 638         union {
 639                 struct rte_crypto_rsa_op_param rsa;
 640                 struct rte_crypto_mod_op_param modex;
 641                 struct rte_crypto_mod_op_param modinv;
 642                 struct rte_crypto_dh_op_param dh;
 643                 struct rte_crypto_ecdh_op_param ecdh;
 644                 struct rte_crypto_dsa_op_param dsa;
 645                 struct rte_crypto_ecdsa_op_param ecdsa;
 646                 struct rte_crypto_ecpm_op_param ecpm;
 647         };
 648         uint16_t flags;
 649         /**<
 650          * Asymmetric crypto operation flags.
 651          * Please refer to the RTE_CRYPTO_ASYM_FLAG_*.
 652          */
 653 };
 654
 655 #ifdef __cplusplus
 656 }
 657 #endif
 658
 659 #endif /* _RTE_CRYPTO_ASYM_H_ */