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