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