1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2018 Cavium Networks
5 #ifndef _RTE_CRYPTO_ASYM_H_
6 #define _RTE_CRYPTO_ASYM_H_
9 * @file rte_crypto_asym.h
11 * RTE Definitions for Asymmetric Cryptography
13 * Defines asymmetric algorithms and modes, as well as supported
14 * asymmetric crypto operations.
24 #include <rte_memory.h>
25 #include <rte_mempool.h>
26 #include <rte_common.h>
28 #include "rte_crypto_sym.h"
30 struct rte_cryptodev_asym_session;
32 /** asym xform type name strings */
34 rte_crypto_asym_xform_strings[];
36 /** asym key exchange operation type name strings */
38 rte_crypto_asym_ke_strings[];
40 /** asym operations type name strings */
42 rte_crypto_asym_op_strings[];
44 #define RTE_CRYPTO_ASYM_FLAG_PUB_KEY_NO_PADDING RTE_BIT32(0)
46 * Flag to denote public key will be returned without leading zero bytes
47 * and if the flag is not set, public key will be padded to the left with
48 * zeros to the size of the underlying algorithm (default)
50 #define RTE_CRYPTO_ASYM_FLAG_SHARED_KEY_NO_PADDING RTE_BIT32(1)
52 * Flag to denote shared secret will be returned without leading zero bytes
53 * and if the flag is not set, shared secret will be padded to the left with
54 * zeros to the size of the underlying algorithm (default)
58 * List of elliptic curves. This enum aligns with
59 * TLS "Supported Groups" registry (previously known as
60 * NamedCurve registry). FFDH groups are not, and will not
61 * be included in this list.
62 * Deprecation for selected curve in TLS does not deprecate
63 * the selected curve in Cryptodev.
64 * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml
66 enum rte_crypto_curve_id {
67 RTE_CRYPTO_EC_GROUP_SECP192R1 = 19,
68 RTE_CRYPTO_EC_GROUP_SECP224R1 = 21,
69 RTE_CRYPTO_EC_GROUP_SECP256R1 = 23,
70 RTE_CRYPTO_EC_GROUP_SECP384R1 = 24,
71 RTE_CRYPTO_EC_GROUP_SECP521R1 = 25
75 * Asymmetric crypto transformation types.
76 * Each xform type maps to one asymmetric algorithm
77 * performing specific operation
80 enum rte_crypto_asym_xform_type {
81 RTE_CRYPTO_ASYM_XFORM_UNSPECIFIED = 0,
82 /**< Invalid xform. */
83 RTE_CRYPTO_ASYM_XFORM_NONE,
85 * May be supported by PMD to support
86 * passthrough op for debugging purpose.
87 * if xform_type none , op_type is disregarded.
89 RTE_CRYPTO_ASYM_XFORM_RSA,
90 /**< RSA. Performs Encrypt, Decrypt, Sign and Verify.
91 * Refer to rte_crypto_asym_op_type
93 RTE_CRYPTO_ASYM_XFORM_DH,
95 * Performs Key Generate and Shared Secret Compute.
96 * Refer to rte_crypto_asym_op_type
98 RTE_CRYPTO_ASYM_XFORM_DSA,
99 /**< Digital Signature Algorithm
100 * Performs Signature Generation and Verification.
101 * Refer to rte_crypto_asym_op_type
103 RTE_CRYPTO_ASYM_XFORM_MODINV,
104 /**< Modular Multiplicative Inverse
105 * Perform Modular Multiplicative Inverse b^(-1) mod n
107 RTE_CRYPTO_ASYM_XFORM_MODEX,
108 /**< Modular Exponentiation
109 * Perform Modular Exponentiation b^e mod n
111 RTE_CRYPTO_ASYM_XFORM_ECDSA,
112 /**< Elliptic Curve Digital Signature Algorithm
113 * Perform Signature Generation and Verification.
115 RTE_CRYPTO_ASYM_XFORM_ECDH,
116 /**< Elliptic Curve Diffie Hellman */
117 RTE_CRYPTO_ASYM_XFORM_ECPM,
118 /**< Elliptic Curve Point Multiplication */
119 RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END
124 * Asymmetric crypto operation type variants
126 enum rte_crypto_asym_op_type {
127 RTE_CRYPTO_ASYM_OP_ENCRYPT,
128 /**< Asymmetric Encrypt operation */
129 RTE_CRYPTO_ASYM_OP_DECRYPT,
130 /**< Asymmetric Decrypt operation */
131 RTE_CRYPTO_ASYM_OP_SIGN,
132 /**< Signature Generation operation */
133 RTE_CRYPTO_ASYM_OP_VERIFY,
134 /**< Signature Verification operation */
135 RTE_CRYPTO_ASYM_OP_LIST_END
139 * Asymmetric crypto key exchange operation type
141 enum rte_crypto_asym_ke_type {
142 RTE_CRYPTO_ASYM_KE_PRIV_KEY_GENERATE,
143 /**< Private Key generation operation */
144 RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE,
145 /**< Public Key generation operation */
146 RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE,
147 /**< Shared Secret compute operation */
148 RTE_CRYPTO_ASYM_KE_PUB_KEY_VERIFY
149 /**< Public Key Verification - can be used for
150 * elliptic curve point validation.
155 * Padding types for RSA signature.
157 enum rte_crypto_rsa_padding_type {
158 RTE_CRYPTO_RSA_PADDING_NONE = 0,
159 /**< RSA no padding scheme */
160 RTE_CRYPTO_RSA_PADDING_PKCS1_5,
161 /**< RSA PKCS#1 PKCS1-v1_5 padding scheme. For signatures block type 01,
162 * for encryption block type 02 are used.
164 RTE_CRYPTO_RSA_PADDING_OAEP,
165 /**< RSA PKCS#1 OAEP padding scheme */
166 RTE_CRYPTO_RSA_PADDING_PSS,
167 /**< RSA PKCS#1 PSS padding scheme */
168 RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END
172 * RSA private key type enumeration
174 * enumerates private key format required to perform RSA crypto
178 enum rte_crypto_rsa_priv_key_type {
179 RTE_RSA_KEY_TYPE_EXP,
180 /**< RSA private key is an exponent */
182 /**< RSA private key is in quintuple format
183 * See rte_crypto_rsa_priv_key_qt
188 * Buffer to hold crypto params required for asym operations.
190 * These buffers can be used for both input to PMD and output from PMD. When
191 * used for output from PMD, application has to ensure the buffer is large
192 * enough to hold the target data.
194 * If an operation requires the PMD to generate a random number,
195 * and the device supports CSRNG, 'data' should be set to NULL.
196 * The crypto parameter in question will not be used by the PMD,
197 * as it is internally generated.
199 typedef struct rte_crypto_param_t {
201 /**< pointer to buffer holding data */
203 /**< IO address of data buffer */
205 /**< length of data in bytes */
208 /** Unsigned big-integer in big-endian format */
209 typedef rte_crypto_param rte_crypto_uint;
212 * Structure for elliptic curve point
214 struct rte_crypto_ec_point {
222 * Structure describing RSA private key in quintuple format.
223 * See PKCS V1.5 RSA Cryptography Standard.
225 struct rte_crypto_rsa_priv_key_qt {
227 /**< the first factor */
229 /**< the second factor */
231 /**< the first factor's CRT exponent */
233 /**< the second's factor's CRT exponent */
234 rte_crypto_uint qInv;
235 /**< the CRT coefficient */
241 struct rte_crypto_rsa_padding {
242 enum rte_crypto_rsa_padding_type type;
243 /**< RSA padding scheme to be used for transform */
244 enum rte_crypto_auth_algorithm hash;
246 * RSA padding hash algorithm
247 * Valid hash algorithms are:
248 * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
250 * When a specific padding type is selected, the following rules apply:
251 * - RTE_CRYPTO_RSA_PADDING_NONE:
252 * This field is ignored by the PMD
254 * - RTE_CRYPTO_RSA_PADDING_PKCS1_5:
255 * When signing an operation this field is used to determine value
256 * of the DigestInfo structure, therefore specifying which algorithm
257 * was used to create the message digest.
258 * When doing encryption/decryption this field is ignored for this
261 * - RTE_CRYPTO_RSA_PADDING_OAEP
262 * This field shall be set with the hash algorithm used
263 * in the padding scheme
265 * - RTE_CRYPTO_RSA_PADDING_PSS
266 * This field shall be set with the hash algorithm used
267 * in the padding scheme (and to create the input message digest)
269 enum rte_crypto_auth_algorithm mgf1hash;
271 * Hash algorithm to be used for mask generation if the
272 * padding scheme is either OAEP or PSS. If the padding
273 * scheme is unspecified a data hash algorithm is used
274 * for mask generation. Valid hash algorithms are:
275 * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
277 uint16_t pss_saltlen;
279 * RSA PSS padding salt length
281 * Used only when RTE_CRYPTO_RSA_PADDING_PSS padding is selected,
284 rte_crypto_param oaep_label;
286 * RSA OAEP padding optional label
288 * Used only when RTE_CRYPTO_RSA_PADDING_OAEP padding is selected,
289 * otherwise ignored. If label.data == NULL, a default
290 * label (empty string) is used.
295 * Asymmetric RSA transform data
297 * Structure describing RSA xform params
300 struct rte_crypto_rsa_xform {
302 /**< the RSA modulus */
304 /**< the RSA public exponent */
306 enum rte_crypto_rsa_priv_key_type key_type;
311 /**< the RSA private exponent */
312 struct rte_crypto_rsa_priv_key_qt qt;
313 /**< qt - Private key in quintuple format */
318 * Asymmetric Modular exponentiation transform data
320 * Structure describing modular exponentiation xform param
323 struct rte_crypto_modex_xform {
324 rte_crypto_uint modulus;
325 /**< Modulus data for modexp transform operation */
326 rte_crypto_uint exponent;
327 /**< Exponent of the modexp transform operation */
331 * Asymmetric modular multiplicative inverse transform operation
333 * Structure describing modular multiplicative inverse transform
336 struct rte_crypto_modinv_xform {
337 rte_crypto_uint modulus;
338 /**< Modulus data for modular multiplicative inverse operation */
342 * Asymmetric DH transform data
344 * Structure describing deffie-hellman xform params
347 struct rte_crypto_dh_xform {
349 /**< Prime modulus data */
355 * Asymmetric Digital Signature transform operation
357 * Structure describing DSA xform params
360 struct rte_crypto_dsa_xform {
362 /**< Prime modulus */
364 /**< Order of the subgroup */
366 /**< Generator of the subgroup */
368 /**< x: Private key of the signer */
372 * Asymmetric elliptic curve transform data
374 * Structure describing all EC based xform params
377 struct rte_crypto_ec_xform {
378 enum rte_crypto_curve_id curve_id;
379 /**< Pre-defined ec groups */
383 * Operations params for modular operations:
384 * exponentiation and multiplicative inverse
387 struct rte_crypto_mod_op_param {
388 rte_crypto_uint base;
389 /** Base of modular exponentiation/multiplicative inverse */
390 rte_crypto_uint result;
391 /** Result of modular exponentiation/multiplicative inverse */
395 * RSA operation params
398 struct rte_crypto_rsa_op_param {
399 enum rte_crypto_asym_op_type op_type;
400 /**< Type of RSA operation for transform */
402 rte_crypto_param message;
404 * Pointer to input data
405 * - to be encrypted for RSA public encrypt.
406 * - to be signed for RSA sign generation.
407 * - to be authenticated for RSA sign verification.
409 * Pointer to output data
410 * - for RSA private decrypt.
411 * In this case the underlying array should have been
412 * allocated with enough memory to hold plaintext output
413 * (i.e. must be at least RSA key size). The message.length
414 * field should be 0 and will be overwritten by the PMD
415 * with the decrypted length.
418 rte_crypto_param cipher;
420 * Pointer to input data
421 * - to be decrypted for RSA private decrypt.
423 * Pointer to output data
424 * - for RSA public encrypt.
425 * In this case the underlying array should have been allocated
426 * with enough memory to hold ciphertext output (i.e. must be
427 * at least RSA key size). The cipher.length field should
428 * be 0 and will be overwritten by the PMD with the encrypted length.
430 * When RTE_CRYPTO_RSA_PADDING_NONE and RTE_CRYPTO_ASYM_OP_VERIFY
431 * selected, this is an output of decrypted signature.
434 rte_crypto_param sign;
436 * Pointer to input data
437 * - to be verified for RSA public decrypt.
439 * Pointer to output data
440 * - for RSA private encrypt.
441 * In this case the underlying array should have been allocated
442 * with enough memory to hold signature output (i.e. must be
443 * at least RSA key size). The sign.length field should
444 * be 0 and will be overwritten by the PMD with the signature length.
447 struct rte_crypto_rsa_padding padding;
448 /**< RSA padding information */
452 * Diffie-Hellman Operations params.
455 struct rte_crypto_dh_op_param {
456 enum rte_crypto_asym_ke_type ke_type;
457 /**< Key exchange operation type */
458 rte_crypto_uint priv_key;
460 * Output - generated private key when ke_type is
461 * RTE_CRYPTO_ASYM_KE_PRIV_KEY_GENERATE.
463 * Input - private key when ke_type is one of:
464 * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE,
465 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
467 * In case priv_key.length is 0 and ke_type is set with
468 * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE, CSRNG capable
469 * device will generate a private key and use it for public
472 rte_crypto_uint pub_key;
474 * Output - generated public key when ke_type is
475 * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE.
477 * Input - peer's public key when ke_type is
478 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
480 rte_crypto_uint shared_secret;
482 * Output - calculated shared secret when ke_type is
483 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
488 * Elliptic Curve Diffie-Hellman Operations params.
490 struct rte_crypto_ecdh_op_param {
491 enum rte_crypto_asym_ke_type ke_type;
492 /**< Key exchange operation type */
493 rte_crypto_uint priv_key;
495 * Output - generated private key when ke_type is
496 * RTE_CRYPTO_ASYM_KE_PRIVATE_KEY_GENERATE.
498 * Input - private key when ke_type is one of:
499 * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE,
500 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
502 * In case priv_key.length is 0 and ke_type is set with
503 * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE, CSRNG capable
504 * device will generate private key and use it for public
507 struct rte_crypto_ec_point pub_key;
509 * Output - generated public key when ke_type is
510 * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE.
512 * Input - peer's public key, when ke_type is one of:
513 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE,
514 * RTE_CRYPTO_ASYM_KE_EC_PUBLIC_KEY_VERIFY.
516 struct rte_crypto_ec_point shared_secret;
518 * Output - calculated shared secret when ke_type is
519 * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
524 * DSA Operations params
527 struct rte_crypto_dsa_op_param {
528 enum rte_crypto_asym_op_type op_type;
529 /**< Signature Generation or Verification */
530 rte_crypto_param message;
531 /**< input message to be signed or verified */
533 /**< Per-message secret number, which is an integer
534 * in the interval (1, q-1).
535 * If the random number is generated by the PMD,
536 * the 'rte_crypto_param.data' parameter should be set to NULL.
539 /**< dsa sign component 'r' value
541 * output if op_type = sign generate,
542 * input if op_type = sign verify
545 /**< dsa sign component 's' value
547 * output if op_type = sign generate,
548 * input if op_type = sign verify
551 /**< y : Public key of the signer.
557 * ECDSA operation params
559 struct rte_crypto_ecdsa_op_param {
560 enum rte_crypto_asym_op_type op_type;
561 /**< Signature generation or verification */
563 rte_crypto_uint pkey;
564 /**< Private key of the signer for signature generation */
566 struct rte_crypto_ec_point q;
567 /**< Public key of the signer for verification */
569 rte_crypto_param message;
570 /**< Input message digest to be signed or verified */
573 /**< The ECDSA per-message secret number, which is an integer
574 * in the interval (1, n-1).
575 * If the random number is generated by the PMD,
576 * the 'rte_crypto_param.data' parameter should be set to NULL.
580 /**< r component of elliptic curve signature
581 * output : for signature generation
582 * input : for signature verification
585 /**< s component of elliptic curve signature
586 * output : for signature generation
587 * input : for signature verification
592 * Structure for EC point multiplication operation param
594 struct rte_crypto_ecpm_op_param {
595 struct rte_crypto_ec_point p;
596 /**< x and y coordinates of input point */
598 struct rte_crypto_ec_point r;
599 /**< x and y coordinates of resultant point */
601 rte_crypto_param scalar;
602 /**< Scalar to multiply the input point */
606 * Asymmetric crypto transform data
608 * Structure describing asym xforms.
610 struct rte_crypto_asym_xform {
611 struct rte_crypto_asym_xform *next;
612 /**< Pointer to next xform to set up xform chain.*/
613 enum rte_crypto_asym_xform_type xform_type;
614 /**< Asymmetric crypto transform */
618 struct rte_crypto_rsa_xform rsa;
619 /**< RSA xform parameters */
621 struct rte_crypto_modex_xform modex;
622 /**< Modular Exponentiation xform parameters */
624 struct rte_crypto_modinv_xform modinv;
625 /**< Modular Multiplicative Inverse xform parameters */
627 struct rte_crypto_dh_xform dh;
628 /**< DH xform parameters */
630 struct rte_crypto_dsa_xform dsa;
631 /**< DSA xform parameters */
633 struct rte_crypto_ec_xform ec;
634 /**< EC xform parameters, used by elliptic curve based
641 * Asymmetric Cryptographic Operation.
643 * Structure describing asymmetric crypto operation params.
646 struct rte_crypto_asym_op {
649 struct rte_cryptodev_asym_session *session;
650 /**< Handle for the initialised session context */
651 struct rte_crypto_asym_xform *xform;
652 /**< Session-less API crypto operation parameters */
657 struct rte_crypto_rsa_op_param rsa;
658 struct rte_crypto_mod_op_param modex;
659 struct rte_crypto_mod_op_param modinv;
660 struct rte_crypto_dh_op_param dh;
661 struct rte_crypto_ecdh_op_param ecdh;
662 struct rte_crypto_dsa_op_param dsa;
663 struct rte_crypto_ecdsa_op_param ecdsa;
664 struct rte_crypto_ecpm_op_param ecpm;
668 * Asymmetric crypto operation flags.
669 * Please refer to the RTE_CRYPTO_ASYM_FLAG_*.
677 #endif /* _RTE_CRYPTO_ASYM_H_ */