cryptodev: add RSA padding salt length and label
[dpdk.git] / lib / 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 #include "rte_crypto_sym.h"
29
30 struct rte_cryptodev_asym_session;
31
32 /** asym xform type name strings */
33 extern const char *
34 rte_crypto_asym_xform_strings[];
35
36 /** asym key exchange operation type name strings */
37 extern const char *
38 rte_crypto_asym_ke_strings[];
39
40 /** asym operations type name strings */
41 extern const char *
42 rte_crypto_asym_op_strings[];
43
44 #define RTE_CRYPTO_ASYM_FLAG_PUB_KEY_NO_PADDING         RTE_BIT32(0)
45 /**<
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)
49  */
50 #define RTE_CRYPTO_ASYM_FLAG_SHARED_KEY_NO_PADDING      RTE_BIT32(1)
51 /**<
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)
55  */
56
57 /**
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
65  */
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
72 };
73
74 /**
75  * Asymmetric crypto transformation types.
76  * Each xform type maps to one asymmetric algorithm
77  * performing specific operation
78  *
79  */
80 enum rte_crypto_asym_xform_type {
81         RTE_CRYPTO_ASYM_XFORM_UNSPECIFIED = 0,
82         /**< Invalid xform. */
83         RTE_CRYPTO_ASYM_XFORM_NONE,
84         /**< Xform type None.
85          * May be supported by PMD to support
86          * passthrough op for debugging purpose.
87          * if xform_type none , op_type is disregarded.
88          */
89         RTE_CRYPTO_ASYM_XFORM_RSA,
90         /**< RSA. Performs Encrypt, Decrypt, Sign and Verify.
91          * Refer to rte_crypto_asym_op_type
92          */
93         RTE_CRYPTO_ASYM_XFORM_DH,
94         /**< Diffie-Hellman.
95          * Performs Key Generate and Shared Secret Compute.
96          * Refer to rte_crypto_asym_op_type
97          */
98         RTE_CRYPTO_ASYM_XFORM_DSA,
99         /**< Digital Signature Algorithm
100          * Performs Signature Generation and Verification.
101          * Refer to rte_crypto_asym_op_type
102          */
103         RTE_CRYPTO_ASYM_XFORM_MODINV,
104         /**< Modular Multiplicative Inverse
105          * Perform Modular Multiplicative Inverse b^(-1) mod n
106          */
107         RTE_CRYPTO_ASYM_XFORM_MODEX,
108         /**< Modular Exponentiation
109          * Perform Modular Exponentiation b^e mod n
110          */
111         RTE_CRYPTO_ASYM_XFORM_ECDSA,
112         /**< Elliptic Curve Digital Signature Algorithm
113          * Perform Signature Generation and Verification.
114          */
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
120         /**< End of list */
121 };
122
123 /**
124  * Asymmetric crypto operation type variants
125  */
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
136 };
137
138 /**
139  * Asymmetric crypto key exchange operation type
140  */
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.
151          */
152 };
153
154 /**
155  * Padding types for RSA signature.
156  */
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.
163          */
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
169 };
170
171 /**
172  * RSA private key type enumeration
173  *
174  * enumerates private key format required to perform RSA crypto
175  * transform.
176  *
177  */
178 enum rte_crypto_rsa_priv_key_type {
179         RTE_RSA_KEY_TYPE_EXP,
180         /**< RSA private key is an exponent */
181         RTE_RSA_KEY_TYPE_QT,
182         /**< RSA private key is in quintuple format
183          * See rte_crypto_rsa_priv_key_qt
184          */
185 };
186
187 /**
188  * Buffer to hold crypto params required for asym operations.
189  *
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.
193  *
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.
198  */
199 typedef struct rte_crypto_param_t {
200         uint8_t *data;
201         /**< pointer to buffer holding data */
202         rte_iova_t iova;
203         /**< IO address of data buffer */
204         size_t length;
205         /**< length of data in bytes */
206 } rte_crypto_param;
207
208 /** Unsigned big-integer in big-endian format */
209 typedef rte_crypto_param rte_crypto_uint;
210
211 /**
212  * Structure for elliptic curve point
213  */
214 struct rte_crypto_ec_point {
215         rte_crypto_param x;
216         /**< X coordinate */
217         rte_crypto_param y;
218         /**< Y coordinate */
219 };
220
221 /**
222  * Structure describing RSA private key in quintuple format.
223  * See PKCS V1.5 RSA Cryptography Standard.
224  */
225 struct rte_crypto_rsa_priv_key_qt {
226         rte_crypto_uint p;
227         /**< the first factor */
228         rte_crypto_uint q;
229         /**< the second factor */
230         rte_crypto_uint dP;
231         /**< the first factor's CRT exponent */
232         rte_crypto_uint dQ;
233         /**< the second's factor's CRT exponent */
234         rte_crypto_uint qInv;
235         /**< the CRT coefficient */
236 };
237
238 /**
239  * RSA padding type
240  */
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;
245         /**<
246          * RSA padding hash algorithm
247          * Valid hash algorithms are:
248          * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
249          *
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
253          *
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
259          * padding type.
260          *
261          * - RTE_CRYPTO_RSA_PADDING_OAEP
262          * This field shall be set with the hash algorithm used
263          * in the padding scheme
264          *
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)
268          */
269         enum rte_crypto_auth_algorithm mgf1hash;
270         /**<
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
276          */
277         uint16_t pss_saltlen;
278         /**<
279          * RSA PSS padding salt length
280          *
281          * Used only when RTE_CRYPTO_RSA_PADDING_PSS padding is selected,
282          * otherwise ignored.
283          */
284         rte_crypto_param oaep_label;
285         /**<
286          * RSA OAEP padding optional label
287          *
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.
291          */
292 };
293
294 /**
295  * Asymmetric RSA transform data
296  *
297  * Structure describing RSA xform params
298  *
299  */
300 struct rte_crypto_rsa_xform {
301         rte_crypto_uint n;
302         /**< the RSA modulus */
303         rte_crypto_uint e;
304         /**< the RSA public exponent */
305
306         enum rte_crypto_rsa_priv_key_type key_type;
307
308         RTE_STD_C11
309         union {
310                 rte_crypto_uint d;
311                 /**< the RSA private exponent */
312                 struct rte_crypto_rsa_priv_key_qt qt;
313                 /**< qt - Private key in quintuple format */
314         };
315 };
316
317 /**
318  * Asymmetric Modular exponentiation transform data
319  *
320  * Structure describing modular exponentiation xform param
321  *
322  */
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 */
328 };
329
330 /**
331  * Asymmetric modular multiplicative inverse transform operation
332  *
333  * Structure describing modular multiplicative inverse transform
334  *
335  */
336 struct rte_crypto_modinv_xform {
337         rte_crypto_uint modulus;
338         /**< Modulus data for modular multiplicative inverse operation */
339 };
340
341 /**
342  * Asymmetric DH transform data
343  *
344  * Structure describing deffie-hellman xform params
345  *
346  */
347 struct rte_crypto_dh_xform {
348         rte_crypto_uint p;
349         /**< Prime modulus data */
350         rte_crypto_uint g;
351         /**< DH Generator */
352 };
353
354 /**
355  * Asymmetric Digital Signature transform operation
356  *
357  * Structure describing DSA xform params
358  *
359  */
360 struct rte_crypto_dsa_xform {
361         rte_crypto_uint p;
362         /**< Prime modulus */
363         rte_crypto_uint q;
364         /**< Order of the subgroup */
365         rte_crypto_uint g;
366         /**< Generator of the subgroup */
367         rte_crypto_uint x;
368         /**< x: Private key of the signer */
369 };
370
371 /**
372  * Asymmetric elliptic curve transform data
373  *
374  * Structure describing all EC based xform params
375  *
376  */
377 struct rte_crypto_ec_xform {
378         enum rte_crypto_curve_id curve_id;
379         /**< Pre-defined ec groups */
380 };
381
382 /**
383  * Operations params for modular operations:
384  * exponentiation and multiplicative inverse
385  *
386  */
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 */
392 };
393
394 /**
395  * RSA operation params
396  *
397  */
398 struct rte_crypto_rsa_op_param {
399         enum rte_crypto_asym_op_type op_type;
400         /**< Type of RSA operation for transform */
401
402         rte_crypto_param message;
403         /**<
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.
408          *
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.
416          */
417
418         rte_crypto_param cipher;
419         /**<
420          * Pointer to input data
421          * - to be decrypted for RSA private decrypt.
422          *
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.
429          *
430          * When RTE_CRYPTO_RSA_PADDING_NONE and RTE_CRYPTO_ASYM_OP_VERIFY
431          * selected, this is an output of decrypted signature.
432          */
433
434         rte_crypto_param sign;
435         /**<
436          * Pointer to input data
437          * - to be verified for RSA public decrypt.
438          *
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.
445          */
446
447         struct rte_crypto_rsa_padding padding;
448         /**< RSA padding information */
449 };
450
451 /**
452  * Diffie-Hellman Operations params.
453  * @note:
454  */
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;
459         /**<
460          * Output - generated private key when ke_type is
461          * RTE_CRYPTO_ASYM_KE_PRIV_KEY_GENERATE.
462          *
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.
466          *
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
470          * key generation.
471          */
472         rte_crypto_uint pub_key;
473         /**<
474          * Output - generated public key when ke_type is
475          * RTE_CRYPTO_ASYM_KE_PUB_KEY_GENERATE.
476          *
477          * Input - peer's public key when ke_type is
478          * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
479          */
480         rte_crypto_uint shared_secret;
481         /**<
482          * Output - calculated shared secret when ke_type is
483          * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
484          */
485 };
486
487 /**
488  * Elliptic Curve Diffie-Hellman Operations params.
489  */
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;
494         /**<
495          * Output - generated private key when ke_type is
496          * RTE_CRYPTO_ASYM_KE_PRIVATE_KEY_GENERATE.
497          *
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.
501          *
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
505          * key generation.
506          */
507         struct rte_crypto_ec_point pub_key;
508         /**<
509          * Output - generated public key when ke_type is
510          * RTE_CRYPTO_ASYM_KE_PUBLIC_KEY_GENERATE.
511          *
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.
515          */
516         struct rte_crypto_ec_point shared_secret;
517         /**<
518          * Output - calculated shared secret when ke_type is
519          * RTE_CRYPTO_ASYM_KE_SHARED_SECRET_COMPUTE.
520          */
521 };
522
523 /**
524  * DSA Operations params
525  *
526  */
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 */
532         rte_crypto_uint k;
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.
537          */
538         rte_crypto_uint r;
539         /**< dsa sign component 'r' value
540          *
541          * output if op_type = sign generate,
542          * input if op_type = sign verify
543          */
544         rte_crypto_uint s;
545         /**< dsa sign component 's' value
546          *
547          * output if op_type = sign generate,
548          * input if op_type = sign verify
549          */
550         rte_crypto_uint y;
551         /**< y : Public key of the signer.
552          * y = g^x mod p
553          */
554 };
555
556 /**
557  * ECDSA operation params
558  */
559 struct rte_crypto_ecdsa_op_param {
560         enum rte_crypto_asym_op_type op_type;
561         /**< Signature generation or verification */
562
563         rte_crypto_uint pkey;
564         /**< Private key of the signer for signature generation */
565
566         struct rte_crypto_ec_point q;
567         /**< Public key of the signer for verification */
568
569         rte_crypto_param message;
570         /**< Input message digest to be signed or verified */
571
572         rte_crypto_uint k;
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.
577          */
578
579         rte_crypto_uint r;
580         /**< r component of elliptic curve signature
581          *     output : for signature generation
582          *     input  : for signature verification
583          */
584         rte_crypto_uint s;
585         /**< s component of elliptic curve signature
586          *     output : for signature generation
587          *     input  : for signature verification
588          */
589 };
590
591 /**
592  * Structure for EC point multiplication operation param
593  */
594 struct rte_crypto_ecpm_op_param {
595         struct rte_crypto_ec_point p;
596         /**< x and y coordinates of input point */
597
598         struct rte_crypto_ec_point r;
599         /**< x and y coordinates of resultant point */
600
601         rte_crypto_param scalar;
602         /**< Scalar to multiply the input point */
603 };
604
605 /**
606  * Asymmetric crypto transform data
607  *
608  * Structure describing asym xforms.
609  */
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 */
615
616         RTE_STD_C11
617         union {
618                 struct rte_crypto_rsa_xform rsa;
619                 /**< RSA xform parameters */
620
621                 struct rte_crypto_modex_xform modex;
622                 /**< Modular Exponentiation xform parameters */
623
624                 struct rte_crypto_modinv_xform modinv;
625                 /**< Modular Multiplicative Inverse xform parameters */
626
627                 struct rte_crypto_dh_xform dh;
628                 /**< DH xform parameters */
629
630                 struct rte_crypto_dsa_xform dsa;
631                 /**< DSA xform parameters */
632
633                 struct rte_crypto_ec_xform ec;
634                 /**< EC xform parameters, used by elliptic curve based
635                  * operations.
636                  */
637         };
638 };
639
640 /**
641  * Asymmetric Cryptographic Operation.
642  *
643  * Structure describing asymmetric crypto operation params.
644  *
645  */
646 struct rte_crypto_asym_op {
647         RTE_STD_C11
648         union {
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 */
653         };
654
655         RTE_STD_C11
656         union {
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;
665         };
666         uint16_t flags;
667         /**<
668          * Asymmetric crypto operation flags.
669          * Please refer to the RTE_CRYPTO_ASYM_FLAG_*.
670          */
671 };
672
673 #ifdef __cplusplus
674 }
675 #endif
676
677 #endif /* _RTE_CRYPTO_ASYM_H_ */