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