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 - Prime modulus
 203          * Prime 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 data
 399          * - to be encrypted for RSA public encrypt.
 400          * - to be decrypted for RSA private decrypt.
 401          * - to be signed for RSA sign generation.
 402          * - to be authenticated for RSA sign verification.
 403          */
 404
 405         rte_crypto_param sign;
 406         /**<
 407          * Pointer to RSA signature data. If operation is RSA
 408          * sign @ref RTE_CRYPTO_ASYM_OP_SIGN, buffer will be
 409          * over-written with generated signature.
 410          *
 411          * Length of the signature data will be equal to the
 412          * RSA prime modulus length.
 413          */
 414
 415         enum rte_crypto_rsa_padding_type pad;
 416         /**< RSA padding scheme to be used for transform */
 417
 418         enum rte_crypto_auth_algorithm md;
 419         /**< Hash algorithm to be used for data hash if padding
 420          * scheme is either OAEP or PSS. Valid hash algorithms
 421          * are:
 422          * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
 423          */
 424
 425         enum rte_crypto_auth_algorithm mgf1md;
 426         /**<
 427          * Hash algorithm to be used for mask generation if
 428          * padding scheme is either OAEP or PSS. If padding
 429          * scheme is unspecified data hash algorithm is used
 430          * for mask generation. Valid hash algorithms are:
 431          * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
 432          */
 433 };
 434
 435 /**
 436  * Diffie-Hellman Operations params.
 437  * @note:
 438  */
 439 struct rte_crypto_dh_op_param {
 440         rte_crypto_param pub_key;
 441         /**<
 442          * Output generated public key when xform type is
 443          * DH PUB_KEY_GENERATION.
 444          * Input peer public key when xform type is DH
 445          * SHARED_SECRET_COMPUTATION
 446          * pub_key is in octet-string network byte order format.
 447          *
 448          */
 449
 450         rte_crypto_param priv_key;
 451         /**<
 452          * Output generated private key if xform type is
 453          * DH PRIVATE_KEY_GENERATION
 454          * Input when xform type is DH SHARED_SECRET_COMPUTATION.
 455          * priv_key is in octet-string network byte order format.
 456          *
 457          */
 458
 459         rte_crypto_param shared_secret;
 460         /**<
 461          * Output with calculated shared secret
 462          * when dh xform set up with op type = SHARED_SECRET_COMPUTATION.
 463          * shared_secret is an octet-string network byte order format.
 464          *
 465          */
 466 };
 467
 468 /**
 469  * DSA Operations params
 470  *
 471  */
 472 struct rte_crypto_dsa_op_param {
 473         enum rte_crypto_asym_op_type op_type;
 474         /**< Signature Generation or Verification */
 475         rte_crypto_param message;
 476         /**< input message to be signed or verified */
 477         rte_crypto_param r;
 478         /**< dsa sign component 'r' value
 479          *
 480          * output if op_type = sign generate,
 481          * input if op_type = sign verify
 482          */
 483         rte_crypto_param s;
 484         /**< dsa sign component 's' value
 485          *
 486          * output if op_type = sign generate,
 487          * input if op_type = sign verify
 488          */
 489         rte_crypto_param y;
 490         /**< y : Public key of the signer.
 491          * Public key data of the signer in Octet-string network byte order
 492          * format.
 493          * y = g^x mod p
 494          */
 495 };
 496
 497 /**
 498  * Asymmetric Cryptographic Operation.
 499  *
 500  * Structure describing asymmetric crypto operation params.
 501  *
 502  */
 503 struct rte_crypto_asym_op {
 504         struct rte_cryptodev_asym_session *session;
 505         /**< Handle for the initialised session context */
 506
 507         __extension__
 508         union {
 509                 struct rte_crypto_rsa_op_param rsa;
 510                 struct rte_crypto_mod_op_param modex;
 511                 struct rte_crypto_mod_op_param modinv;
 512                 struct rte_crypto_dh_op_param dh;
 513                 struct rte_crypto_dsa_op_param dsa;
 514         };
 515 };
 516
 517 #ifdef __cplusplus
 518 }
 519 #endif
 520
 521 #endif /* _RTE_CRYPTO_ASYM_H_ */