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