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