/* SPDX-License-Identifier: BSD-3-Clause * Copyright(c) 2018 Cavium Networks */ #ifndef _RTE_CRYPTO_ASYM_H_ #define _RTE_CRYPTO_ASYM_H_ /** * @file rte_crypto_asym.h * * RTE Definitions for Asymmetric Cryptography * * Defines asymmetric algorithms and modes, as well as supported * asymmetric crypto operations. */ #ifdef __cplusplus extern "C" { #endif #include #include #include #include #include #include "rte_crypto_sym.h" struct rte_cryptodev_asym_session; /** asym xform type name strings */ extern const char * rte_crypto_asym_xform_strings[]; /** asym key exchange operation type name strings */ extern const char * rte_crypto_asym_ke_strings[]; /** asym operations type name strings */ extern const char * rte_crypto_asym_op_strings[]; #define RTE_CRYPTO_ASYM_FLAG_PUB_KEY_NO_PADDING RTE_BIT32(0) /**< * Flag to denote public key will be returned without leading zero bytes * and if the flag is not set, public key will be padded to the left with * zeros to the size of the underlying algorithm (default) */ #define RTE_CRYPTO_ASYM_FLAG_SHARED_KEY_NO_PADDING RTE_BIT32(1) /**< * Flag to denote shared secret will be returned without leading zero bytes * and if the flag is not set, shared secret will be padded to the left with * zeros to the size of the underlying algorithm (default) */ /** * List of elliptic curves. This enum aligns with * TLS "Supported Groups" registry (previously known as * NamedCurve registry). FFDH groups are not, and will not * be included in this list. * Deprecation for selected curve in TLS does not deprecate * the selected curve in Cryptodev. * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml */ enum rte_crypto_curve_id { RTE_CRYPTO_EC_GROUP_SECP192R1 = 19, RTE_CRYPTO_EC_GROUP_SECP224R1 = 21, RTE_CRYPTO_EC_GROUP_SECP256R1 = 23, RTE_CRYPTO_EC_GROUP_SECP384R1 = 24, RTE_CRYPTO_EC_GROUP_SECP521R1 = 25 }; /** * Asymmetric crypto transformation types. * Each xform type maps to one asymmetric algorithm * performing specific operation * */ enum rte_crypto_asym_xform_type { RTE_CRYPTO_ASYM_XFORM_UNSPECIFIED = 0, /**< Invalid xform. */ RTE_CRYPTO_ASYM_XFORM_NONE, /**< Xform type None. * May be supported by PMD to support * passthrough op for debugging purpose. * if xform_type none , op_type is disregarded. */ RTE_CRYPTO_ASYM_XFORM_RSA, /**< RSA. Performs Encrypt, Decrypt, Sign and Verify. * Refer to rte_crypto_asym_op_type */ RTE_CRYPTO_ASYM_XFORM_DH, /**< Diffie-Hellman. * Performs Key Generate and Shared Secret Compute. * Refer to rte_crypto_asym_op_type */ RTE_CRYPTO_ASYM_XFORM_DSA, /**< Digital Signature Algorithm * Performs Signature Generation and Verification. * Refer to rte_crypto_asym_op_type */ RTE_CRYPTO_ASYM_XFORM_MODINV, /**< Modular Multiplicative Inverse * Perform Modular Multiplicative Inverse b^(-1) mod n */ RTE_CRYPTO_ASYM_XFORM_MODEX, /**< Modular Exponentiation * Perform Modular Exponentiation b^e mod n */ RTE_CRYPTO_ASYM_XFORM_ECDSA, /**< Elliptic Curve Digital Signature Algorithm * Perform Signature Generation and Verification. */ RTE_CRYPTO_ASYM_XFORM_ECDH, /**< Elliptic Curve Diffie Hellman */ RTE_CRYPTO_ASYM_XFORM_ECPM, /**< Elliptic Curve Point Multiplication */ RTE_CRYPTO_ASYM_XFORM_ECFPM, /**< Elliptic Curve Fixed Point Multiplication */ RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END /**< End of list */ }; /** * Asymmetric crypto operation type variants */ enum rte_crypto_asym_op_type { RTE_CRYPTO_ASYM_OP_ENCRYPT, /**< Asymmetric Encrypt operation */ RTE_CRYPTO_ASYM_OP_DECRYPT, /**< Asymmetric Decrypt operation */ RTE_CRYPTO_ASYM_OP_SIGN, /**< Signature Generation operation */ RTE_CRYPTO_ASYM_OP_VERIFY, /**< Signature Verification operation */ RTE_CRYPTO_ASYM_OP_LIST_END }; /** * Asymmetric crypto key exchange operation type */ enum rte_crypto_asym_ke_type { RTE_CRYPTO_ASYM_KE_PRIV_KEY_GENERATE, /**< Private Key generation operation */ RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE, /**< Public Key generation operation */ RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE, /**< Shared Secret compute operation */ RTE_CRYPTO_ASYM_KE_PUB_KEY_VERIFY /**< Public Key Verification - can be used for * elliptic curve point validation. */ }; /** * Padding types for RSA signature. */ enum rte_crypto_rsa_padding_type { RTE_CRYPTO_RSA_PADDING_NONE = 0, /**< RSA no padding scheme */ RTE_CRYPTO_RSA_PADDING_PKCS1_5, /**< RSA PKCS#1 PKCS1-v1_5 padding scheme. For signatures block type 01, * for encryption block type 02 are used. */ RTE_CRYPTO_RSA_PADDING_OAEP, /**< RSA PKCS#1 OAEP padding scheme */ RTE_CRYPTO_RSA_PADDING_PSS, /**< RSA PKCS#1 PSS padding scheme */ RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END }; /** * RSA private key type enumeration * * enumerates private key format required to perform RSA crypto * transform. * */ enum rte_crypto_rsa_priv_key_type { RTE_RSA_KEY_TYPE_EXP, /**< RSA private key is an exponent */ RTE_RSA_KEY_TYPE_QT, /**< RSA private key is in quintuple format * See rte_crypto_rsa_priv_key_qt */ }; /** * Buffer to hold crypto params required for asym operations. * * These buffers can be used for both input to PMD and output from PMD. When * used for output from PMD, application has to ensure the buffer is large * enough to hold the target data. * * If an operation requires the PMD to generate a random number, * and the device supports CSRNG, 'data' should be set to NULL. * The crypto parameter in question will not be used by the PMD, * as it is internally generated. */ typedef struct rte_crypto_param_t { uint8_t *data; /**< pointer to buffer holding data */ rte_iova_t iova; /**< IO address of data buffer */ size_t length; /**< length of data in bytes */ } rte_crypto_param; /** Unsigned big-integer in big-endian format */ typedef rte_crypto_param rte_crypto_uint; /** * Structure for elliptic curve point */ struct rte_crypto_ec_point { rte_crypto_param x; /**< X coordinate */ rte_crypto_param y; /**< Y coordinate */ }; /** * Structure describing RSA private key in quintuple format. * See PKCS V1.5 RSA Cryptography Standard. */ struct rte_crypto_rsa_priv_key_qt { rte_crypto_uint p; /**< the first factor */ rte_crypto_uint q; /**< the second factor */ rte_crypto_uint dP; /**< the first factor's CRT exponent */ rte_crypto_uint dQ; /**< the second's factor's CRT exponent */ rte_crypto_uint qInv; /**< the CRT coefficient */ }; /** * RSA padding type */ struct rte_crypto_rsa_padding { enum rte_crypto_rsa_padding_type type; /**< RSA padding scheme to be used for transform */ enum rte_crypto_auth_algorithm hash; /**< * RSA padding hash algorithm * Valid hash algorithms are: * MD5, SHA1, SHA224, SHA256, SHA384, SHA512 * * When a specific padding type is selected, the following rules apply: * - RTE_CRYPTO_RSA_PADDING_NONE: * This field is ignored by the PMD * * - RTE_CRYPTO_RSA_PADDING_PKCS1_5: * When signing an operation this field is used to determine value * of the DigestInfo structure, therefore specifying which algorithm * was used to create the message digest. * When doing encryption/decryption this field is ignored for this * padding type. * * - RTE_CRYPTO_RSA_PADDING_OAEP * This field shall be set with the hash algorithm used * in the padding scheme * * - RTE_CRYPTO_RSA_PADDING_PSS * This field shall be set with the hash algorithm used * in the padding scheme (and to create the input message digest) */ enum rte_crypto_auth_algorithm mgf1hash; /**< * Hash algorithm to be used for mask generation if the * padding scheme is either OAEP or PSS. If the padding * scheme is unspecified a data hash algorithm is used * for mask generation. Valid hash algorithms are: * MD5, SHA1, SHA224, SHA256, SHA384, SHA512 */ uint16_t pss_saltlen; /**< * RSA PSS padding salt length * * Used only when RTE_CRYPTO_RSA_PADDING_PSS padding is selected, * otherwise ignored. */ rte_crypto_param oaep_label; /**< * RSA OAEP padding optional label * * Used only when RTE_CRYPTO_RSA_PADDING_OAEP padding is selected, * otherwise ignored. If label.data == NULL, a default * label (empty string) is used. */ }; /** * Asymmetric RSA transform data * * Structure describing RSA xform params * */ struct rte_crypto_rsa_xform { rte_crypto_uint n; /**< the RSA modulus */ rte_crypto_uint e; /**< the RSA public exponent */ enum rte_crypto_rsa_priv_key_type key_type; RTE_STD_C11 union { rte_crypto_uint d; /**< the RSA private exponent */ struct rte_crypto_rsa_priv_key_qt qt; /**< qt - Private key in quintuple format */ }; }; /** * Asymmetric Modular exponentiation transform data * * Structure describing modular exponentiation xform param * */ struct rte_crypto_modex_xform { rte_crypto_uint modulus; /**< Modulus data for modexp transform operation */ rte_crypto_uint exponent; /**< Exponent of the modexp transform operation */ }; /** * Asymmetric modular multiplicative inverse transform operation * * Structure describing modular multiplicative inverse transform * */ struct rte_crypto_modinv_xform { rte_crypto_uint modulus; /**< Modulus data for modular multiplicative inverse operation */ }; /** * Asymmetric DH transform data * * Structure describing deffie-hellman xform params * */ struct rte_crypto_dh_xform { rte_crypto_uint p; /**< Prime modulus data */ rte_crypto_uint g; /**< DH Generator */ }; /** * Asymmetric Digital Signature transform operation * * Structure describing DSA xform params * */ struct rte_crypto_dsa_xform { rte_crypto_uint p; /**< Prime modulus */ rte_crypto_uint q; /**< Order of the subgroup */ rte_crypto_uint g; /**< Generator of the subgroup */ rte_crypto_uint x; /**< x: Private key of the signer */ }; /** * Asymmetric elliptic curve transform data * * Structure describing all EC based xform params * */ struct rte_crypto_ec_xform { enum rte_crypto_curve_id curve_id; /**< Pre-defined ec groups */ }; /** * Operations params for modular operations: * exponentiation and multiplicative inverse * */ struct rte_crypto_mod_op_param { rte_crypto_uint base; /**< Base of modular exponentiation/multiplicative inverse. */ rte_crypto_uint result; /**< Result of modular exponentiation/multiplicative inverse. */ }; /** * RSA operation params * */ struct rte_crypto_rsa_op_param { enum rte_crypto_asym_op_type op_type; /**< Type of RSA operation for transform */ rte_crypto_param message; /**< * Pointer to input data * - to be encrypted for RSA public encrypt. * - to be signed for RSA sign generation. * - to be authenticated for RSA sign verification. * * Pointer to output data * - for RSA private decrypt. * In this case the underlying array should have been * allocated with enough memory to hold plaintext output * (i.e. must be at least RSA key size). The message.length * field should be 0 and will be overwritten by the PMD * with the decrypted length. */ rte_crypto_param cipher; /**< * Pointer to input data * - to be decrypted for RSA private decrypt. * * Pointer to output data * - for RSA public encrypt. * In this case the underlying array should have been allocated * with enough memory to hold ciphertext output (i.e. must be * at least RSA key size). The cipher.length field should * be 0 and will be overwritten by the PMD with the encrypted length. * * When RTE_CRYPTO_RSA_PADDING_NONE and RTE_CRYPTO_ASYM_OP_VERIFY * selected, this is an output of decrypted signature. */ rte_crypto_param sign; /**< * Pointer to input data * - to be verified for RSA public decrypt. * * Pointer to output data * - for RSA private encrypt. * In this case the underlying array should have been allocated * with enough memory to hold signature output (i.e. must be * at least RSA key size). The sign.length field should * be 0 and will be overwritten by the PMD with the signature length. */ struct rte_crypto_rsa_padding padding; /**< RSA padding information */ }; /** * Diffie-Hellman Operations params. * @note: */ struct rte_crypto_dh_op_param { enum rte_crypto_asym_ke_type ke_type; /**< Key exchange operation type */ rte_crypto_uint priv_key; /**< * Output - generated private key when ke_type is * RTE_CRYPTO_ASYM_KE_PRIV_KEY_GENERATE. * * Input - private key when ke_type is one of: * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE, * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. * * In case priv_key.length is 0 and ke_type is set with * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE, CSRNG capable * device will generate a private key and use it for public * key generation. */ rte_crypto_uint pub_key; /**< * Output - generated public key when ke_type is * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE. * * Input - peer's public key when ke_type is * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. */ rte_crypto_uint shared_secret; /**< * Output - calculated shared secret when ke_type is * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. */ }; /** * Elliptic Curve Diffie-Hellman Operations params. */ struct rte_crypto_ecdh_op_param { enum rte_crypto_asym_ke_type ke_type; /**< Key exchange operation type */ rte_crypto_uint priv_key; /**< * Output - generated private key when ke_type is * RTE_CRYPTO_ASYM_KE_PRIVATE_KEY_GENERATE. * * Input - private key when ke_type is one of: * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE, * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. * * In case priv_key.length is 0 and ke_type is set with * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE, CSRNG capable * device will generate private key and use it for public * key generation. */ struct rte_crypto_ec_point pub_key; /**< * Output - generated public key when ke_type is * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE. * * Input - peer's public key, when ke_type is one of: * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE, * RTE_CRYPTO_ASYM_KE_EC_PUBLIC_KEY_VERIFY. */ struct rte_crypto_ec_point shared_secret; /**< * Output - calculated shared secret when ke_type is * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE. */ }; /** * DSA Operations params * */ struct rte_crypto_dsa_op_param { enum rte_crypto_asym_op_type op_type; /**< Signature Generation or Verification */ rte_crypto_param message; /**< input message to be signed or verified */ rte_crypto_uint k; /**< Per-message secret number, which is an integer * in the interval (1, q-1). * If the random number is generated by the PMD, * the 'rte_crypto_param.data' parameter should be set to NULL. */ rte_crypto_uint r; /**< dsa sign component 'r' value * * output if op_type = sign generate, * input if op_type = sign verify */ rte_crypto_uint s; /**< dsa sign component 's' value * * output if op_type = sign generate, * input if op_type = sign verify */ rte_crypto_uint y; /**< y : Public key of the signer. * y = g^x mod p */ }; /** * ECDSA operation params */ struct rte_crypto_ecdsa_op_param { enum rte_crypto_asym_op_type op_type; /**< Signature generation or verification */ rte_crypto_uint pkey; /**< Private key of the signer for signature generation */ struct rte_crypto_ec_point q; /**< Public key of the signer for verification */ rte_crypto_param message; /**< Input message digest to be signed or verified */ rte_crypto_uint k; /**< The ECDSA per-message secret number, which is an integer * in the interval (1, n-1). * If the random number is generated by the PMD, * the 'rte_crypto_param.data' parameter should be set to NULL. */ rte_crypto_uint r; /**< r component of elliptic curve signature * output : for signature generation * input : for signature verification */ rte_crypto_uint s; /**< s component of elliptic curve signature * output : for signature generation * input : for signature verification */ }; /** * Structure for EC point multiplication operation param */ struct rte_crypto_ecpm_op_param { struct rte_crypto_ec_point p; /**< x and y coordinates of input point */ struct rte_crypto_ec_point r; /**< x and y coordinates of resultant point */ rte_crypto_param scalar; /**< Scalar to multiply the input point */ }; /** * Asymmetric crypto transform data * * Structure describing asym xforms. */ struct rte_crypto_asym_xform { struct rte_crypto_asym_xform *next; /**< Pointer to next xform to set up xform chain.*/ enum rte_crypto_asym_xform_type xform_type; /**< Asymmetric crypto transform */ RTE_STD_C11 union { struct rte_crypto_rsa_xform rsa; /**< RSA xform parameters */ struct rte_crypto_modex_xform modex; /**< Modular Exponentiation xform parameters */ struct rte_crypto_modinv_xform modinv; /**< Modular Multiplicative Inverse xform parameters */ struct rte_crypto_dh_xform dh; /**< DH xform parameters */ struct rte_crypto_dsa_xform dsa; /**< DSA xform parameters */ struct rte_crypto_ec_xform ec; /**< EC xform parameters, used by elliptic curve based * operations. */ }; }; /** * Asymmetric Cryptographic Operation. * * Structure describing asymmetric crypto operation params. * */ struct rte_crypto_asym_op { RTE_STD_C11 union { struct rte_cryptodev_asym_session *session; /**< Handle for the initialised session context */ struct rte_crypto_asym_xform *xform; /**< Session-less API crypto operation parameters */ }; RTE_STD_C11 union { struct rte_crypto_rsa_op_param rsa; struct rte_crypto_mod_op_param modex; struct rte_crypto_mod_op_param modinv; struct rte_crypto_dh_op_param dh; struct rte_crypto_ecdh_op_param ecdh; struct rte_crypto_dsa_op_param dsa; struct rte_crypto_ecdsa_op_param ecdsa; struct rte_crypto_ecpm_op_param ecpm; }; uint16_t flags; /**< * Asymmetric crypto operation flags. * Please refer to the RTE_CRYPTO_ASYM_FLAG_*. */ }; #ifdef __cplusplus } #endif #endif /* _RTE_CRYPTO_ASYM_H_ */