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