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"
31 * Buffer to hold crypto params required for asym operations.
33 * These buffers can be used for both input to PMD and output from PMD. When
34 * used for output from PMD, application has to ensure the buffer is large
35 * enough to hold the target data.
37 * If an operation requires the PMD to generate a random number,
38 * and the device supports CSRNG, 'data' should be set to NULL.
39 * The crypto parameter in question will not be used by the PMD,
40 * as it is internally generated.
42 typedef struct rte_crypto_param_t {
44 /**< pointer to buffer holding data */
46 /**< IO address of data buffer */
48 /**< length of data in bytes */
51 /** asym xform type name strings */
53 rte_crypto_asym_xform_strings[];
55 /** asym operations type name strings */
57 rte_crypto_asym_op_strings[];
60 * Asymmetric crypto transformation types.
61 * Each xform type maps to one asymmetric algorithm
62 * performing specific operation
65 enum rte_crypto_asym_xform_type {
66 RTE_CRYPTO_ASYM_XFORM_UNSPECIFIED = 0,
67 /**< Invalid xform. */
68 RTE_CRYPTO_ASYM_XFORM_NONE,
70 * May be supported by PMD to support
71 * passthrough op for debugging purpose.
72 * if xform_type none , op_type is disregarded.
74 RTE_CRYPTO_ASYM_XFORM_RSA,
75 /**< RSA. Performs Encrypt, Decrypt, Sign and Verify.
76 * Refer to rte_crypto_asym_op_type
78 RTE_CRYPTO_ASYM_XFORM_DH,
80 * Performs Key Generate and Shared Secret Compute.
81 * Refer to rte_crypto_asym_op_type
83 RTE_CRYPTO_ASYM_XFORM_DSA,
84 /**< Digital Signature Algorithm
85 * Performs Signature Generation and Verification.
86 * Refer to rte_crypto_asym_op_type
88 RTE_CRYPTO_ASYM_XFORM_MODINV,
89 /**< Modular Multiplicative Inverse
90 * Perform Modular Multiplicative Inverse b^(-1) mod n
92 RTE_CRYPTO_ASYM_XFORM_MODEX,
93 /**< Modular Exponentiation
94 * Perform Modular Exponentiation b^e mod n
96 RTE_CRYPTO_ASYM_XFORM_ECDSA,
97 /**< Elliptic Curve Digital Signature Algorithm
98 * Perform Signature Generation and Verification.
100 RTE_CRYPTO_ASYM_XFORM_ECPM,
101 /**< Elliptic Curve Point Multiplication */
102 RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END
107 * Asymmetric crypto operation type variants
109 enum rte_crypto_asym_op_type {
110 RTE_CRYPTO_ASYM_OP_ENCRYPT,
111 /**< Asymmetric Encrypt operation */
112 RTE_CRYPTO_ASYM_OP_DECRYPT,
113 /**< Asymmetric Decrypt operation */
114 RTE_CRYPTO_ASYM_OP_SIGN,
115 /**< Signature Generation operation */
116 RTE_CRYPTO_ASYM_OP_VERIFY,
117 /**< Signature Verification operation */
118 RTE_CRYPTO_ASYM_OP_PRIVATE_KEY_GENERATE,
119 /**< DH Private Key generation operation */
120 RTE_CRYPTO_ASYM_OP_PUBLIC_KEY_GENERATE,
121 /**< DH Public Key generation operation */
122 RTE_CRYPTO_ASYM_OP_SHARED_SECRET_COMPUTE,
123 /**< DH Shared Secret compute operation */
124 RTE_CRYPTO_ASYM_OP_LIST_END
128 * Padding types for RSA signature.
130 enum rte_crypto_rsa_padding_type {
131 RTE_CRYPTO_RSA_PADDING_NONE = 0,
132 /**< RSA no padding scheme */
133 RTE_CRYPTO_RSA_PADDING_PKCS1_5,
134 /**< RSA PKCS#1 PKCS1-v1_5 padding scheme. For signatures block type 01,
135 * for encryption block type 02 are used.
137 RTE_CRYPTO_RSA_PADDING_OAEP,
138 /**< RSA PKCS#1 OAEP padding scheme */
139 RTE_CRYPTO_RSA_PADDING_PSS,
140 /**< RSA PKCS#1 PSS padding scheme */
141 RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END
145 * RSA private key type enumeration
147 * enumerates private key format required to perform RSA crypto
151 enum rte_crypto_rsa_priv_key_type {
152 RTE_RSA_KEY_TYPE_EXP,
153 /**< RSA private key is an exponent */
155 /**< RSA private key is in quintuple format
156 * See rte_crypto_rsa_priv_key_qt
161 * Structure describing RSA private key in quintuple format.
162 * See PKCS V1.5 RSA Cryptography Standard.
164 struct rte_crypto_rsa_priv_key_qt {
166 /**< p - Private key component P
167 * Private key component of RSA parameter required for CRT method
168 * of private key operations in Octet-string network byte order
173 /**< q - Private key component Q
174 * Private key component of RSA parameter required for CRT method
175 * of private key operations in Octet-string network byte order
180 /**< dP - Private CRT component
181 * Private CRT component of RSA parameter required for CRT method
182 * RSA private key operations in Octet-string network byte order
184 * dP = d mod ( p - 1 )
188 /**< dQ - Private CRT component
189 * Private CRT component of RSA parameter required for CRT method
190 * RSA private key operations in Octet-string network byte order
192 * dQ = d mod ( q - 1 )
195 rte_crypto_param qInv;
196 /**< qInv - Private CRT component
197 * Private CRT component of RSA parameter required for CRT method
198 * RSA private key operations in Octet-string network byte order
205 * Asymmetric RSA transform data
207 * Structure describing RSA xform params
210 struct rte_crypto_rsa_xform {
213 * Modulus data of RSA operation in Octet-string network
218 /**< e - Public key exponent
219 * Public key exponent used for RSA public key operations in Octet-
220 * string network byte order format.
223 enum rte_crypto_rsa_priv_key_type key_type;
228 /**< d - Private key exponent
229 * Private key exponent used for RSA
230 * private key operations in
231 * Octet-string network byte order format.
234 struct rte_crypto_rsa_priv_key_qt qt;
235 /**< qt - Private key in quintuple format */
240 * Asymmetric Modular exponentiation transform data
242 * Structure describing modular exponentiation xform param
245 struct rte_crypto_modex_xform {
246 rte_crypto_param modulus;
248 * Pointer to the modulus data for modexp transform operation
249 * in octet-string network byte order format
251 * In case this number is equal to zero the driver shall set
252 * the crypto op status field to RTE_CRYPTO_OP_STATUS_ERROR
255 rte_crypto_param exponent;
257 * Exponent of the modexp transform operation in
258 * octet-string network byte order format
263 * Asymmetric modular multiplicative inverse transform operation
265 * Structure describing modular multiplicative inverse transform
268 struct rte_crypto_modinv_xform {
269 rte_crypto_param modulus;
271 * Pointer to the modulus data for modular multiplicative inverse
272 * operation in octet-string network byte order format
274 * In case this number is equal to zero the driver shall set
275 * the crypto op status field to RTE_CRYPTO_OP_STATUS_ERROR
277 * This number shall be relatively prime to base
278 * in corresponding Modular Multiplicative Inverse
279 * rte_crypto_mod_op_param
284 * Asymmetric DH transform data
286 * Structure describing deffie-hellman xform params
289 struct rte_crypto_dh_xform {
290 enum rte_crypto_asym_op_type type;
291 /**< Setup xform for key generate or shared secret compute */
294 /**< p : Prime modulus data
295 * DH prime modulus data in octet-string network byte order format.
301 * DH group generator data in octet-string network byte order
308 * Asymmetric Digital Signature transform operation
310 * Structure describing DSA xform params
313 struct rte_crypto_dsa_xform {
315 /**< p - Prime modulus
316 * Prime modulus data for DSA operation in Octet-string network byte
320 /**< q : Order of the subgroup.
321 * Order of the subgroup data in Octet-string network byte order
326 /**< g: Generator of the subgroup
327 * Generator data in Octet-string network byte order format.
330 /**< x: Private key of the signer in octet-string network
332 * Used when app has pre-defined private key.
333 * Valid only when xform chain is DSA ONLY.
334 * if xform chain is DH private key generate + DSA, then DSA sign
335 * compute will use internally generated key.
341 * https://tools.ietf.org/html/rfc8422
343 enum rte_crypto_ec_group {
344 RTE_CRYPTO_EC_GROUP_UNKNOWN = 0,
345 RTE_CRYPTO_EC_GROUP_SECP192R1 = 19,
346 RTE_CRYPTO_EC_GROUP_SECP224R1 = 21,
347 RTE_CRYPTO_EC_GROUP_SECP256R1 = 23,
348 RTE_CRYPTO_EC_GROUP_SECP384R1 = 24,
349 RTE_CRYPTO_EC_GROUP_SECP521R1 = 25,
353 * Structure for elliptic curve point
355 struct rte_crypto_ec_point {
363 * Asymmetric elliptic curve transform data
365 * Structure describing all EC based xform params
368 struct rte_crypto_ec_xform {
369 enum rte_crypto_ec_group curve_id;
370 /**< Pre-defined ec groups */
374 * Operations params for modular operations:
375 * exponentiation and multiplicative inverse
378 struct rte_crypto_mod_op_param {
379 rte_crypto_param base;
381 * Pointer to base of modular exponentiation/multiplicative
382 * inverse data in octet-string network byte order format
384 * In case Multiplicative Inverse is used this number shall
385 * be relatively prime to modulus in corresponding Modular
386 * Multiplicative Inverse rte_crypto_modinv_xform
389 rte_crypto_param result;
391 * Pointer to the result of modular exponentiation/multiplicative inverse
392 * data in octet-string network byte order format.
394 * This field shall be big enough to hold the result of Modular
395 * Exponentiation or Modular Multiplicative Inverse
396 * (bigger or equal to length of modulus)
401 * Asymmetric crypto transform data
403 * Structure describing asym xforms.
405 struct rte_crypto_asym_xform {
406 struct rte_crypto_asym_xform *next;
407 /**< Pointer to next xform to set up xform chain.*/
408 enum rte_crypto_asym_xform_type xform_type;
409 /**< Asymmetric crypto transform */
413 struct rte_crypto_rsa_xform rsa;
414 /**< RSA xform parameters */
416 struct rte_crypto_modex_xform modex;
417 /**< Modular Exponentiation xform parameters */
419 struct rte_crypto_modinv_xform modinv;
420 /**< Modular Multiplicative Inverse xform parameters */
422 struct rte_crypto_dh_xform dh;
423 /**< DH xform parameters */
425 struct rte_crypto_dsa_xform dsa;
426 /**< DSA xform parameters */
428 struct rte_crypto_ec_xform ec;
429 /**< EC xform parameters, used by elliptic curve based
435 struct rte_cryptodev_asym_session;
438 * RSA operation params
441 struct rte_crypto_rsa_op_param {
442 enum rte_crypto_asym_op_type op_type;
443 /**< Type of RSA operation for transform */
445 rte_crypto_param message;
447 * Pointer to input data
448 * - to be encrypted for RSA public encrypt.
449 * - to be signed for RSA sign generation.
450 * - to be authenticated for RSA sign verification.
452 * Pointer to output data
453 * - for RSA private decrypt.
454 * In this case the underlying array should have been
455 * allocated with enough memory to hold plaintext output
456 * (i.e. must be at least RSA key size). The message.length
457 * field should be 0 and will be overwritten by the PMD
458 * with the decrypted length.
460 * All data is in Octet-string network byte order format.
463 rte_crypto_param cipher;
465 * Pointer to input data
466 * - to be decrypted for RSA private decrypt.
468 * Pointer to output data
469 * - for RSA public encrypt.
470 * In this case the underlying array should have been allocated
471 * with enough memory to hold ciphertext output (i.e. must be
472 * at least RSA key size). The cipher.length field should
473 * be 0 and will be overwritten by the PMD with the encrypted length.
475 * All data is in Octet-string network byte order format.
478 rte_crypto_param sign;
480 * Pointer to input data
481 * - to be verified for RSA public decrypt.
483 * Pointer to output data
484 * - for RSA private encrypt.
485 * In this case the underlying array should have been allocated
486 * with enough memory to hold signature output (i.e. must be
487 * at least RSA key size). The sign.length field should
488 * be 0 and will be overwritten by the PMD with the signature length.
490 * All data is in Octet-string network byte order format.
493 enum rte_crypto_rsa_padding_type pad;
494 /**< RSA padding scheme to be used for transform */
496 enum rte_crypto_auth_algorithm md;
497 /**< Hash algorithm to be used for data hash if padding
498 * scheme is either OAEP or PSS. Valid hash algorithms
500 * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
503 enum rte_crypto_auth_algorithm mgf1md;
505 * Hash algorithm to be used for mask generation if
506 * padding scheme is either OAEP or PSS. If padding
507 * scheme is unspecified data hash algorithm is used
508 * for mask generation. Valid hash algorithms are:
509 * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
514 * Diffie-Hellman Operations params.
517 struct rte_crypto_dh_op_param {
518 rte_crypto_param pub_key;
520 * Output generated public key when xform type is
521 * DH PUB_KEY_GENERATION.
522 * Input peer public key when xform type is DH
523 * SHARED_SECRET_COMPUTATION
524 * pub_key is in octet-string network byte order format.
528 rte_crypto_param priv_key;
530 * Output generated private key if xform type is
531 * DH PRIVATE_KEY_GENERATION
532 * Input when xform type is DH SHARED_SECRET_COMPUTATION.
533 * priv_key is in octet-string network byte order format.
537 rte_crypto_param shared_secret;
539 * Output with calculated shared secret
540 * when dh xform set up with op type = SHARED_SECRET_COMPUTATION.
541 * shared_secret is an octet-string network byte order format.
547 * DSA Operations params
550 struct rte_crypto_dsa_op_param {
551 enum rte_crypto_asym_op_type op_type;
552 /**< Signature Generation or Verification */
553 rte_crypto_param message;
554 /**< input message to be signed or verified */
556 /**< Per-message secret number, which is an integer
557 * in the interval (1, q-1).
558 * If the random number is generated by the PMD,
559 * the 'rte_crypto_param.data' parameter should be set to NULL.
562 /**< dsa sign component 'r' value
564 * output if op_type = sign generate,
565 * input if op_type = sign verify
568 /**< dsa sign component 's' value
570 * output if op_type = sign generate,
571 * input if op_type = sign verify
574 /**< y : Public key of the signer.
575 * Public key data of the signer in Octet-string network byte order
582 * ECDSA operation params
584 struct rte_crypto_ecdsa_op_param {
585 enum rte_crypto_asym_op_type op_type;
586 /**< Signature generation or verification */
588 rte_crypto_param pkey;
589 /**< Private key of the signer for signature generation */
591 struct rte_crypto_ec_point q;
592 /**< Public key of the signer for verification */
594 rte_crypto_param message;
595 /**< Input message digest to be signed or verified */
598 /**< The ECDSA per-message secret number, which is an integer
599 * in the interval (1, n-1).
600 * If the random number is generated by the PMD,
601 * the 'rte_crypto_param.data' parameter should be set to NULL.
605 /**< r component of elliptic curve signature
606 * output : for signature generation
607 * input : for signature verification
610 /**< s component of elliptic curve signature
611 * output : for signature generation
612 * input : for signature verification
617 * Structure for EC point multiplication operation param
619 struct rte_crypto_ecpm_op_param {
620 struct rte_crypto_ec_point p;
621 /**< x and y coordinates of input point */
623 struct rte_crypto_ec_point r;
624 /**< x and y coordinates of resultant point */
626 rte_crypto_param scalar;
627 /**< Scalar to multiply the input point */
631 * Asymmetric Cryptographic Operation.
633 * Structure describing asymmetric crypto operation params.
636 struct rte_crypto_asym_op {
639 struct rte_cryptodev_asym_session *session;
640 /**< Handle for the initialised session context */
641 struct rte_crypto_asym_xform *xform;
642 /**< Session-less API crypto operation parameters */
647 struct rte_crypto_rsa_op_param rsa;
648 struct rte_crypto_mod_op_param modex;
649 struct rte_crypto_mod_op_param modinv;
650 struct rte_crypto_dh_op_param dh;
651 struct rte_crypto_dsa_op_param dsa;
652 struct rte_crypto_ecdsa_op_param ecdsa;
653 struct rte_crypto_ecpm_op_param ecpm;
661 #endif /* _RTE_CRYPTO_ASYM_H_ */