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