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_PKCS1_V1_5_BT0,
 116         /**< RSA PKCS#1 V1.5 Block Type 0 padding scheme
 117          * as described in rfc2313
 118          */
 119         RTE_CRYPTO_RSA_PKCS1_V1_5_BT1,
 120         /**< RSA PKCS#1 V1.5 Block Type 01 padding scheme
 121          * as described in rfc2313
 122          */
 123         RTE_CRYPTO_RSA_PKCS1_V1_5_BT2,
 124         /**< RSA PKCS#1 V1.5 Block Type 02 padding scheme
 125          * as described in rfc2313
 126          */
 127         RTE_CRYPTO_RSA_PADDING_OAEP,
 128         /**< RSA PKCS#1 OAEP padding scheme */
 129         RTE_CRYPTO_RSA_PADDING_PSS,
 130         /**< RSA PKCS#1 PSS padding scheme */
 131         RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END
 132 };
 133
 134 /**
 135  * RSA private key type enumeration
 136  *
 137  * enumerates private key format required to perform RSA crypto
 138  * transform.
 139  *
 140  */
 141 enum rte_crypto_rsa_priv_key_type {
 142         RTE_RSA_KEY_TYPE_EXP,
 143         /**< RSA private key is an exponent */
 144         RTE_RSA_KET_TYPE_QT,
 145         /**< RSA private key is in quintuple format
 146          * See rte_crypto_rsa_priv_key_qt
 147          */
 148 };
 149
 150 /**
 151  * Structure describing RSA private key in quintuple format.
 152  * See PKCS V1.5 RSA Cryptography Standard.
 153  */
 154 struct rte_crypto_rsa_priv_key_qt {
 155         rte_crypto_param p;
 156         /**< p - Private key component P
 157          * Private key component of RSA parameter  required for CRT method
 158          * of private key operations in Octet-string network byte order
 159          * format.
 160          */
 161
 162         rte_crypto_param q;
 163         /**< q - Private key component Q
 164          * Private key component of RSA parameter  required for CRT method
 165          * of private key operations in Octet-string network byte order
 166          * format.
 167          */
 168
 169         rte_crypto_param dP;
 170         /**< dP - 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          * dP = d mod ( p - 1 )
 175          */
 176
 177         rte_crypto_param dQ;
 178         /**< dQ - 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          * dQ = d mod ( q - 1 )
 183          */
 184
 185         rte_crypto_param qInv;
 186         /**< qInv - Private CRT component
 187          * Private CRT component of RSA parameter  required for CRT method
 188          * RSA private key operations in Octet-string network byte order
 189          * format.
 190          * qInv = inv q mod p
 191          */
 192 };
 193
 194 /**
 195  * Asymmetric RSA transform data
 196  *
 197  * Structure describing RSA xform params
 198  *
 199  */
 200 struct rte_crypto_rsa_xform {
 201         rte_crypto_param n;
 202         /**< n - Modulus
 203          * Modulus data of RSA operation in Octet-string network
 204          * byte order format.
 205          */
 206
 207         rte_crypto_param e;
 208         /**< e - Public key exponent
 209          * Public key exponent used for RSA public key operations in Octet-
 210          * string network byte order format.
 211          */
 212
 213         enum rte_crypto_rsa_priv_key_type key_type;
 214
 215         __extension__
 216         union {
 217                 rte_crypto_param d;
 218                 /**< d - Private key exponent
 219                  * Private key exponent used for RSA
 220                  * private key operations in
 221                  * Octet-string  network byte order format.
 222                  */
 223
 224                 struct rte_crypto_rsa_priv_key_qt qt;
 225                 /**< qt - Private key in quintuple format */
 226         };
 227 };
 228
 229 /**
 230  * Asymmetric Modular exponentiation transform data
 231  *
 232  * Structure describing modular exponentiation xform param
 233  *
 234  */
 235 struct rte_crypto_modex_xform {
 236         rte_crypto_param modulus;
 237         /**< modulus
 238          * Pointer to the modulus data for modexp transform operation
 239          * in octet-string network byte order format
 240          *
 241          * In case this number is equal to zero the driver shall set
 242          * the crypto op status field to RTE_CRYPTO_OP_STATUS_ERROR
 243          */
 244
 245         rte_crypto_param exponent;
 246         /**< exponent
 247          * Exponent of the modexp transform operation in
 248          * octet-string network byte order format
 249          */
 250 };
 251
 252 /**
 253  * Asymmetric modular multiplicative inverse transform operation
 254  *
 255  * Structure describing modular multiplicative inverse transform
 256  *
 257  */
 258 struct rte_crypto_modinv_xform {
 259         rte_crypto_param modulus;
 260         /**<
 261          * Pointer to the modulus data for modular multiplicative inverse
 262          * operation in octet-string network byte order format
 263          *
 264          * In case this number is equal to zero the driver shall set
 265          * the crypto op status field to RTE_CRYPTO_OP_STATUS_ERROR
 266          *
 267          * This number shall be relatively prime to base
 268          * in corresponding Modular Multiplicative Inverse
 269          * rte_crypto_mod_op_param
 270          */
 271 };
 272
 273 /**
 274  * Asymmetric DH transform data
 275  *
 276  * Structure describing deffie-hellman xform params
 277  *
 278  */
 279 struct rte_crypto_dh_xform {
 280         enum rte_crypto_asym_op_type type;
 281         /**< Setup xform for key generate or shared secret compute */
 282
 283         rte_crypto_param p;
 284         /**< p : Prime modulus data
 285          * DH prime modulus data in octet-string network byte order format.
 286          *
 287          */
 288
 289         rte_crypto_param g;
 290         /**< g : Generator
 291          * DH group generator data in octet-string network byte order
 292          * format.
 293          *
 294          */
 295 };
 296
 297 /**
 298  * Asymmetric Digital Signature transform operation
 299  *
 300  * Structure describing DSA xform params
 301  *
 302  */
 303 struct rte_crypto_dsa_xform {
 304         rte_crypto_param p;
 305         /**< p - Prime modulus
 306          * Prime modulus data for DSA operation in Octet-string network byte
 307          * order format.
 308          */
 309         rte_crypto_param q;
 310         /**< q : Order of the subgroup.
 311          * Order of the subgroup data in Octet-string network byte order
 312          * format.
 313          * (p-1) % q = 0
 314          */
 315         rte_crypto_param g;
 316         /**< g: Generator of the subgroup
 317          * Generator  data in Octet-string network byte order format.
 318          */
 319         rte_crypto_param x;
 320         /**< x: Private key of the signer in octet-string network
 321          * byte order format.
 322          * Used when app has pre-defined private key.
 323          * Valid only when xform chain is DSA ONLY.
 324          * if xform chain is DH private key generate + DSA, then DSA sign
 325          * compute will use internally generated key.
 326          */
 327 };
 328
 329 /**
 330  * Operations params for modular operations:
 331  * exponentiation and multiplicative inverse
 332  *
 333  */
 334 struct rte_crypto_mod_op_param {
 335         rte_crypto_param base;
 336         /**<
 337          * Pointer to base of modular exponentiation/multiplicative
 338          * inverse data in octet-string network byte order format
 339          *
 340          * In case Multiplicative Inverse is used this number shall
 341          * be relatively prime to modulus in corresponding Modular
 342          * Multiplicative Inverse rte_crypto_modinv_xform
 343          */
 344
 345         rte_crypto_param result;
 346         /**<
 347          * Pointer to the result of modular exponentiation/multiplicative inverse
 348          * data in octet-string network byte order format.
 349          *
 350          * This field shall be big enough to hold the result of Modular
 351          * Exponentiation or Modular Multiplicative Inverse
 352          * (bigger or equal to length of modulus)
 353          */
 354 };
 355
 356 /**
 357  * Asymmetric crypto transform data
 358  *
 359  * Structure describing asym xforms.
 360  */
 361 struct rte_crypto_asym_xform {
 362         struct rte_crypto_asym_xform *next;
 363         /**< Pointer to next xform to set up xform chain.*/
 364         enum rte_crypto_asym_xform_type xform_type;
 365         /**< Asymmetric crypto transform */
 366
 367         __extension__
 368         union {
 369                 struct rte_crypto_rsa_xform rsa;
 370                 /**< RSA xform parameters */
 371
 372                 struct rte_crypto_modex_xform modex;
 373                 /**< Modular Exponentiation xform parameters */
 374
 375                 struct rte_crypto_modinv_xform modinv;
 376                 /**< Modular Multiplicative Inverse xform parameters */
 377
 378                 struct rte_crypto_dh_xform dh;
 379                 /**< DH xform parameters */
 380
 381                 struct rte_crypto_dsa_xform dsa;
 382                 /**< DSA xform parameters */
 383         };
 384 };
 385
 386 struct rte_cryptodev_asym_session;
 387
 388 /**
 389  * RSA operation params
 390  *
 391  */
 392 struct rte_crypto_rsa_op_param {
 393         enum rte_crypto_asym_op_type op_type;
 394         /**< Type of RSA operation for transform */;
 395
 396         rte_crypto_param message;
 397         /**<
 398          * Pointer to input data
 399          * - to be encrypted for RSA public encrypt.
 400          * - to be signed for RSA sign generation.
 401          * - to be authenticated for RSA sign verification.
 402          *
 403          * Pointer to output data
 404          * - for RSA private decrypt.
 405          * In this case the underlying array should have been
 406          * allocated with enough memory to hold plaintext output
 407          * (i.e. must be at least RSA key size). The message.length
 408          * field should be 0 and will be overwritten by the PMD
 409          * with the decrypted length.
 410          *
 411          * All data is in Octet-string network byte order format.
 412          */
 413
 414         rte_crypto_param cipher;
 415         /**<
 416          * Pointer to input data
 417          * - to be decrypted for RSA private decrypt.
 418          *
 419          * Pointer to output data
 420          * - for RSA public encrypt.
 421          * In this case the underlying array should have been allocated
 422          * with enough memory to hold ciphertext output (i.e. must be
 423          * at least RSA key size). The cipher.length field should
 424          * be 0 and will be overwritten by the PMD with the encrypted length.
 425          *
 426          * All data is in Octet-string network byte order format.
 427          */
 428
 429         rte_crypto_param sign;
 430         /**<
 431          * Pointer to input data
 432          * - to be verified for RSA public decrypt.
 433          *
 434          * Pointer to output data
 435          * - for RSA private encrypt.
 436          * In this case the underlying array should have been allocated
 437          * with enough memory to hold signature output (i.e. must be
 438          * at least RSA key size). The sign.length field should
 439          * be 0 and will be overwritten by the PMD with the signature length.
 440          *
 441          * All data is in Octet-string network byte order format.
 442          */
 443
 444         enum rte_crypto_rsa_padding_type pad;
 445         /**< RSA padding scheme to be used for transform */
 446
 447         enum rte_crypto_auth_algorithm md;
 448         /**< Hash algorithm to be used for data hash if padding
 449          * scheme is either OAEP or PSS. Valid hash algorithms
 450          * are:
 451          * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
 452          */
 453
 454         enum rte_crypto_auth_algorithm mgf1md;
 455         /**<
 456          * Hash algorithm to be used for mask generation if
 457          * padding scheme is either OAEP or PSS. If padding
 458          * scheme is unspecified data hash algorithm is used
 459          * for mask generation. Valid hash algorithms are:
 460          * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
 461          */
 462 };
 463
 464 /**
 465  * Diffie-Hellman Operations params.
 466  * @note:
 467  */
 468 struct rte_crypto_dh_op_param {
 469         rte_crypto_param pub_key;
 470         /**<
 471          * Output generated public key when xform type is
 472          * DH PUB_KEY_GENERATION.
 473          * Input peer public key when xform type is DH
 474          * SHARED_SECRET_COMPUTATION
 475          * pub_key is in octet-string network byte order format.
 476          *
 477          */
 478
 479         rte_crypto_param priv_key;
 480         /**<
 481          * Output generated private key if xform type is
 482          * DH PRIVATE_KEY_GENERATION
 483          * Input when xform type is DH SHARED_SECRET_COMPUTATION.
 484          * priv_key is in octet-string network byte order format.
 485          *
 486          */
 487
 488         rte_crypto_param shared_secret;
 489         /**<
 490          * Output with calculated shared secret
 491          * when dh xform set up with op type = SHARED_SECRET_COMPUTATION.
 492          * shared_secret is an octet-string network byte order format.
 493          *
 494          */
 495 };
 496
 497 /**
 498  * DSA Operations params
 499  *
 500  */
 501 struct rte_crypto_dsa_op_param {
 502         enum rte_crypto_asym_op_type op_type;
 503         /**< Signature Generation or Verification */
 504         rte_crypto_param message;
 505         /**< input message to be signed or verified */
 506         rte_crypto_param r;
 507         /**< dsa sign component 'r' value
 508          *
 509          * output if op_type = sign generate,
 510          * input if op_type = sign verify
 511          */
 512         rte_crypto_param s;
 513         /**< dsa sign component 's' value
 514          *
 515          * output if op_type = sign generate,
 516          * input if op_type = sign verify
 517          */
 518         rte_crypto_param y;
 519         /**< y : Public key of the signer.
 520          * Public key data of the signer in Octet-string network byte order
 521          * format.
 522          * y = g^x mod p
 523          */
 524 };
 525
 526 /**
 527  * Asymmetric Cryptographic Operation.
 528  *
 529  * Structure describing asymmetric crypto operation params.
 530  *
 531  */
 532 struct rte_crypto_asym_op {
 533         struct rte_cryptodev_asym_session *session;
 534         /**< Handle for the initialised session context */
 535
 536         __extension__
 537         union {
 538                 struct rte_crypto_rsa_op_param rsa;
 539                 struct rte_crypto_mod_op_param modex;
 540                 struct rte_crypto_mod_op_param modinv;
 541                 struct rte_crypto_dh_op_param dh;
 542                 struct rte_crypto_dsa_op_param dsa;
 543         };
 544 };
 545
 546 #ifdef __cplusplus
 547 }
 548 #endif
 549
 550 #endif /* _RTE_CRYPTO_ASYM_H_ */