1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
|
/* SPDX-License-Identifier: BSD-3-Clause */
/* Copyright(c) 2007-2025 Intel Corporation */
/*
*****************************************************************************
* Doxygen group definitions
****************************************************************************/
/**
*****************************************************************************
* @file cpa_cy_dh.h
*
* @defgroup cpaCyDh Diffie-Hellman (DH) API
*
* @ingroup cpaCy
*
* @description
* These functions specify the API for Public Key Encryption
* (Cryptography) operations for use with Diffie-Hellman algorithm.
*
* @note
* Large numbers are represented on the QuickAssist API as described
* in the Large Number API (@ref cpaCyLn).
*****************************************************************************/
#ifndef CPA_CY_DH_H
#define CPA_CY_DH_H
#ifdef __cplusplus
extern "C" {
#endif
#include "cpa_cy_common.h"
/**
*****************************************************************************
* @ingroup cpaCyDh
* Diffie-Hellman Phase 1 Key Generation Data.
* @description
* This structure lists the different items that are required in the
* cpaCyDhKeyGenPhase1 function. The client MUST allocate the memory for
* this structure. When the structure is passed into the function,
* ownership of the memory passes to the function. Ownership of the memory
* returns to the client when this structure is returned with the
* CpaCyDhPhase1KeyGenOpData structure.
*
* @note
* If the client modifies or frees the memory referenced in this structure
* after it has been submitted to the cpaCyDhKeyGenPhase1 function, and
* before it has been returned in the callback, undefined behavior will
* result.
* All values in this structure are required to be in Most Significant Byte
* first order, e.g. primeP.pData[0] = MSB.
*
*****************************************************************************/
typedef struct _CpaCyDhPhase1KeyGenOpData {
CpaFlatBuffer primeP;
/**< Flat buffer containing a pointer to the random odd prime number (p).
* The bit-length of this number may be one of 768, 1024, 1536, 2048,
* 3072, 4096 or 8192.
*/
CpaFlatBuffer baseG;
/**< Flat buffer containing a pointer to base (g). This MUST comply with
* the following:
* 0 < g < p.
*/
CpaFlatBuffer privateValueX;
/**< Flat buffer containing a pointer to the private value (x). This is a
* random value which MUST satisfy the following condition:
* 0 < PrivateValueX < (PrimeP - 1)
*
* Refer to PKCS #3: Diffie-Hellman Key-Agreement Standard for details.
* The client creating this data MUST ensure the compliance of this value
* with the standard. Note: This value is also needed to complete local
* phase 2 Diffie-Hellman operation.*/
} CpaCyDhPhase1KeyGenOpData;
/**
*****************************************************************************
* @ingroup cpaCyDh
* Diffie-Hellman Phase 2 Secret Key Generation Data.
* @description
* This structure lists the different items that required in the
* cpaCyDhKeyGenPhase2Secret function. The client MUST allocate the
* memory for this structure. When the structure is passed into the
* function, ownership of the memory passes to the function. Ownership of
* the memory returns to the client when this structure is returned with
* the callback.
* @note
* If the client modifies or frees the memory referenced in this structure
* after it has been submitted to the cpaCyDhKeyGenPhase2Secret
* function, and before it has been returned in the callback, undefined
* behavior will result.
* All values in this structure are required to be in Most Significant Byte
* first order, e.g. primeP.pData[0] = MSB.
*
*****************************************************************************/
typedef struct _CpaCyDhPhase2SecretKeyGenOpData {
CpaFlatBuffer primeP;
/**< Flat buffer containing a pointer to the random odd prime number (p).
* The bit-length of this number may be one of 768, 1024, 1536, 2048,
* 3072, 4096 or 8192.
* This SHOULD be same prime number as was used in the phase 1 key
* generation operation. */
CpaFlatBuffer remoteOctetStringPV;
/**< Flat buffer containing a pointer to the remote entity
* octet string Public Value (PV). */
CpaFlatBuffer privateValueX;
/**< Flat buffer containing a pointer to the private value (x). This
* value may have been used in a call to the cpaCyDhKeyGenPhase1 function.
* This is a random value which MUST satisfy the following condition:
* 0 < privateValueX < (primeP - 1). */
} CpaCyDhPhase2SecretKeyGenOpData;
/**
*****************************************************************************
* @ingroup cpaCyDh
* Diffie-Hellman Statistics.
* @deprecated
* As of v1.3 of the Crypto API, this structure has been deprecated,
* replaced by @ref CpaCyDhStats64.
* @description
* This structure contains statistics on the Diffie-Hellman operations.
* Statistics are set to zero when the component is initialized, and are
* collected per instance.
****************************************************************************/
typedef struct _CpaCyDhStats {
Cpa32U numDhPhase1KeyGenRequests;
/**< Total number of successful Diffie-Hellman phase 1 key
* generation requests. */
Cpa32U numDhPhase1KeyGenRequestErrors;
/**< Total number of Diffie-Hellman phase 1 key generation requests
* that had an error and could not be processed. */
Cpa32U numDhPhase1KeyGenCompleted;
/**< Total number of Diffie-Hellman phase 1 key generation operations
* that completed successfully. */
Cpa32U numDhPhase1KeyGenCompletedErrors;
/**< Total number of Diffie-Hellman phase 1 key generation operations
* that could not be completed successfully due to errors. */
Cpa32U numDhPhase2KeyGenRequests;
/**< Total number of successful Diffie-Hellman phase 2 key
* generation requests. */
Cpa32U numDhPhase2KeyGenRequestErrors;
/**< Total number of Diffie-Hellman phase 2 key generation requests
* that had an error and could not be processed. */
Cpa32U numDhPhase2KeyGenCompleted;
/**< Total number of Diffie-Hellman phase 2 key generation operations
* that completed successfully. */
Cpa32U numDhPhase2KeyGenCompletedErrors;
/**< Total number of Diffie-Hellman phase 2 key generation operations
* that could not be completed successfully due to errors. */
} CpaCyDhStats CPA_DEPRECATED;
/**
*****************************************************************************
* @ingroup cpaCyDh
* Diffie-Hellman Statistics (64-bit version).
* @description
* This structure contains the 64-bit version of the statistics on the
* Diffie-Hellman operations.
* Statistics are set to zero when the component is initialized, and are
* collected per instance.
****************************************************************************/
typedef struct _CpaCyDhStats64 {
Cpa64U numDhPhase1KeyGenRequests;
/**< Total number of successful Diffie-Hellman phase 1 key
* generation requests. */
Cpa64U numDhPhase1KeyGenRequestErrors;
/**< Total number of Diffie-Hellman phase 1 key generation requests
* that had an error and could not be processed. */
Cpa64U numDhPhase1KeyGenCompleted;
/**< Total number of Diffie-Hellman phase 1 key generation operations
* that completed successfully. */
Cpa64U numDhPhase1KeyGenCompletedErrors;
/**< Total number of Diffie-Hellman phase 1 key generation operations
* that could not be completed successfully due to errors. */
Cpa64U numDhPhase2KeyGenRequests;
/**< Total number of successful Diffie-Hellman phase 2 key
* generation requests. */
Cpa64U numDhPhase2KeyGenRequestErrors;
/**< Total number of Diffie-Hellman phase 2 key generation requests
* that had an error and could not be processed. */
Cpa64U numDhPhase2KeyGenCompleted;
/**< Total number of Diffie-Hellman phase 2 key generation operations
* that completed successfully. */
Cpa64U numDhPhase2KeyGenCompletedErrors;
/**< Total number of Diffie-Hellman phase 2 key generation operations
* that could not be completed successfully due to errors. */
} CpaCyDhStats64;
/**
*****************************************************************************
* @ingroup cpaCyDh
* Function to implement Diffie-Hellman phase 1 operations.
*
* @description
* This function may be used to implement the Diffie-Hellman phase 1
* operations as defined in the PKCS #3 standard. It may be used to
* generate the (local) octet string public value (PV) key.
* The prime number sizes specified in RFC 2409, 4306, and part of
* RFC 3526 are supported (bit size 6144 from RFC 3536 is not
* supported).
*
* @context
* When called as an asynchronous function it cannot sleep. It can be
* executed in a context that does not permit sleeping.
* When called as a synchronous function it may sleep. It MUST NOT be
* executed in a context that DOES NOT permit sleeping.
* @assumptions
* None
* @sideEffects
* None
* @blocking
* Yes when configured to operate in synchronous mode.
* @reentrant
* No
* @threadSafe
* Yes
*
* @param[in] instanceHandle Instance handle.
* @param[in] pDhPhase1Cb Pointer to a callback function to be invoked
* when the operation is complete. If the
* pointer is set to a NULL value the function
* will operate synchronously.
* @param[in] pCallbackTag Opaque User Data for this specific call.
* Will be returned unchanged in the callback
* @param[in] pPhase1KeyGenData Structure containing all the data needed
* to perform the DH Phase 1 key generation
* operation. The client code allocates the
* memory for this structure. This component
* takes ownership of the memory until it is
* returned in the callback.
* @param[out] pLocalOctetStringPV Pointer to memory allocated by the client
* into which the (local) octet string Public
* Value (PV) will be written. This value
* needs to be sent to the remote entity with
* which Diffie-Hellman is negotiating.
* The size of this buffer in bytes (as
* represented by the dataLenInBytes field)
* MUST be at least big enough to store
* the public value, which may have a bit
* length up to that of pPrimeP.
* On invocation the callback function
* will contain this parameter in the
* pOut parameter.
*
* @retval CPA_STATUS_SUCCESS Function executed successfully.
* @retval CPA_STATUS_FAIL Function failed.
* @retval CPA_STATUS_RETRY Resubmit the request.
* @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
* @retval CPA_STATUS_RESOURCE Error related to system resources.
* @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit
* the request.
* @retval CPA_STATUS_UNSUPPORTED Function is not supported.
*
* @pre
* The component has been initialized via cpaCyStartInstance function.
* @post
* None
* @note
* When pDhPhase1Cb is non-NULL an asynchronous callback of type
* CpaCyGenFlatBufCbFunc is generated in response to this function
* call. Any errors generated during processing are reported in the
* structure returned in the callback.
*
* @see
* CpaCyGenFlatBufCbFunc,
* CpaCyDhPhase1KeyGenOpData
*
*****************************************************************************/
CpaStatus
cpaCyDhKeyGenPhase1(const CpaInstanceHandle instanceHandle,
const CpaCyGenFlatBufCbFunc pDhPhase1Cb,
void *pCallbackTag,
const CpaCyDhPhase1KeyGenOpData *pPhase1KeyGenData,
CpaFlatBuffer *pLocalOctetStringPV);
/**
*****************************************************************************
* @ingroup cpaCyDh
* Function to implement Diffie-Hellman phase 2 operations.
*
* @description
* This function may be used to implement the Diffie-Hellman phase 2
* operation as defined in the PKCS #3 standard. It may be used to
* generate the Diffie-Hellman shared secret key.
*
* @context
* When called as an asynchronous function it cannot sleep. It can be
* executed in a context that does not permit sleeping.
* When called as a synchronous function it may sleep. It MUST NOT be
* executed in a context that DOES NOT permit sleeping.
* @assumptions
* None
* @sideEffects
* None
* @blocking
* Yes when configured to operate in synchronous mode.
* @reentrant
* No
* @threadSafe
* Yes
*
* @param[in] instanceHandle Instance handle.
* @param[in] pDhPhase2Cb Pointer to a callback function to be
* invoked when the operation is complete.
* If the pointer is set to a NULL value
* the function will operate synchronously.
* @param[in] pCallbackTag Opaque User Data for this specific
* call. Will be returned unchanged in
* the callback.
* @param[in] pPhase2SecretKeyGenData Structure containing all the data
* needed to perform the DH Phase 2
* secret key generation operation. The
* client code allocates the memory for
* this structure. This component takes
* ownership of the memory until it is
* returned in the callback.
* @param[out] pOctetStringSecretKey Pointer to memory allocated by the
* client into which the octet string
* secret key will be written.
* The size of this buffer in bytes (as
* represented by the dataLenInBytes field)
* MUST be at least big enough to store
* the public value, which may have a bit
* length up to that of pPrimeP.
* On invocation the callback function
* will contain this parameter in the
* pOut parameter.
*
* @retval CPA_STATUS_SUCCESS Function executed successfully.
* @retval CPA_STATUS_FAIL Function failed.
* @retval CPA_STATUS_RETRY Resubmit the request.
* @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
* @retval CPA_STATUS_RESOURCE Error related to system resources.
* @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit
* the request.
* @retval CPA_STATUS_UNSUPPORTED Function is not supported.
*
* @pre
* The component has been initialized via cpaCyStartInstance function.
* @post
* None
* @note
* When pDhPhase2Cb is non-NULL an asynchronous callback of type
* CpaCyGenFlatBufCbFunc is generated in response to this function
* call. Any errors generated during processing are reported in the
* structure returned in the callback.
*
* @see
* CpaCyGenFlatBufCbFunc,
* CpaCyDhPhase2SecretKeyGenOpData
*
*****************************************************************************/
CpaStatus
cpaCyDhKeyGenPhase2Secret(const CpaInstanceHandle instanceHandle,
const CpaCyGenFlatBufCbFunc pDhPhase2Cb,
void *pCallbackTag,
const CpaCyDhPhase2SecretKeyGenOpData *pPhase2SecretKeyGenData,
CpaFlatBuffer *pOctetStringSecretKey);
/**
*****************************************************************************
* @ingroup cpaCyDh
* Query statistics for Diffie-Hellman operations
*
* @deprecated
* As of v1.3 of the Crypto API, this function has been deprecated,
* replaced by @ref cpaCyDhQueryStats64().
*
* @description
* This function will query a specific Instance handle for Diffie-
* Hellman statistics. The user MUST allocate the CpaCyDhStats
* structure and pass the reference to that structure into this function
* call. This function writes the statistic results into the passed in
* CpaCyDhStats structure.
*
* Note: statistics returned by this function do not interrupt current data
* processing and as such can be slightly out of sync with operations that
* are in progress during the statistics retrieval process.
*
* @context
* This is a synchronous function and it can sleep. It MUST NOT be
* executed in a context that DOES NOT permit sleeping.
* @assumptions
* None
* @sideEffects
* None
* @reentrant
* No
* @threadSafe
* Yes
*
* @param[in] instanceHandle Instance handle.
* @param[out] pDhStats Pointer to memory into which the statistics
* will be written.
*
* @retval CPA_STATUS_SUCCESS Function executed successfully.
* @retval CPA_STATUS_FAIL Function failed.
* @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
* @retval CPA_STATUS_RESOURCE Error related to system resources.
* @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit
* the request.
* @retval CPA_STATUS_UNSUPPORTED Function is not supported.
*
* @pre
* Component has been initialized.
*
* @post
* None
* @note
* This function operates in a synchronous manner and no asynchronous
* callback will be generated.
* @see
* CpaCyDhStats
*****************************************************************************/
CpaStatus CPA_DEPRECATED
cpaCyDhQueryStats(const CpaInstanceHandle instanceHandle,
struct _CpaCyDhStats *pDhStats);
/**
*****************************************************************************
* @ingroup cpaCyDh
* Query statistics (64-bit version) for Diffie-Hellman operations
*
* @description
* This function will query a specific Instance handle for the 64-bit
* version of the Diffie-Hellman statistics. The user MUST allocate the
* CpaCyDhStats64 structure and pass the reference to that structure into
* this function call. This function writes the statistic results into
* the passed in CpaCyDhStats64 structure.
*
* Note: statistics returned by this function do not interrupt current data
* processing and as such can be slightly out of sync with operations that
* are in progress during the statistics retrieval process.
*
* @context
* This is a synchronous function and it can sleep. It MUST NOT be
* executed in a context that DOES NOT permit sleeping.
* @assumptions
* None
* @sideEffects
* None
* @reentrant
* No
* @threadSafe
* Yes
*
* @param[in] instanceHandle Instance handle.
* @param[out] pDhStats Pointer to memory into which the statistics
* will be written.
*
* @retval CPA_STATUS_SUCCESS Function executed successfully.
* @retval CPA_STATUS_FAIL Function failed.
* @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
* @retval CPA_STATUS_RESOURCE Error related to system resources.
* @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit
* the request.
* @retval CPA_STATUS_UNSUPPORTED Function is not supported.
*
* @pre
* Component has been initialized.
*
* @post
* None
* @note
* This function operates in a synchronous manner and no asynchronous
* callback will be generated.
* @see
* CpaCyDhStats64
*****************************************************************************/
CpaStatus
cpaCyDhQueryStats64(const CpaInstanceHandle instanceHandle,
CpaCyDhStats64 *pDhStats);
/*****************************************************************************/
#ifdef __cplusplus
} /* close the extern "C" { */
#endif
#endif /* CPA_CY_DH_H */
|
