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