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 operations type name strings */
38 rte_crypto_asym_op_strings[];
42 * https://tools.ietf.org/html/rfc8422
44 enum rte_crypto_ec_group {
45 RTE_CRYPTO_EC_GROUP_UNKNOWN = 0,
46 RTE_CRYPTO_EC_GROUP_SECP192R1 = 19,
47 RTE_CRYPTO_EC_GROUP_SECP224R1 = 21,
48 RTE_CRYPTO_EC_GROUP_SECP256R1 = 23,
49 RTE_CRYPTO_EC_GROUP_SECP384R1 = 24,
50 RTE_CRYPTO_EC_GROUP_SECP521R1 = 25,
54 * Asymmetric crypto transformation types.
55 * Each xform type maps to one asymmetric algorithm
56 * performing specific operation
59 enum rte_crypto_asym_xform_type {
60 RTE_CRYPTO_ASYM_XFORM_UNSPECIFIED = 0,
61 /**< Invalid xform. */
62 RTE_CRYPTO_ASYM_XFORM_NONE,
64 * May be supported by PMD to support
65 * passthrough op for debugging purpose.
66 * if xform_type none , op_type is disregarded.
68 RTE_CRYPTO_ASYM_XFORM_RSA,
69 /**< RSA. Performs Encrypt, Decrypt, Sign and Verify.
70 * Refer to rte_crypto_asym_op_type
72 RTE_CRYPTO_ASYM_XFORM_DH,
74 * Performs Key Generate and Shared Secret Compute.
75 * Refer to rte_crypto_asym_op_type
77 RTE_CRYPTO_ASYM_XFORM_DSA,
78 /**< Digital Signature Algorithm
79 * Performs Signature Generation and Verification.
80 * Refer to rte_crypto_asym_op_type
82 RTE_CRYPTO_ASYM_XFORM_MODINV,
83 /**< Modular Multiplicative Inverse
84 * Perform Modular Multiplicative Inverse b^(-1) mod n
86 RTE_CRYPTO_ASYM_XFORM_MODEX,
87 /**< Modular Exponentiation
88 * Perform Modular Exponentiation b^e mod n
90 RTE_CRYPTO_ASYM_XFORM_ECDSA,
91 /**< Elliptic Curve Digital Signature Algorithm
92 * Perform Signature Generation and Verification.
94 RTE_CRYPTO_ASYM_XFORM_ECPM,
95 /**< Elliptic Curve Point Multiplication */
96 RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END
101 * Asymmetric crypto operation type variants
103 enum rte_crypto_asym_op_type {
104 RTE_CRYPTO_ASYM_OP_ENCRYPT,
105 /**< Asymmetric Encrypt operation */
106 RTE_CRYPTO_ASYM_OP_DECRYPT,
107 /**< Asymmetric Decrypt operation */
108 RTE_CRYPTO_ASYM_OP_SIGN,
109 /**< Signature Generation operation */
110 RTE_CRYPTO_ASYM_OP_VERIFY,
111 /**< Signature Verification operation */
112 RTE_CRYPTO_ASYM_OP_PRIVATE_KEY_GENERATE,
113 /**< DH Private Key generation operation */
114 RTE_CRYPTO_ASYM_OP_PUBLIC_KEY_GENERATE,
115 /**< DH Public Key generation operation */
116 RTE_CRYPTO_ASYM_OP_SHARED_SECRET_COMPUTE,
117 /**< DH Shared Secret compute operation */
118 RTE_CRYPTO_ASYM_OP_LIST_END
122 * Padding types for RSA signature.
124 enum rte_crypto_rsa_padding_type {
125 RTE_CRYPTO_RSA_PADDING_NONE = 0,
126 /**< RSA no padding scheme */
127 RTE_CRYPTO_RSA_PADDING_PKCS1_5,
128 /**< RSA PKCS#1 PKCS1-v1_5 padding scheme. For signatures block type 01,
129 * for encryption block type 02 are used.
131 RTE_CRYPTO_RSA_PADDING_OAEP,
132 /**< RSA PKCS#1 OAEP padding scheme */
133 RTE_CRYPTO_RSA_PADDING_PSS,
134 /**< RSA PKCS#1 PSS padding scheme */
135 RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END
139 * RSA private key type enumeration
141 * enumerates private key format required to perform RSA crypto
145 enum rte_crypto_rsa_priv_key_type {
146 RTE_RSA_KEY_TYPE_EXP,
147 /**< RSA private key is an exponent */
149 /**< RSA private key is in quintuple format
150 * See rte_crypto_rsa_priv_key_qt
155 * Buffer to hold crypto params required for asym operations.
157 * These buffers can be used for both input to PMD and output from PMD. When
158 * used for output from PMD, application has to ensure the buffer is large
159 * enough to hold the target data.
161 * If an operation requires the PMD to generate a random number,
162 * and the device supports CSRNG, 'data' should be set to NULL.
163 * The crypto parameter in question will not be used by the PMD,
164 * as it is internally generated.
166 typedef struct rte_crypto_param_t {
168 /**< pointer to buffer holding data */
170 /**< IO address of data buffer */
172 /**< length of data in bytes */
175 /** Unsigned big-integer in big-endian format */
176 typedef rte_crypto_param rte_crypto_uint;
179 * Structure for elliptic curve point
181 struct rte_crypto_ec_point {
189 * Structure describing RSA private key in quintuple format.
190 * See PKCS V1.5 RSA Cryptography Standard.
192 struct rte_crypto_rsa_priv_key_qt {
194 /**< the first factor */
196 /**< the second factor */
198 /**< the first factor's CRT exponent */
200 /**< the second's factor's CRT exponent */
201 rte_crypto_uint qInv;
202 /**< the CRT coefficient */
206 * Asymmetric RSA transform data
208 * Structure describing RSA xform params
211 struct rte_crypto_rsa_xform {
213 /**< the RSA modulus */
215 /**< the RSA public exponent */
217 enum rte_crypto_rsa_priv_key_type key_type;
222 /**< the RSA private exponent */
223 struct rte_crypto_rsa_priv_key_qt qt;
224 /**< qt - Private key in quintuple format */
229 * Asymmetric Modular exponentiation transform data
231 * Structure describing modular exponentiation xform param
234 struct rte_crypto_modex_xform {
235 rte_crypto_uint modulus;
236 /**< Modulus data for modexp transform operation */
237 rte_crypto_uint exponent;
238 /**< Exponent of the modexp transform operation */
242 * Asymmetric modular multiplicative inverse transform operation
244 * Structure describing modular multiplicative inverse transform
247 struct rte_crypto_modinv_xform {
248 rte_crypto_uint modulus;
249 /**< Modulus data for modular multiplicative inverse operation */
253 * Asymmetric DH transform data
255 * Structure describing deffie-hellman xform params
258 struct rte_crypto_dh_xform {
259 enum rte_crypto_asym_op_type type;
260 /**< Setup xform for key generate or shared secret compute */
262 /**< Prime modulus data */
268 * Asymmetric Digital Signature transform operation
270 * Structure describing DSA xform params
273 struct rte_crypto_dsa_xform {
275 /**< Prime modulus */
277 /**< Order of the subgroup */
279 /**< Generator of the subgroup */
281 /**< x: Private key of the signer in octet-string network
283 * Used when app has pre-defined private key.
284 * Valid only when xform chain is DSA ONLY.
285 * if xform chain is DH private key generate + DSA, then DSA sign
286 * compute will use internally generated key.
291 * Asymmetric elliptic curve transform data
293 * Structure describing all EC based xform params
296 struct rte_crypto_ec_xform {
297 enum rte_crypto_ec_group curve_id;
298 /**< Pre-defined ec groups */
302 * Operations params for modular operations:
303 * exponentiation and multiplicative inverse
306 struct rte_crypto_mod_op_param {
307 rte_crypto_uint base;
308 /** Base of modular exponentiation/multiplicative inverse */
309 rte_crypto_uint result;
310 /** Result of modular exponentiation/multiplicative inverse */
314 * RSA operation params
317 struct rte_crypto_rsa_op_param {
318 enum rte_crypto_asym_op_type op_type;
319 /**< Type of RSA operation for transform */
321 rte_crypto_param message;
323 * Pointer to input data
324 * - to be encrypted for RSA public encrypt.
325 * - to be signed for RSA sign generation.
326 * - to be authenticated for RSA sign verification.
328 * Pointer to output data
329 * - for RSA private decrypt.
330 * In this case the underlying array should have been
331 * allocated with enough memory to hold plaintext output
332 * (i.e. must be at least RSA key size). The message.length
333 * field should be 0 and will be overwritten by the PMD
334 * with the decrypted length.
336 * All data is in Octet-string network byte order format.
339 rte_crypto_param cipher;
341 * Pointer to input data
342 * - to be decrypted for RSA private decrypt.
344 * Pointer to output data
345 * - for RSA public encrypt.
346 * In this case the underlying array should have been allocated
347 * with enough memory to hold ciphertext output (i.e. must be
348 * at least RSA key size). The cipher.length field should
349 * be 0 and will be overwritten by the PMD with the encrypted length.
351 * All data is in Octet-string network byte order format.
354 rte_crypto_param sign;
356 * Pointer to input data
357 * - to be verified for RSA public decrypt.
359 * Pointer to output data
360 * - for RSA private encrypt.
361 * In this case the underlying array should have been allocated
362 * with enough memory to hold signature output (i.e. must be
363 * at least RSA key size). The sign.length field should
364 * be 0 and will be overwritten by the PMD with the signature length.
366 * All data is in Octet-string network byte order format.
369 enum rte_crypto_rsa_padding_type pad;
370 /**< RSA padding scheme to be used for transform */
372 enum rte_crypto_auth_algorithm md;
373 /**< Hash algorithm to be used for data hash if padding
374 * scheme is either OAEP or PSS. Valid hash algorithms
376 * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
379 enum rte_crypto_auth_algorithm mgf1md;
381 * Hash algorithm to be used for mask generation if
382 * padding scheme is either OAEP or PSS. If padding
383 * scheme is unspecified data hash algorithm is used
384 * for mask generation. Valid hash algorithms are:
385 * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
390 * Diffie-Hellman Operations params.
393 struct rte_crypto_dh_op_param {
394 rte_crypto_uint pub_key;
396 * Output generated public key when xform type is
397 * DH PUB_KEY_GENERATION.
398 * Input peer public key when xform type is DH
399 * SHARED_SECRET_COMPUTATION
403 rte_crypto_uint priv_key;
405 * Output generated private key if xform type is
406 * DH PRIVATE_KEY_GENERATION
407 * Input when xform type is DH SHARED_SECRET_COMPUTATION.
411 rte_crypto_uint shared_secret;
413 * Output with calculated shared secret
414 * when dh xform set up with op type = SHARED_SECRET_COMPUTATION.
420 * DSA Operations params
423 struct rte_crypto_dsa_op_param {
424 enum rte_crypto_asym_op_type op_type;
425 /**< Signature Generation or Verification */
426 rte_crypto_param message;
427 /**< input message to be signed or verified */
429 /**< Per-message secret number, which is an integer
430 * in the interval (1, q-1).
431 * If the random number is generated by the PMD,
432 * the 'rte_crypto_param.data' parameter should be set to NULL.
435 /**< dsa sign component 'r' value
437 * output if op_type = sign generate,
438 * input if op_type = sign verify
441 /**< dsa sign component 's' value
443 * output if op_type = sign generate,
444 * input if op_type = sign verify
447 /**< y : Public key of the signer.
453 * ECDSA operation params
455 struct rte_crypto_ecdsa_op_param {
456 enum rte_crypto_asym_op_type op_type;
457 /**< Signature generation or verification */
459 rte_crypto_uint pkey;
460 /**< Private key of the signer for signature generation */
462 struct rte_crypto_ec_point q;
463 /**< Public key of the signer for verification */
465 rte_crypto_param message;
466 /**< Input message digest to be signed or verified */
469 /**< The ECDSA per-message secret number, which is an integer
470 * in the interval (1, n-1).
471 * If the random number is generated by the PMD,
472 * the 'rte_crypto_param.data' parameter should be set to NULL.
476 /**< r component of elliptic curve signature
477 * output : for signature generation
478 * input : for signature verification
481 /**< s component of elliptic curve signature
482 * output : for signature generation
483 * input : for signature verification
488 * Structure for EC point multiplication operation param
490 struct rte_crypto_ecpm_op_param {
491 struct rte_crypto_ec_point p;
492 /**< x and y coordinates of input point */
494 struct rte_crypto_ec_point r;
495 /**< x and y coordinates of resultant point */
497 rte_crypto_param scalar;
498 /**< Scalar to multiply the input point */
502 * Asymmetric crypto transform data
504 * Structure describing asym xforms.
506 struct rte_crypto_asym_xform {
507 struct rte_crypto_asym_xform *next;
508 /**< Pointer to next xform to set up xform chain.*/
509 enum rte_crypto_asym_xform_type xform_type;
510 /**< Asymmetric crypto transform */
514 struct rte_crypto_rsa_xform rsa;
515 /**< RSA xform parameters */
517 struct rte_crypto_modex_xform modex;
518 /**< Modular Exponentiation xform parameters */
520 struct rte_crypto_modinv_xform modinv;
521 /**< Modular Multiplicative Inverse xform parameters */
523 struct rte_crypto_dh_xform dh;
524 /**< DH xform parameters */
526 struct rte_crypto_dsa_xform dsa;
527 /**< DSA xform parameters */
529 struct rte_crypto_ec_xform ec;
530 /**< EC xform parameters, used by elliptic curve based
537 * Asymmetric Cryptographic Operation.
539 * Structure describing asymmetric crypto operation params.
542 struct rte_crypto_asym_op {
545 struct rte_cryptodev_asym_session *session;
546 /**< Handle for the initialised session context */
547 struct rte_crypto_asym_xform *xform;
548 /**< Session-less API crypto operation parameters */
553 struct rte_crypto_rsa_op_param rsa;
554 struct rte_crypto_mod_op_param modex;
555 struct rte_crypto_mod_op_param modinv;
556 struct rte_crypto_dh_op_param dh;
557 struct rte_crypto_dsa_op_param dsa;
558 struct rte_crypto_ecdsa_op_param ecdsa;
559 struct rte_crypto_ecpm_op_param ecpm;
567 #endif /* _RTE_CRYPTO_ASYM_H_ */