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