common/octeontx2: upgrade mbox definition to version 7
[dpdk.git] / lib / librte_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 /**
31  * Buffer to hold crypto params required for asym operations.
32  *
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.
36  */
37 typedef struct rte_crypto_param_t {
38         uint8_t *data;
39         /**< pointer to buffer holding data */
40         rte_iova_t iova;
41         /**< IO address of data buffer */
42         size_t length;
43         /**< length of data in bytes */
44 } rte_crypto_param;
45
46 /** asym xform type name strings */
47 extern const char *
48 rte_crypto_asym_xform_strings[];
49
50 /** asym operations type name strings */
51 extern const char *
52 rte_crypto_asym_op_strings[];
53
54 /**
55  * Asymmetric crypto transformation types.
56  * Each xform type maps to one asymmetric algorithm
57  * performing specific operation
58  *
59  */
60 enum rte_crypto_asym_xform_type {
61         RTE_CRYPTO_ASYM_XFORM_UNSPECIFIED = 0,
62         /**< Invalid xform. */
63         RTE_CRYPTO_ASYM_XFORM_NONE,
64         /**< Xform type None.
65          * May be supported by PMD to support
66          * passthrough op for debugging purpose.
67          * if xform_type none , op_type is disregarded.
68          */
69         RTE_CRYPTO_ASYM_XFORM_RSA,
70         /**< RSA. Performs Encrypt, Decrypt, Sign and Verify.
71          * Refer to rte_crypto_asym_op_type
72          */
73         RTE_CRYPTO_ASYM_XFORM_DH,
74         /**< Diffie-Hellman.
75          * Performs Key Generate and Shared Secret Compute.
76          * Refer to rte_crypto_asym_op_type
77          */
78         RTE_CRYPTO_ASYM_XFORM_DSA,
79         /**< Digital Signature Algorithm
80          * Performs Signature Generation and Verification.
81          * Refer to rte_crypto_asym_op_type
82          */
83         RTE_CRYPTO_ASYM_XFORM_MODINV,
84         /**< Modular Multiplicative Inverse
85          * Perform Modular Multiplicative Inverse b^(-1) mod n
86          */
87         RTE_CRYPTO_ASYM_XFORM_MODEX,
88         /**< Modular Exponentiation
89          * Perform Modular Exponentiation b^e mod n
90          */
91         RTE_CRYPTO_ASYM_XFORM_ECDSA,
92         /**< Elliptic Curve Digital Signature Algorithm
93          * Perform Signature Generation and Verification.
94          */
95         RTE_CRYPTO_ASYM_XFORM_ECPM,
96         /**< Elliptic Curve Point Multiplication */
97         RTE_CRYPTO_ASYM_XFORM_TYPE_LIST_END
98         /**< End of list */
99 };
100
101 /**
102  * Asymmetric crypto operation type variants
103  */
104 enum rte_crypto_asym_op_type {
105         RTE_CRYPTO_ASYM_OP_ENCRYPT,
106         /**< Asymmetric Encrypt operation */
107         RTE_CRYPTO_ASYM_OP_DECRYPT,
108         /**< Asymmetric Decrypt operation */
109         RTE_CRYPTO_ASYM_OP_SIGN,
110         /**< Signature Generation operation */
111         RTE_CRYPTO_ASYM_OP_VERIFY,
112         /**< Signature Verification operation */
113         RTE_CRYPTO_ASYM_OP_PRIVATE_KEY_GENERATE,
114         /**< DH Private Key generation operation */
115         RTE_CRYPTO_ASYM_OP_PUBLIC_KEY_GENERATE,
116         /**< DH Public Key generation operation */
117         RTE_CRYPTO_ASYM_OP_SHARED_SECRET_COMPUTE,
118         /**< DH Shared Secret compute operation */
119         RTE_CRYPTO_ASYM_OP_LIST_END
120 };
121
122 /**
123  * Padding types for RSA signature.
124  */
125 enum rte_crypto_rsa_padding_type {
126         RTE_CRYPTO_RSA_PADDING_NONE = 0,
127         /**< RSA no padding scheme */
128         RTE_CRYPTO_RSA_PADDING_PKCS1_5,
129         /**< RSA PKCS#1 PKCS1-v1_5 padding scheme. For signatures block type 01,
130          * for encryption block type 02 are used.
131          */
132         RTE_CRYPTO_RSA_PADDING_OAEP,
133         /**< RSA PKCS#1 OAEP padding scheme */
134         RTE_CRYPTO_RSA_PADDING_PSS,
135         /**< RSA PKCS#1 PSS padding scheme */
136         RTE_CRYPTO_RSA_PADDING_TYPE_LIST_END
137 };
138
139 /**
140  * RSA private key type enumeration
141  *
142  * enumerates private key format required to perform RSA crypto
143  * transform.
144  *
145  */
146 enum rte_crypto_rsa_priv_key_type {
147         RTE_RSA_KEY_TYPE_EXP,
148         /**< RSA private key is an exponent */
149         RTE_RSA_KET_TYPE_QT,
150         /**< RSA private key is in quintuple format
151          * See rte_crypto_rsa_priv_key_qt
152          */
153 };
154
155 /**
156  * Structure describing RSA private key in quintuple format.
157  * See PKCS V1.5 RSA Cryptography Standard.
158  */
159 struct rte_crypto_rsa_priv_key_qt {
160         rte_crypto_param p;
161         /**< p - Private key component P
162          * Private key component of RSA parameter  required for CRT method
163          * of private key operations in Octet-string network byte order
164          * format.
165          */
166
167         rte_crypto_param q;
168         /**< q - Private key component Q
169          * Private key component of RSA parameter  required for CRT method
170          * of private key operations in Octet-string network byte order
171          * format.
172          */
173
174         rte_crypto_param dP;
175         /**< dP - Private CRT component
176          * Private CRT component of RSA parameter  required for CRT method
177          * RSA private key operations in Octet-string network byte order
178          * format.
179          * dP = d mod ( p - 1 )
180          */
181
182         rte_crypto_param dQ;
183         /**< dQ - Private CRT component
184          * Private CRT component of RSA parameter  required for CRT method
185          * RSA private key operations in Octet-string network byte order
186          * format.
187          * dQ = d mod ( q - 1 )
188          */
189
190         rte_crypto_param qInv;
191         /**< qInv - Private CRT component
192          * Private CRT component of RSA parameter  required for CRT method
193          * RSA private key operations in Octet-string network byte order
194          * format.
195          * qInv = inv q mod p
196          */
197 };
198
199 /**
200  * Asymmetric RSA transform data
201  *
202  * Structure describing RSA xform params
203  *
204  */
205 struct rte_crypto_rsa_xform {
206         rte_crypto_param n;
207         /**< n - Modulus
208          * Modulus data of RSA operation in Octet-string network
209          * byte order format.
210          */
211
212         rte_crypto_param e;
213         /**< e - Public key exponent
214          * Public key exponent used for RSA public key operations in Octet-
215          * string network byte order format.
216          */
217
218         enum rte_crypto_rsa_priv_key_type key_type;
219
220         __extension__
221         union {
222                 rte_crypto_param d;
223                 /**< d - Private key exponent
224                  * Private key exponent used for RSA
225                  * private key operations in
226                  * Octet-string  network byte order format.
227                  */
228
229                 struct rte_crypto_rsa_priv_key_qt qt;
230                 /**< qt - Private key in quintuple format */
231         };
232 };
233
234 /**
235  * Asymmetric Modular exponentiation transform data
236  *
237  * Structure describing modular exponentiation xform param
238  *
239  */
240 struct rte_crypto_modex_xform {
241         rte_crypto_param modulus;
242         /**< modulus
243          * Pointer to the modulus data for modexp transform operation
244          * in octet-string network byte order format
245          *
246          * In case this number is equal to zero the driver shall set
247          * the crypto op status field to RTE_CRYPTO_OP_STATUS_ERROR
248          */
249
250         rte_crypto_param exponent;
251         /**< exponent
252          * Exponent of the modexp transform operation in
253          * octet-string network byte order format
254          */
255 };
256
257 /**
258  * Asymmetric modular multiplicative inverse transform operation
259  *
260  * Structure describing modular multiplicative inverse transform
261  *
262  */
263 struct rte_crypto_modinv_xform {
264         rte_crypto_param modulus;
265         /**<
266          * Pointer to the modulus data for modular multiplicative inverse
267          * operation in octet-string network byte order format
268          *
269          * In case this number is equal to zero the driver shall set
270          * the crypto op status field to RTE_CRYPTO_OP_STATUS_ERROR
271          *
272          * This number shall be relatively prime to base
273          * in corresponding Modular Multiplicative Inverse
274          * rte_crypto_mod_op_param
275          */
276 };
277
278 /**
279  * Asymmetric DH transform data
280  *
281  * Structure describing deffie-hellman xform params
282  *
283  */
284 struct rte_crypto_dh_xform {
285         enum rte_crypto_asym_op_type type;
286         /**< Setup xform for key generate or shared secret compute */
287
288         rte_crypto_param p;
289         /**< p : Prime modulus data
290          * DH prime modulus data in octet-string network byte order format.
291          *
292          */
293
294         rte_crypto_param g;
295         /**< g : Generator
296          * DH group generator data in octet-string network byte order
297          * format.
298          *
299          */
300 };
301
302 /**
303  * Asymmetric Digital Signature transform operation
304  *
305  * Structure describing DSA xform params
306  *
307  */
308 struct rte_crypto_dsa_xform {
309         rte_crypto_param p;
310         /**< p - Prime modulus
311          * Prime modulus data for DSA operation in Octet-string network byte
312          * order format.
313          */
314         rte_crypto_param q;
315         /**< q : Order of the subgroup.
316          * Order of the subgroup data in Octet-string network byte order
317          * format.
318          * (p-1) % q = 0
319          */
320         rte_crypto_param g;
321         /**< g: Generator of the subgroup
322          * Generator  data in Octet-string network byte order format.
323          */
324         rte_crypto_param x;
325         /**< x: Private key of the signer in octet-string network
326          * byte order format.
327          * Used when app has pre-defined private key.
328          * Valid only when xform chain is DSA ONLY.
329          * if xform chain is DH private key generate + DSA, then DSA sign
330          * compute will use internally generated key.
331          */
332 };
333
334 /**
335  * TLS named curves
336  * https://tools.ietf.org/html/rfc8422
337  */
338 enum rte_crypto_ec_group {
339         RTE_CRYPTO_EC_GROUP_UNKNOWN  = 0,
340         RTE_CRYPTO_EC_GROUP_SECP192R1 = 19,
341         RTE_CRYPTO_EC_GROUP_SECP224R1 = 21,
342         RTE_CRYPTO_EC_GROUP_SECP256R1 = 23,
343         RTE_CRYPTO_EC_GROUP_SECP384R1 = 24,
344         RTE_CRYPTO_EC_GROUP_SECP521R1 = 25,
345 };
346
347 /**
348  * Structure for elliptic curve point
349  */
350 struct rte_crypto_ec_point {
351         rte_crypto_param x;
352         /**< X coordinate */
353         rte_crypto_param y;
354         /**< Y coordinate */
355 };
356
357 /**
358  * Asymmetric elliptic curve transform data
359  *
360  * Structure describing all EC based xform params
361  *
362  */
363 struct rte_crypto_ec_xform {
364         enum rte_crypto_ec_group curve_id;
365         /**< Pre-defined ec groups */
366 };
367
368 /**
369  * Operations params for modular operations:
370  * exponentiation and multiplicative inverse
371  *
372  */
373 struct rte_crypto_mod_op_param {
374         rte_crypto_param base;
375         /**<
376          * Pointer to base of modular exponentiation/multiplicative
377          * inverse data in octet-string network byte order format
378          *
379          * In case Multiplicative Inverse is used this number shall
380          * be relatively prime to modulus in corresponding Modular
381          * Multiplicative Inverse rte_crypto_modinv_xform
382          */
383
384         rte_crypto_param result;
385         /**<
386          * Pointer to the result of modular exponentiation/multiplicative inverse
387          * data in octet-string network byte order format.
388          *
389          * This field shall be big enough to hold the result of Modular
390          * Exponentiation or Modular Multiplicative Inverse
391          * (bigger or equal to length of modulus)
392          */
393 };
394
395 /**
396  * Asymmetric crypto transform data
397  *
398  * Structure describing asym xforms.
399  */
400 struct rte_crypto_asym_xform {
401         struct rte_crypto_asym_xform *next;
402         /**< Pointer to next xform to set up xform chain.*/
403         enum rte_crypto_asym_xform_type xform_type;
404         /**< Asymmetric crypto transform */
405
406         __extension__
407         union {
408                 struct rte_crypto_rsa_xform rsa;
409                 /**< RSA xform parameters */
410
411                 struct rte_crypto_modex_xform modex;
412                 /**< Modular Exponentiation xform parameters */
413
414                 struct rte_crypto_modinv_xform modinv;
415                 /**< Modular Multiplicative Inverse xform parameters */
416
417                 struct rte_crypto_dh_xform dh;
418                 /**< DH xform parameters */
419
420                 struct rte_crypto_dsa_xform dsa;
421                 /**< DSA xform parameters */
422
423                 struct rte_crypto_ec_xform ec;
424                 /**< EC xform parameters, used by elliptic curve based
425                  * operations.
426                  */
427         };
428 };
429
430 struct rte_cryptodev_asym_session;
431
432 /**
433  * RSA operation params
434  *
435  */
436 struct rte_crypto_rsa_op_param {
437         enum rte_crypto_asym_op_type op_type;
438         /**< Type of RSA operation for transform */
439
440         rte_crypto_param message;
441         /**<
442          * Pointer to input data
443          * - to be encrypted for RSA public encrypt.
444          * - to be signed for RSA sign generation.
445          * - to be authenticated for RSA sign verification.
446          *
447          * Pointer to output data
448          * - for RSA private decrypt.
449          * In this case the underlying array should have been
450          * allocated with enough memory to hold plaintext output
451          * (i.e. must be at least RSA key size). The message.length
452          * field should be 0 and will be overwritten by the PMD
453          * with the decrypted length.
454          *
455          * All data is in Octet-string network byte order format.
456          */
457
458         rte_crypto_param cipher;
459         /**<
460          * Pointer to input data
461          * - to be decrypted for RSA private decrypt.
462          *
463          * Pointer to output data
464          * - for RSA public encrypt.
465          * In this case the underlying array should have been allocated
466          * with enough memory to hold ciphertext output (i.e. must be
467          * at least RSA key size). The cipher.length field should
468          * be 0 and will be overwritten by the PMD with the encrypted length.
469          *
470          * All data is in Octet-string network byte order format.
471          */
472
473         rte_crypto_param sign;
474         /**<
475          * Pointer to input data
476          * - to be verified for RSA public decrypt.
477          *
478          * Pointer to output data
479          * - for RSA private encrypt.
480          * In this case the underlying array should have been allocated
481          * with enough memory to hold signature output (i.e. must be
482          * at least RSA key size). The sign.length field should
483          * be 0 and will be overwritten by the PMD with the signature length.
484          *
485          * All data is in Octet-string network byte order format.
486          */
487
488         enum rte_crypto_rsa_padding_type pad;
489         /**< RSA padding scheme to be used for transform */
490
491         enum rte_crypto_auth_algorithm md;
492         /**< Hash algorithm to be used for data hash if padding
493          * scheme is either OAEP or PSS. Valid hash algorithms
494          * are:
495          * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
496          */
497
498         enum rte_crypto_auth_algorithm mgf1md;
499         /**<
500          * Hash algorithm to be used for mask generation if
501          * padding scheme is either OAEP or PSS. If padding
502          * scheme is unspecified data hash algorithm is used
503          * for mask generation. Valid hash algorithms are:
504          * MD5, SHA1, SHA224, SHA256, SHA384, SHA512
505          */
506 };
507
508 /**
509  * Diffie-Hellman Operations params.
510  * @note:
511  */
512 struct rte_crypto_dh_op_param {
513         rte_crypto_param pub_key;
514         /**<
515          * Output generated public key when xform type is
516          * DH PUB_KEY_GENERATION.
517          * Input peer public key when xform type is DH
518          * SHARED_SECRET_COMPUTATION
519          * pub_key is in octet-string network byte order format.
520          *
521          */
522
523         rte_crypto_param priv_key;
524         /**<
525          * Output generated private key if xform type is
526          * DH PRIVATE_KEY_GENERATION
527          * Input when xform type is DH SHARED_SECRET_COMPUTATION.
528          * priv_key is in octet-string network byte order format.
529          *
530          */
531
532         rte_crypto_param shared_secret;
533         /**<
534          * Output with calculated shared secret
535          * when dh xform set up with op type = SHARED_SECRET_COMPUTATION.
536          * shared_secret is an octet-string network byte order format.
537          *
538          */
539 };
540
541 /**
542  * DSA Operations params
543  *
544  */
545 struct rte_crypto_dsa_op_param {
546         enum rte_crypto_asym_op_type op_type;
547         /**< Signature Generation or Verification */
548         rte_crypto_param message;
549         /**< input message to be signed or verified */
550         rte_crypto_param r;
551         /**< dsa sign component 'r' value
552          *
553          * output if op_type = sign generate,
554          * input if op_type = sign verify
555          */
556         rte_crypto_param s;
557         /**< dsa sign component 's' value
558          *
559          * output if op_type = sign generate,
560          * input if op_type = sign verify
561          */
562         rte_crypto_param y;
563         /**< y : Public key of the signer.
564          * Public key data of the signer in Octet-string network byte order
565          * format.
566          * y = g^x mod p
567          */
568 };
569
570 /**
571  * ECDSA operation params
572  */
573 struct rte_crypto_ecdsa_op_param {
574         enum rte_crypto_asym_op_type op_type;
575         /**< Signature generation or verification */
576
577         rte_crypto_param pkey;
578         /**< Private key of the signer for signature generation */
579
580         struct rte_crypto_ec_point q;
581         /**< Public key of the signer for verification */
582
583         rte_crypto_param message;
584         /**< Input message digest to be signed or verified */
585
586         rte_crypto_param k;
587         /**< The ECDSA per-message secret number, which is an integer
588          * in the interval (1, n-1)
589          */
590
591         rte_crypto_param r;
592         /**< r component of elliptic curve signature
593          *     output : for signature generation
594          *     input  : for signature verification
595          */
596         rte_crypto_param s;
597         /**< s component of elliptic curve signature
598          *     output : for signature generation
599          *     input  : for signature verification
600          */
601 };
602
603 /**
604  * Structure for EC point multiplication operation param
605  */
606 struct rte_crypto_ecpm_op_param {
607         struct rte_crypto_ec_point p;
608         /**< x and y coordinates of input point */
609
610         struct rte_crypto_ec_point r;
611         /**< x and y coordinates of resultant point */
612
613         rte_crypto_param scalar;
614         /**< Scalar to multiply the input point */
615 };
616
617 /**
618  * Asymmetric Cryptographic Operation.
619  *
620  * Structure describing asymmetric crypto operation params.
621  *
622  */
623 struct rte_crypto_asym_op {
624         RTE_STD_C11
625         union {
626                 struct rte_cryptodev_asym_session *session;
627                 /**< Handle for the initialised session context */
628                 struct rte_crypto_asym_xform *xform;
629                 /**< Session-less API crypto operation parameters */
630         };
631
632         __extension__
633         union {
634                 struct rte_crypto_rsa_op_param rsa;
635                 struct rte_crypto_mod_op_param modex;
636                 struct rte_crypto_mod_op_param modinv;
637                 struct rte_crypto_dh_op_param dh;
638                 struct rte_crypto_dsa_op_param dsa;
639                 struct rte_crypto_ecdsa_op_param ecdsa;
640                 struct rte_crypto_ecpm_op_param ecpm;
641         };
642 };
643
644 #ifdef __cplusplus
645 }
646 #endif
647
648 #endif /* _RTE_CRYPTO_ASYM_H_ */