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