xref: /freebsd/sys/dev/qat/qat_api/include/lac/cpa_cy_rsa.h (revision 2542189532b3025577fa4e782904494f3587008b)
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /* Copyright(c) 2007-2025 Intel Corporation */
3 
4 /*
5  *****************************************************************************
6  * Doxygen group definitions
7  ****************************************************************************/
8 
9 /**
10  *****************************************************************************
11  * @file cpa_cy_rsa.h
12  *
13  * @defgroup cpaCyRsa RSA API
14  *
15  * @ingroup cpaCy
16  *
17  * @description
18  *      These functions specify the API for Public Key Encryption
19  *      (Cryptography) RSA operations. The PKCS #1 V2.1 specification is
20  *      supported, however the support is limited to "two-prime" mode. RSA
21  *      multi-prime is not supported.
22  *
23  * @note
24  *     These functions implement RSA cryptographic primitives. RSA padding
25  *     schemes are not implemented. For padding schemes that require the mgf
26  *     function see @ref cpaCyKeyGen.
27  *
28  * @note
29  *      Large numbers are represented on the QuickAssist API as described
30  *      in the Large Number API (@ref cpaCyLn).
31  *****************************************************************************/
32 
33 #ifndef CPA_CY_RSA_H
34 #define CPA_CY_RSA_H
35 
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39 
40 #include "cpa_cy_common.h"
41 
42 /**
43  *****************************************************************************
44  * @ingroup cpaCyRsa
45  *      RSA Version.
46  * @description
47  *      This enumeration lists the version identifier for the PKCS #1 V2.1
48  *      standard.
49  * @note
50  *      Multi-prime (more than two primes) is not supported.
51  *
52  *****************************************************************************/
53 typedef enum _CpaCyRsaVersion
54 {
55     CPA_CY_RSA_VERSION_TWO_PRIME = 1
56     /**< The version supported is "two-prime". */
57 } CpaCyRsaVersion;
58 
59 /**
60  *****************************************************************************
61  * @ingroup cpaCyRsa
62  *      RSA Public Key Structure.
63  * @description
64  *      This structure contains the two components which comprise the RSA
65  *      public key as defined in the PKCS #1 V2.1 standard.
66  *      All values in this structure are required to be in Most Significant Byte
67  *      first order, e.g. modulusN.pData[0] = MSB.
68  *
69  *****************************************************************************/
70 typedef struct _CpaCyRsaPublicKey {
71     CpaFlatBuffer modulusN;
72     /**< The modulus (n).
73      * For key generation operations, the client MUST allocate the memory
74      * for this parameter; its value is generated.
75      * For encrypt operations this parameter is an input. */
76     CpaFlatBuffer publicExponentE;
77     /**< The public exponent (e).
78      * For key generation operations, this field is unused.  It is NOT
79      * generated by the interface; it is the responsibility of the client
80      * to set this to the same value as the corresponding parameter on
81      * the CpaCyRsaKeyGenOpData structure before using the key for
82      * encryption.
83      * For encrypt operations this parameter is an input. */
84 } CpaCyRsaPublicKey;
85 
86 /**
87  *****************************************************************************
88  * @ingroup cpaCyRsa
89  *      RSA Private Key Structure For Representation 1.
90  * @description
91  *      This structure contains the first representation that can be used for
92  *      describing the RSA private key, represented by the tuple of the
93  *      modulus (n) and the private exponent (d).
94  *      All values in this structure are required to be in Most Significant Byte
95  *      first order, e.g. modulusN.pData[0] = MSB.
96  *
97  *****************************************************************************/
98 typedef struct _CpaCyRsaPrivateKeyRep1 {
99     CpaFlatBuffer modulusN;
100     /**< The modulus (n). For key generation operations the memory MUST
101      * be allocated by the client and the value is generated. For other
102      * operations this is an input. Permitted lengths are:
103      *
104      * - 512 bits (64 bytes),
105      * - 1024 bits (128 bytes),
106      * - 1536 bits (192 bytes),
107      * - 2048 bits (256 bytes),
108      * - 3072 bits (384 bytes),
109      * - 4096 bits (512 bytes), or
110      * - 8192 bits (1024 bytes).
111      */
112     CpaFlatBuffer privateExponentD;
113     /**< The private exponent (d). For key generation operations the
114      * memory MUST be allocated by the client and the value is generated. For
115      * other operations this is an input.
116      * NOTE: It is important that the value D is big enough. It is STRONGLY
117      * recommended that this value is at least half the length of the modulus
118      * N to protect against the Wiener attack. */
119 } CpaCyRsaPrivateKeyRep1;
120 
121 /**
122  *****************************************************************************
123  * @ingroup cpaCyRsa
124  *      RSA Private Key Structure For Representation 2.
125  * @description
126  *      This structure contains the second representation that can be used for
127  *      describing the RSA private key. The quintuple of p, q, dP, dQ, and qInv
128  *      (explained below and in the spec) are required for the second
129  *      representation. The optional sequence of triplets are not included.
130  *      All values in this structure are required to be in Most Significant Byte
131  *      first order, e.g. prime1P.pData[0] = MSB.
132  *
133  *****************************************************************************/
134 typedef struct _CpaCyRsaPrivateKeyRep2 {
135     CpaFlatBuffer prime1P;
136     /**< The first large prime (p).
137      * For key generation operations, this field is unused. */
138     CpaFlatBuffer prime2Q;
139     /**< The second large prime (q).
140      * For key generation operations, this field is unused. */
141     CpaFlatBuffer exponent1Dp;
142     /**< The first factor CRT exponent (dP). d mod (p-1). */
143     CpaFlatBuffer exponent2Dq;
144     /**< The second factor CRT exponent (dQ). d mod (q-1). */
145     CpaFlatBuffer coefficientQInv;
146     /**< The (first) Chinese Remainder Theorem (CRT) coefficient (qInv).
147      * (inverse of q) mod p. */
148 } CpaCyRsaPrivateKeyRep2;
149 
150 /**
151  *****************************************************************************
152  * @ingroup cpaCyRsa
153  *      RSA private key representation type.
154  * @description
155  *      This enumeration lists which PKCS V2.1 representation of the private
156  *      key is being used.
157  *
158  *****************************************************************************/
159 typedef enum _CpaCyRsaPrivateKeyRepType
160 {
161     CPA_CY_RSA_PRIVATE_KEY_REP_TYPE_1= 1,
162     /**< The first representation of the RSA private key. */
163     CPA_CY_RSA_PRIVATE_KEY_REP_TYPE_2
164     /**< The second representation of the RSA private key. */
165 } CpaCyRsaPrivateKeyRepType;
166 
167 /**
168  *****************************************************************************
169  * @ingroup cpaCyRsa
170  *      RSA Private Key Structure.
171  * @description
172  *      This structure contains the two representations that can be used for
173  *      describing the RSA private key. The privateKeyRepType will be used to
174  *      identify which representation is to be used. Typically, using the
175  *      second representation results in faster decryption operations.
176  *
177  *****************************************************************************/
178 typedef struct _CpaCyRsaPrivateKey {
179     CpaCyRsaVersion version;
180     /**< Indicates the version of the PKCS #1 specification that is
181      * supported.
182      * Note that this applies to both representations. */
183     CpaCyRsaPrivateKeyRepType privateKeyRepType;
184     /**< This value is used to identify which of the private key
185      * representation types in this structure is relevant.
186      * When performing key generation operations for Type 2 representations,
187      * memory must also be allocated for the type 1 representations, and values
188      * for both will be returned. */
189     CpaCyRsaPrivateKeyRep1 privateKeyRep1;
190     /**< This is the first representation of the RSA private key as
191      * defined in the PKCS #1 V2.1 specification. For key generation operations
192      * the memory for this structure is allocated by the client and the
193      * specific values are generated. For other operations this is an input
194      * parameter. */
195     CpaCyRsaPrivateKeyRep2 privateKeyRep2;
196     /**< This is the second representation of the RSA private key as
197      * defined in the PKCS #1 V2.1 specification. For key generation operations
198      * the memory for this structure is allocated by the client and the
199      * specific values are generated. For other operations this is an input
200      * parameter. */
201 } CpaCyRsaPrivateKey;
202 
203 /**
204  *****************************************************************************
205  * @ingroup cpaCyRsa
206  *      RSA Key Generation Data.
207  * @description
208  *      This structure lists the different items that are required in the
209  *      cpaCyRsaGenKey function. The client MUST allocate the memory for this
210  *      structure. When the structure is passed into the function, ownership of
211  *      the memory passes to the function. Ownership of the memory returns to
212  *      the client when this structure is returned in the
213  *      CpaCyRsaKeyGenCbFunc callback function.
214  *
215  * @note
216  *      If the client modifies or frees the memory referenced in this structure
217  *      after it has been submitted to the cpaCyRsaGenKey function, and
218  *      before it has been returned in the callback, undefined behavior will
219  *      result.
220  *      All values in this structure are required to be in Most Significant Byte
221  *      first order, e.g. prime1P.pData[0] = MSB.
222  *
223  *      The following limitations on the permutations of the supported bit
224  *      lengths of p, q and n (written as {p, q, n}) apply:
225  *
226  *      - {256, 256, 512} or
227  *      - {512, 512, 1024} or
228  *      - {768, 768, 1536} or
229  *      - {1024, 1024, 2048} or
230  *      - {1536, 1536, 3072} or
231  *      - {2048, 2048, 4096}.
232  *
233  *****************************************************************************/
234 typedef struct _CpaCyRsaKeyGenOpData {
235     CpaFlatBuffer prime1P;
236     /**< A large random prime number (p). This MUST be created by the
237      * client. Permitted bit lengths are: 256, 512, 768, 1024, 1536 or 2048.
238      * Limitations apply - refer to the description above for details. */
239     CpaFlatBuffer prime2Q;
240     /**<  A large random prime number (q). This MUST be created by the
241      * client. Permitted bit lengths are: 256, 512, 768, 1024, 1536 or 2048.
242      * Limitations apply - refer to the description above for details. If the
243      * private key representation type is 2, then this pointer will be assigned
244      * to the relevant structure member of the representation 2 private key. */
245     Cpa32U modulusLenInBytes;
246     /**<  The bit length of the modulus (n). This is the modulus length for
247      * both the private and public keys. The length of the modulus N parameter
248      * for the private key representation 1 structure and the public key
249      * structures will be assigned to this value. References to the strength of
250      * RSA actually refer to this bit length. Recommended minimum is 1024 bits.
251      * Permitted lengths are:
252      * - 512 bits (64 bytes),
253      * - 1024 bits (128 bytes),
254      * - 1536 bits (192 bytes),
255      * - 2048 bits (256 bytes),
256      * - 3072 bits (384 bytes), or
257      * - 4096 bits (512 bytes).
258      * Limitations apply - refer to description above for details. */
259     CpaCyRsaVersion version;
260     /**< Indicates the version of the PKCS #1 specification that is
261      * supported.
262      * Note that this applies to both representations. */
263     CpaCyRsaPrivateKeyRepType privateKeyRepType;
264     /**< This value is used to identify which of the private key
265      * representation types is required to be generated. */
266     CpaFlatBuffer publicExponentE;
267     /**< The public exponent (e). */
268 } CpaCyRsaKeyGenOpData;
269 
270 /**
271  *****************************************************************************
272  * @ingroup cpaCyRsa
273  *      RSA Encryption Primitive Operation Data
274  * @description
275  *      This structure lists the different items that are required in the
276  *      cpaCyRsaEncrypt function.  As the RSA encryption primitive and
277  *      verification primitive operations are mathematically identical this
278  *      structure may also be used to perform an RSA verification primitive
279  *      operation.
280  *      When performing an RSA encryption primitive operation, the input data
281  *      is the message and the output data is the cipher text.
282  *      When performing an RSA verification primitive operation, the input data
283  *      is the signature and the output data is the message.
284  *      The client MUST allocate the memory for this structure. When the
285  *      structure is passed into the function, ownership of the memory passes
286  *      to the function. Ownership of the memory returns to the client when
287  *      this structure is returned in the CpaCyRsaEncryptCbFunc
288  *      callback function.
289  *
290  * @note
291  *      If the client modifies or frees the memory referenced in this structure
292  *      after it has been submitted to the cpaCyRsaEncrypt function, and
293  *      before it has been returned in the callback, undefined behavior will
294  *      result.
295  *      All values in this structure are required to be in Most Significant Byte
296  *      first order, e.g. inputData.pData[0] = MSB.
297  *
298  *****************************************************************************/
299 typedef struct _CpaCyRsaEncryptOpData {
300     CpaCyRsaPublicKey *pPublicKey;
301     /**< Pointer to the public key. */
302     CpaFlatBuffer inputData;
303     /**< The input data that the RSA encryption primitive operation is
304      * performed on. The data pointed to is an integer that MUST be in big-
305      * endian order. The value MUST be between 0 and the modulus n - 1. */
306 } CpaCyRsaEncryptOpData;
307 
308 /**
309  *****************************************************************************
310  * @ingroup cpaCyRsa
311  *      RSA Decryption Primitive Operation Data
312  * @description
313  *      This structure lists the different items that are required in the
314  *      cpaCyRsaDecrypt function.  As the RSA decryption primitive and
315  *      signature primitive operations are mathematically identical this
316  *      structure may also be used to perform an RSA signature primitive
317  *      operation.
318  *      When performing an RSA decryption primitive operation, the input data
319  *      is the cipher text and the output data is the message text.
320  *      When performing an RSA signature primitive operation, the input data
321  *      is the message and the output data is the signature.
322  *      The client MUST allocate the memory for this structure. When the
323  *      structure is passed into the function, ownership of the memory passes
324  *      to he function. Ownership of the memory returns to the client when
325  *      this structure is returned in the CpaCyRsaDecryptCbFunc
326  *      callback function.
327  *
328  * @note
329  *      If the client modifies or frees the memory referenced in this structure
330  *      after it has been submitted to the cpaCyRsaDecrypt function, and
331  *      before it has been returned in the callback, undefined behavior will
332  *      result.
333  *      All values in this structure are required to be in Most Significant Byte
334  *      first order, e.g. inputData.pData[0] = MSB.
335  *
336  *****************************************************************************/
337 typedef struct _CpaCyRsaDecryptOpData {
338     CpaCyRsaPrivateKey *pRecipientPrivateKey;
339     /**< Pointer to the recipient's RSA private key. */
340     CpaFlatBuffer inputData;
341     /**< The input data that the RSA decryption primitive operation is
342      * performed on. The data pointed to is an integer that MUST be in big-
343      * endian order. The value MUST be between 0 and the modulus n - 1. */
344 } CpaCyRsaDecryptOpData;
345 
346 /**
347  *****************************************************************************
348  * @ingroup cpaCyRsa
349  *      RSA Statistics.
350  * @deprecated
351  *      As of v1.3 of the Crypto API, this structure has been deprecated,
352  *      replaced by @ref CpaCyRsaStats64.
353  * @description
354  *      This structure contains statistics on the RSA operations.
355  *      Statistics are set to zero when the component is initialized, and are
356  *      collected per instance.
357  ****************************************************************************/
358 typedef struct _CpaCyRsaStats {
359     Cpa32U numRsaKeyGenRequests;
360     /**<  Total number of successful RSA key generation requests. */
361     Cpa32U numRsaKeyGenRequestErrors;
362     /**<  Total number of RSA key generation requests that had an error and
363      * could not be processed. */
364     Cpa32U numRsaKeyGenCompleted;
365     /**<  Total number of RSA key generation operations that completed
366      * successfully. */
367     Cpa32U numRsaKeyGenCompletedErrors;
368     /**<  Total number of RSA key generation operations that could not be
369      * completed successfully due to errors. */
370     Cpa32U numRsaEncryptRequests;
371     /**<  Total number of successful RSA encrypt operation requests. */
372     Cpa32U numRsaEncryptRequestErrors;
373     /**<  Total number of RSA encrypt requests that had an error and could
374      * not be processed. */
375     Cpa32U numRsaEncryptCompleted;
376     /**<  Total number of RSA encrypt operations that completed
377      * successfully. */
378     Cpa32U numRsaEncryptCompletedErrors;
379     /**<  Total number of RSA encrypt operations that could not be
380      * completed successfully due to errors. */
381     Cpa32U numRsaDecryptRequests;
382     /**<  Total number of successful RSA decrypt operation requests. */
383     Cpa32U numRsaDecryptRequestErrors;
384     /**<  Total number of RSA decrypt requests that had an error and could
385      * not be processed. */
386     Cpa32U numRsaDecryptCompleted;
387     /**<  Total number of RSA decrypt operations that completed
388      * successfully. */
389     Cpa32U numRsaDecryptCompletedErrors;
390     /**<  Total number of RSA decrypt operations that could not be
391      * completed successfully due to errors. */
392 } CpaCyRsaStats CPA_DEPRECATED;
393 
394 /**
395  *****************************************************************************
396  * @ingroup cpaCyRsa
397  *      RSA Statistics (64-bit version).
398  * @description
399  *      This structure contains 64-bit version of the statistics on the RSA
400  *      operations.
401  *      Statistics are set to zero when the component is initialized, and are
402  *      collected per instance.
403  ****************************************************************************/
404 typedef struct _CpaCyRsaStats64 {
405     Cpa64U numRsaKeyGenRequests;
406     /**<  Total number of successful RSA key generation requests. */
407     Cpa64U numRsaKeyGenRequestErrors;
408     /**<  Total number of RSA key generation requests that had an error and
409      * could not be processed. */
410     Cpa64U numRsaKeyGenCompleted;
411     /**<  Total number of RSA key generation operations that completed
412      * successfully. */
413     Cpa64U numRsaKeyGenCompletedErrors;
414     /**<  Total number of RSA key generation operations that could not be
415      * completed successfully due to errors. */
416     Cpa64U numRsaEncryptRequests;
417     /**<  Total number of successful RSA encrypt operation requests. */
418     Cpa64U numRsaEncryptRequestErrors;
419     /**<  Total number of RSA encrypt requests that had an error and could
420      * not be processed. */
421     Cpa64U numRsaEncryptCompleted;
422     /**<  Total number of RSA encrypt operations that completed
423      * successfully. */
424     Cpa64U numRsaEncryptCompletedErrors;
425     /**<  Total number of RSA encrypt operations that could not be
426      * completed successfully due to errors. */
427     Cpa64U numRsaDecryptRequests;
428     /**<  Total number of successful RSA decrypt operation requests. */
429     Cpa64U numRsaDecryptRequestErrors;
430     /**<  Total number of RSA decrypt requests that had an error and could
431      * not be processed. */
432     Cpa64U numRsaDecryptCompleted;
433     /**<  Total number of RSA decrypt operations that completed
434      * successfully. */
435     Cpa64U numRsaDecryptCompletedErrors;
436     /**<  Total number of RSA decrypt operations that could not be
437      * completed successfully due to errors. */
438     Cpa64U numKptRsaDecryptRequests;
439     /**<  Total number of successful KPT RSA decrypt operation requests. */
440     Cpa64U numKptRsaDecryptRequestErrors;
441     /**<  Total number of KPT RSA decrypt requests that had an error and could
442      * not be processed. */
443     Cpa64U numKptRsaDecryptCompleted;
444     /**<  Total number of KPT RSA decrypt operations that completed
445      * successfully. */
446     Cpa64U numKptRsaDecryptCompletedErrors;
447     /**<  Total number of KPT RSA decrypt operations that could not be
448      * completed successfully due to errors. */
449 } CpaCyRsaStats64;
450 
451 /**
452  *****************************************************************************
453  * @ingroup cpaCyRsa
454  *      Definition of the RSA key generation callback function.
455  *
456  * @description
457  *      This is the prototype for the RSA key generation callback function. The
458  *      callback function pointer is passed in as a parameter to the
459  *      cpaCyRsaGenKey function. It will be invoked once the request has
460  *      completed.
461  *
462  * @context
463  *      This callback function can be executed in a context that DOES NOT
464  *      permit sleeping to occur.
465  * @assumptions
466  *      None
467  * @sideEffects
468  *      None
469  * @reentrant
470  *      No
471  * @threadSafe
472  *      Yes
473  *
474  * @param[in] pCallbackTag    Opaque value provided by user while making
475  *                            individual function calls.
476  * @param[in] status          Status of the operation. Valid values are
477  *                            CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
478  *                            CPA_STATUS_UNSUPPORTED.
479  * @param[in] pKeyGenOpData   Structure with output params for callback.
480  * @param[in] pPrivateKey     Structure which contains pointers to the memory
481  *                            into which the generated private key will be
482  *                            written.
483  * @param[in] pPublicKey      Structure which contains pointers to the memory
484  *                            into which the generated public key will be
485  *                            written. The pointer to the public exponent (e)
486  *                            that is returned in this structure is equal to
487  *                            the input public exponent.
488  * @retval
489  *      None
490  * @pre
491  *      Component has been initialized.
492  * @post
493  *      None
494  * @note
495  *      None
496  * @see
497  *      CpaCyRsaPrivateKey,
498  *      CpaCyRsaPublicKey,
499  *      cpaCyRsaGenKey()
500  *
501  *****************************************************************************/
502 typedef void (*CpaCyRsaKeyGenCbFunc)(void *pCallbackTag,
503         CpaStatus status,
504         void *pKeyGenOpData,
505         CpaCyRsaPrivateKey *pPrivateKey,
506         CpaCyRsaPublicKey *pPublicKey);
507 
508 /**
509  *****************************************************************************
510  * @ingroup cpaCyRsa
511  *      Generate RSA keys.
512  *
513  * @description
514  *      This function will generate private and public keys for RSA as specified
515  *      in the PKCS #1 V2.1 standard. Both representation types of the private
516  *      key may be generated.
517  *
518  * @context
519  *      When called as an asynchronous function it cannot sleep. It can be
520  *      executed in a context that does not permit sleeping.
521  *      When called as a synchronous function it may sleep. It MUST NOT be
522  *      executed in a context that DOES NOT permit sleeping.
523  * @assumptions
524  *      None
525  * @sideEffects
526  *      None
527  * @blocking
528  *      Yes when configured to operate in synchronous mode.
529  * @reentrant
530  *      No
531  * @threadSafe
532  *      Yes
533  *
534  * @param[in]  instanceHandle    Instance handle.
535  * @param[in]  pRsaKeyGenCb      Pointer to the callback function to be invoked
536  *                               when the operation is complete. If this is
537  *                               set to a NULL value the function will operate
538  *                               synchronously.
539  * @param[in]  pCallbackTag      Opaque User Data for this specific call. Will
540  *                               be returned unchanged in the callback.
541  * @param[in]  pKeyGenOpData     Structure containing all the data needed to
542  *                               perform the RSA key generation operation. The
543  *                               client code allocates the memory for this
544  *                               structure. This component takes ownership of
545  *                               the memory until it is returned in the
546  *                               callback.
547  * @param[out] pPrivateKey       Structure which contains pointers to the memory
548  *                               into which the generated private key will be
549  *                               written.  The client MUST allocate memory
550  *                               for this structure, and for the pointers
551  *                               within it, recursively; on return, these will
552  *                               be populated.
553  * @param[out] pPublicKey        Structure which contains pointers to the memory
554  *                               into which the generated public key will be
555  *                               written.  The memory for this structure and
556  *                               for the modulusN parameter MUST be allocated
557  *                               by the client, and will be populated on return
558  *                               from the call.  The field publicExponentE
559  *                               is not modified or touched in any way; it is
560  *                               the responsibility of the client to set this
561  *                               to the same value as the corresponding
562  *                               parameter on the CpaCyRsaKeyGenOpData
563  *                               structure before using the key for encryption.
564  *
565  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
566  * @retval CPA_STATUS_FAIL           Function failed.
567  * @retval CPA_STATUS_RETRY          Resubmit the request.
568  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
569  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
570  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
571  *                                   the request.
572  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
573  *
574  * @pre
575  *      The component has been initialized via cpaCyStartInstance function.
576  * @post
577  *      None
578  * @note
579  *      When pRsaKeyGenCb is non-NULL, an asynchronous callback of type is
580  *      generated in response to this function call.
581  *      Any errors generated during processing are reported as part of the
582  *      callback status code. For optimal performance, data pointers SHOULD be
583  *      8-byte aligned.
584  * @see
585  *      CpaCyRsaKeyGenOpData,
586  *      CpaCyRsaKeyGenCbFunc,
587  *      cpaCyRsaEncrypt(),
588  *      cpaCyRsaDecrypt()
589  *
590  *****************************************************************************/
591 CpaStatus
592 cpaCyRsaGenKey(const CpaInstanceHandle instanceHandle,
593         const CpaCyRsaKeyGenCbFunc pRsaKeyGenCb,
594         void *pCallbackTag,
595         const CpaCyRsaKeyGenOpData *pKeyGenOpData,
596         CpaCyRsaPrivateKey *pPrivateKey,
597         CpaCyRsaPublicKey *pPublicKey);
598 
599 /**
600  *****************************************************************************
601  * @ingroup cpaCyRsa
602  *      Perform the RSA encrypt (or verify) primitive operation on the input
603  *      data.
604  *
605  * @description
606  *      This function will perform an RSA encryption primitive operation on the
607  *      input data using the specified RSA public key.  As the RSA encryption
608  *      primitive and verification primitive operations are mathematically
609  *      identical this function may also be used to perform an RSA verification
610  *      primitive operation.
611  *
612  * @context
613  *      When called as an asynchronous function it cannot sleep. It can be
614  *      executed in a context that does not permit sleeping.
615  *      When called as a synchronous function it may sleep. It MUST NOT be
616  *      executed in a context that DOES NOT permit sleeping.
617  * @assumptions
618  *      None
619  * @sideEffects
620  *      None
621  * @blocking
622  *      Yes when configured to operate in synchronous mode.
623  * @reentrant
624  *      No
625  * @threadSafe
626  *      Yes
627  *
628  * @param[in]  instanceHandle    Instance handle.
629  * @param[in]  pRsaEncryptCb     Pointer to callback function to be invoked
630  *                               when the operation is complete. If this is
631  *                               set to a NULL value the function will operate
632  *                               synchronously.
633  * @param[in]  pCallbackTag      Opaque User Data for this specific call. Will
634  *                               be returned unchanged in the callback.
635  * @param[in]  pEncryptOpData    Structure containing all the data needed to
636  *                               perform the RSA encryption operation. The
637  *                               client code allocates the memory for this
638  *                               structure. This component takes ownership of
639  *                               the memory until it is returned in the
640  *                               callback.
641  * @param[out] pOutputData       Pointer to structure into which the result of
642  *                               the RSA encryption primitive is written. The
643  *                               client MUST allocate this memory. The data
644  *                               pointed to is an integer in big-endian order.
645  *                               The value will be between 0 and the modulus
646  *                               n - 1.
647  *                               On invocation the callback function will
648  *                               contain this parameter in the pOut parameter.
649  *
650  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
651  * @retval CPA_STATUS_FAIL           Function failed.
652  * @retval CPA_STATUS_RETRY          Resubmit the request.
653  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
654  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
655  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
656  *                                   the request.
657  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
658  *
659  * @pre
660  *      The component has been initialized via cpaCyStartInstance function.
661  * @post
662  *      None
663  * @note
664  *      When pRsaEncryptCb is non-NULL an asynchronous callback of type is
665  *      generated in response to this function call.
666  *      Any errors generated during processing are reported as part of the
667  *      callback status code. For optimal performance, data pointers SHOULD be
668  *      8-byte aligned.
669  * @see
670  *      CpaCyGenFlatBufCbFunc
671  *      CpaCyRsaEncryptOpData
672  *      cpaCyRsaGenKey()
673  *      cpaCyRsaDecrypt()
674  *
675  *****************************************************************************/
676 CpaStatus
677 cpaCyRsaEncrypt(const CpaInstanceHandle instanceHandle,
678         const CpaCyGenFlatBufCbFunc pRsaEncryptCb,
679         void *pCallbackTag,
680         const CpaCyRsaEncryptOpData *pEncryptOpData,
681         CpaFlatBuffer *pOutputData);
682 
683 /**
684  *****************************************************************************
685  * @ingroup cpaCyRsa
686  *      Perform the RSA decrypt (or sign) primitive operation on the input
687  *      data.
688  *
689  * @description
690  *      This function will perform an RSA decryption primitive operation on the
691  *      input data using the specified RSA private key. As the RSA decryption
692  *      primitive and signing primitive operations are mathematically identical
693  *      this function may also be used to perform an RSA signing primitive
694  *      operation.
695  *
696  * @context
697  *      When called as an asynchronous function it cannot sleep. It can be
698  *      executed in a context that does not permit sleeping.
699  *      When called as a synchronous function it may sleep. It MUST NOT be
700  *      executed in a context that DOES NOT permit sleeping.
701  * @assumptions
702  *      None
703  * @sideEffects
704  *      None
705  * @blocking
706  *      Yes when configured to operate in synchronous mode.
707  * @reentrant
708  *      No
709  * @threadSafe
710  *      Yes
711  *
712  * @param[in]  instanceHandle   Instance handle.
713  * @param[in]  pRsaDecryptCb    Pointer to callback function to be invoked
714  *                              when the operation is complete. If this is
715  *                              set to a NULL value the function will operate
716  *                              synchronously.
717  * @param[in]  pCallbackTag     Opaque User Data for this specific call.
718  *                              Will be returned unchanged in the callback.
719  * @param[in]  pDecryptOpData   Structure containing all the data needed to
720  *                              perform the RSA decrypt operation. The
721  *                              client code allocates the memory for this
722  *                              structure. This component takes ownership
723  *                              of the memory until it is returned in the
724  *                              callback.
725  * @param[out] pOutputData      Pointer to structure into which the result of
726  *                              the RSA decryption primitive is written. The
727  *                              client MUST allocate this memory. The data
728  *                              pointed to is an integer in big-endian order.
729  *                              The value will be between 0 and the modulus
730  *                              n - 1.
731  *                              On invocation the callback function will
732  *                              contain this parameter in the pOut parameter.
733  *
734  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
735  * @retval CPA_STATUS_FAIL           Function failed.
736  * @retval CPA_STATUS_RETRY          Resubmit the request.
737  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
738  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
739  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
740  *                                   the request.
741  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
742  *
743  * @pre
744  *      The component has been initialized via cpaCyStartInstance function.
745  * @post
746  *      None
747  * @note
748  *      When pRsaDecryptCb is non-NULL an asynchronous callback is generated in
749  *      response to this function call.
750  *      Any errors generated during processing are reported as part of the
751  *      callback status code. For optimal performance, data pointers SHOULD be
752  *      8-byte aligned.
753  * @see
754  *      CpaCyRsaDecryptOpData,
755  *      CpaCyGenFlatBufCbFunc,
756  *      cpaCyRsaGenKey(),
757  *      cpaCyRsaEncrypt()
758  *
759  *****************************************************************************/
760 CpaStatus
761 cpaCyRsaDecrypt(const CpaInstanceHandle instanceHandle,
762         const CpaCyGenFlatBufCbFunc pRsaDecryptCb,
763         void *pCallbackTag,
764         const CpaCyRsaDecryptOpData *pDecryptOpData,
765         CpaFlatBuffer * pOutputData);
766 
767 /**
768  *****************************************************************************
769  * @ingroup cpaCyRsa
770  *      Query statistics for a specific RSA instance.
771  *
772  * @deprecated
773  *      As of v1.3 of the Crypto API, this function has been deprecated,
774  *      replaced by @ref cpaCyRsaQueryStats64().
775  *
776  * @description
777  *      This function will query a specific instance for RSA statistics. The
778  *      user MUST allocate the CpaCyRsaStats structure and pass the
779  *      reference to that into this function call. This function will write the
780  *      statistic results into the passed in CpaCyRsaStats structure.
781  *
782  *      Note: statistics returned by this function do not interrupt current data
783  *      processing and as such can be slightly out of sync with operations that
784  *      are in progress during the statistics retrieval process.
785  *
786  * @context
787  *      This is a synchronous function and it can sleep. It MUST NOT be
788  *      executed in a context that DOES NOT permit sleeping.
789  * @assumptions
790  *      None
791  * @sideEffects
792  *      None
793  * @blocking
794  *      This function is synchronous and blocking.
795  * @reentrant
796  *      No
797  * @threadSafe
798  *      Yes
799  *
800  * @param[in]  instanceHandle       Instance handle.
801  * @param[out] pRsaStats            Pointer to memory into which the statistics
802  *                                  will be written.
803  *
804  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
805  * @retval CPA_STATUS_FAIL           Function failed.
806  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
807  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
808  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
809  *                                   the request.
810  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
811  *
812  * @pre
813  *      Component has been initialized.
814  * @post
815  *      None
816  * @note
817  *      This function operates in a synchronous manner and no asynchronous
818  *      callback will be generated.
819  * @see
820  *      CpaCyRsaStats
821  *
822  *****************************************************************************/
823 CpaStatus CPA_DEPRECATED
824 cpaCyRsaQueryStats(const CpaInstanceHandle instanceHandle,
825         struct _CpaCyRsaStats *pRsaStats);
826 
827 /**
828  *****************************************************************************
829  * @ingroup cpaCyRsa
830  *      Query statistics (64-bit version) for a specific RSA instance.
831  *
832  * @description
833  *      This function will query a specific instance for RSA statistics. The
834  *      user MUST allocate the CpaCyRsaStats64 structure and pass the
835  *      reference to that into this function call. This function will write the
836  *      statistic results into the passed in CpaCyRsaStats64 structure.
837  *
838  *      Note: statistics returned by this function do not interrupt current data
839  *      processing and as such can be slightly out of sync with operations that
840  *      are in progress during the statistics retrieval process.
841  *
842  * @context
843  *      This is a synchronous function and it can sleep. It MUST NOT be
844  *      executed in a context that DOES NOT permit sleeping.
845  * @assumptions
846  *      None
847  * @sideEffects
848  *      None
849  * @blocking
850  *      This function is synchronous and blocking.
851  * @reentrant
852  *      No
853  * @threadSafe
854  *      Yes
855  *
856  * @param[in]  instanceHandle       Instance handle.
857  * @param[out] pRsaStats            Pointer to memory into which the statistics
858  *                                  will be written.
859  *
860  * @retval CPA_STATUS_SUCCESS        Function executed successfully.
861  * @retval CPA_STATUS_FAIL           Function failed.
862  * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
863  * @retval CPA_STATUS_RESOURCE       Error related to system resources.
864  * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
865  *                                   the request.
866  * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
867  *
868  * @pre
869  *      Component has been initialized.
870  * @post
871  *      None
872  * @note
873  *      This function operates in a synchronous manner and no asynchronous
874  *      callback will be generated.
875  * @see
876  *      CpaCyRsaStats64
877  *****************************************************************************/
878 CpaStatus
879 cpaCyRsaQueryStats64(const CpaInstanceHandle instanceHandle,
880         CpaCyRsaStats64 *pRsaStats);
881 
882 #ifdef __cplusplus
883 } /* close the extern "C" { */
884 #endif
885 
886 #endif /* CPA_CY_RSA_H */
887