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_ln.h 12 * 13 * @defgroup cpaCyLn Cryptographic Large Number API 14 * 15 * @ingroup cpaCy 16 * 17 * @description 18 * These functions specify the Cryptographic API for Large Number 19 * Operations. 20 * 21 * @note 22 * Large numbers are represented on the QuickAssist API using octet 23 * strings, stored in structures of type @ref CpaFlatBuffer. These 24 * octet strings are encoded as described by PKCS#1 v2.1, section 4, 25 * which is consistent with ASN.1 syntax. The following text 26 * summarizes this. Any exceptions to this encoding are specified 27 * on the specific data structure or function to which the exception 28 * applies. 29 * 30 * An n-bit number, N, has a value in the range 2^(n-1) through 2^(n)-1. 31 * In other words, its most significant bit, bit n-1 (where bit-counting 32 * starts from zero) MUST be set to 1. We can also state that the 33 * bit-length n of a number N is defined by n = floor(log2(N))+1. 34 * 35 * The buffer, b, in which an n-bit number N is stored, must be "large 36 * enough". In other words, b.dataLenInBytes must be at least 37 * minLenInBytes = ceiling(n/8). 38 * 39 * The number is stored in a "big endian" format. This means that the 40 * least significant byte (LSB) is b[b.dataLenInBytes-1], while the 41 * most significant byte (MSB) is b[b.dataLenInBytes-minLenInBytes]. 42 * In the case where the buffer is "exactly" the right size, then the 43 * MSB is b[0]. Otherwise, all bytes from b[0] up to the MSB MUST be 44 * set to 0x00. 45 * 46 * The largest bit-length we support today is 8192 bits. In other 47 * words, we can deal with numbers up to a value of (2^8192)-1. 48 * 49 *****************************************************************************/ 50 51 #ifndef CPA_CY_LN_H 52 #define CPA_CY_LN_H 53 54 #ifdef __cplusplus 55 extern "C" { 56 #endif 57 58 #include "cpa_cy_common.h" 59 60 /** 61 ***************************************************************************** 62 * @ingroup cpaCyLn 63 * Modular Exponentiation Function Operation Data. 64 * @description 65 * This structure lists the different items that are required in the 66 * cpaCyLnModExp function. The client MUST allocate the memory for 67 * this structure. When the structure is passed into the function, 68 * ownership of the memory passes to the function. Ownership of the memory 69 * returns to the client when this structure is returned in the callback. 70 * The operation size in bits is equal to the size of whichever of the 71 * following is largest: the modulus, the base or the exponent. 72 * 73 * @note 74 * If the client modifies or frees the memory referenced in this structure 75 * after it has been submitted to the cpaCyLnModExp function, and 76 * before it has been returned in the callback, undefined behavior will 77 * result. 78 79 * The values of the base, the exponent and the modulus MUST all be less 80 * than 2^8192, and the modulus must not be equal to zero. 81 *****************************************************************************/ 82 typedef struct _CpaCyLnModExpOpData { 83 CpaFlatBuffer modulus; 84 /**< Flat buffer containing a pointer to the modulus. 85 * This number may be up to 8192 bits in length, and MUST be greater 86 * than zero. 87 */ 88 CpaFlatBuffer base; 89 /**< Flat buffer containing a pointer to the base. 90 * This number may be up to 8192 bits in length. 91 */ 92 CpaFlatBuffer exponent; 93 /**< Flat buffer containing a pointer to the exponent. 94 * This number may be up to 8192 bits in length. 95 */ 96 } CpaCyLnModExpOpData; 97 98 /** 99 ***************************************************************************** 100 * @ingroup cpaCyLn 101 * Modular Inversion Function Operation Data. 102 * @description 103 * This structure lists the different items that are required in the 104 * function @ref cpaCyLnModInv. The client MUST allocate the memory for 105 * this structure. When the structure is passed into the function, 106 * ownership of the memory passes to the function. Ownership of the 107 * memory returns to the client when this structure is returned in the 108 * callback. 109 * @note 110 * If the client modifies or frees the memory referenced in this structure 111 * after it has been submitted to the cpaCyLnModInv function, and 112 * before it has been returned in the callback, undefined behavior will 113 * result. 114 * 115 * Note that the values of A and B MUST NOT both be even numbers, and 116 * both MUST be less than 2^8192. 117 *****************************************************************************/ 118 typedef struct _CpaCyLnModInvOpData { 119 CpaFlatBuffer A; 120 /**< Flat buffer containing a pointer to the value that will be 121 * inverted. 122 * This number may be up to 8192 bits in length, it MUST NOT be zero, 123 * and it MUST be co-prime with B. 124 */ 125 CpaFlatBuffer B; 126 /**< Flat buffer containing a pointer to the value that will be used as 127 * the modulus. 128 * This number may be up to 8192 bits in length, it MUST NOT be zero, 129 * and it MUST be co-prime with A. 130 */ 131 } CpaCyLnModInvOpData; 132 133 /** 134 ***************************************************************************** 135 * @ingroup cpaCyLn 136 * Look Aside Cryptographic large number Statistics. 137 * @deprecated 138 * As of v1.3 of the Crypto API, this structure has been deprecated, 139 * replaced by @ref CpaCyLnStats64. 140 * @description 141 * This structure contains statistics on the Look Aside Cryptographic 142 * large number operations. Statistics are set to zero when the component 143 * is initialized, and are collected per instance. 144 * 145 ****************************************************************************/ 146 typedef struct _CpaCyLnStats { 147 Cpa32U numLnModExpRequests; 148 /**< Total number of successful large number modular exponentiation 149 * requests.*/ 150 Cpa32U numLnModExpRequestErrors; 151 /**< Total number of large number modular exponentiation requests that 152 * had an error and could not be processed. */ 153 Cpa32U numLnModExpCompleted; 154 /**< Total number of large number modular exponentiation operations 155 * that completed successfully. */ 156 Cpa32U numLnModExpCompletedErrors; 157 /**< Total number of large number modular exponentiation operations 158 * that could not be completed successfully due to errors. */ 159 Cpa32U numLnModInvRequests; 160 /**< Total number of successful large number modular inversion 161 * requests.*/ 162 Cpa32U numLnModInvRequestErrors; 163 /**< Total number of large number modular inversion requests that 164 * had an error and could not be processed. */ 165 Cpa32U numLnModInvCompleted; 166 /**< Total number of large number modular inversion operations 167 * that completed successfully. */ 168 Cpa32U numLnModInvCompletedErrors; 169 /**< Total number of large number modular inversion operations 170 * that could not be completed successfully due to errors. */ 171 } CpaCyLnStats CPA_DEPRECATED; 172 173 /** 174 ***************************************************************************** 175 * @ingroup cpaCyLn 176 * Look Aside Cryptographic large number Statistics. 177 * @description 178 * This structure contains statistics on the Look Aside Cryptographic 179 * large number operations. Statistics are set to zero when the component 180 * is initialized, and are collected per instance. 181 * 182 ****************************************************************************/ 183 typedef struct _CpaCyLnStats64 { 184 Cpa64U numLnModExpRequests; 185 /**< Total number of successful large number modular exponentiation 186 * requests.*/ 187 Cpa64U numLnModExpRequestErrors; 188 /**< Total number of large number modular exponentiation requests that 189 * had an error and could not be processed. */ 190 Cpa64U numLnModExpCompleted; 191 /**< Total number of large number modular exponentiation operations 192 * that completed successfully. */ 193 Cpa64U numLnModExpCompletedErrors; 194 /**< Total number of large number modular exponentiation operations 195 * that could not be completed successfully due to errors. */ 196 Cpa64U numLnModInvRequests; 197 /**< Total number of successful large number modular inversion 198 * requests.*/ 199 Cpa64U numLnModInvRequestErrors; 200 /**< Total number of large number modular inversion requests that 201 * had an error and could not be processed. */ 202 Cpa64U numLnModInvCompleted; 203 /**< Total number of large number modular inversion operations 204 * that completed successfully. */ 205 Cpa64U numLnModInvCompletedErrors; 206 /**< Total number of large number modular inversion operations 207 * that could not be completed successfully due to errors. */ 208 } CpaCyLnStats64; 209 210 /** 211 ***************************************************************************** 212 * @ingroup cpaCyLn 213 * Perform modular exponentiation operation. 214 * 215 * @description 216 * This function performs modular exponentiation. It computes the 217 * following result based on the inputs: 218 * 219 * result = (base ^ exponent) mod modulus 220 * 221 * @context 222 * When called as an asynchronous function it cannot sleep. It can be 223 * executed in a context that does not permit sleeping. 224 * When called as a synchronous function it may sleep. It MUST NOT be 225 * executed in a context that DOES NOT permit sleeping. 226 * @assumptions 227 * None 228 * @sideEffects 229 * None 230 * @reentrant 231 * No 232 * @threadSafe 233 * Yes 234 * 235 * @param[in] instanceHandle Instance handle. 236 * @param[in] pLnModExpCb Pointer to callback function to be 237 * invoked when the operation is complete. 238 * @param[in] pCallbackTag Opaque User Data for this specific call. 239 * Will be returned unchanged in the callback. 240 * @param[in] pLnModExpOpData Structure containing all the data needed 241 * to perform the LN modular exponentiation 242 * operation. The client code allocates 243 * the memory for this structure. This 244 * component takes ownership of the memory 245 * until it is returned in the callback. 246 * @param[out] pResult Pointer to a flat buffer containing a 247 * pointer to memory allocated by the client 248 * into which the result will be written. 249 * The size of the memory required MUST be 250 * larger than or equal to the size 251 * required to store the modulus. 252 * On invocation the callback function 253 * will contain this parameter in the 254 * pOut parameter. 255 * 256 * @retval CPA_STATUS_SUCCESS Function executed successfully. 257 * @retval CPA_STATUS_FAIL Function failed. 258 * @retval CPA_STATUS_RETRY Resubmit the request. 259 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 260 * @retval CPA_STATUS_RESOURCE Error related to system resources. 261 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 262 * the request. 263 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 264 * 265 * @pre 266 * The component has been initialized. 267 * @post 268 * None 269 * @note 270 * When pLnModExpCb is non null, an asynchronous callback of type 271 * CpaCyLnModExpCbFunc is generated in response to this function call. 272 * Any errors generated during processing are reported in the structure 273 * returned in the callback. 274 * 275 * @see 276 * CpaCyLnModExpOpData, CpaCyGenFlatBufCbFunc 277 * 278 *****************************************************************************/ 279 CpaStatus 280 cpaCyLnModExp(const CpaInstanceHandle instanceHandle, 281 const CpaCyGenFlatBufCbFunc pLnModExpCb, 282 void *pCallbackTag, 283 const CpaCyLnModExpOpData *pLnModExpOpData, 284 CpaFlatBuffer *pResult); 285 286 /** 287 ***************************************************************************** 288 * @ingroup cpaCyLn 289 * Perform modular inversion operation. 290 * 291 * @description 292 * This function performs modular inversion. It computes the following 293 * result based on the inputs: 294 * 295 * result = (1/A) mod B. 296 * 297 * @context 298 * When called as an asynchronous function it cannot sleep. It can be 299 * executed in a context that does not permit sleeping. 300 * When called as a synchronous function it may sleep. It MUST NOT be 301 * executed in a context that DOES NOT permit sleeping. 302 * @assumptions 303 * None 304 * @sideEffects 305 * None 306 * @reentrant 307 * No 308 * @threadSafe 309 * Yes 310 * 311 * @param[in] instanceHandle Instance handle. 312 * @param[in] pLnModInvCb Pointer to callback function to be 313 * invoked when the operation is complete. 314 * @param[in] pCallbackTag Opaque User Data for this specific call. 315 * Will be returned unchanged in the 316 * callback. 317 * @param[in] pLnModInvOpData Structure containing all the data 318 * needed to perform the LN modular 319 * inversion operation. The client code 320 * allocates the memory for this structure. 321 * This component takes ownership of the 322 * memory until it is returned in the 323 * callback. 324 * @param[out] pResult Pointer to a flat buffer containing a 325 * pointer to memory allocated by the client 326 * into which the result will be written. 327 * The size of the memory required MUST be 328 * larger than or equal to the size 329 * required to store the modulus. 330 * On invocation the callback function 331 * will contain this parameter in the 332 * pOut parameter. 333 * 334 * @retval CPA_STATUS_SUCCESS Function executed successfully. 335 * @retval CPA_STATUS_FAIL Function failed. 336 * @retval CPA_STATUS_RETRY Resubmit the request. 337 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 338 * @retval CPA_STATUS_RESOURCE Error related to system resources. 339 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 340 * the request. 341 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 342 * 343 * @pre 344 * The component has been initialized. 345 * @post 346 * None 347 * @note 348 * When pLnModInvCb is non null, an asynchronous callback of type 349 * CpaCyLnModInvCbFunc is generated in response to this function call. 350 * Any errors generated during processing are reported in the structure 351 * returned in the callback. 352 * 353 * @see 354 * CpaCyLnModInvOpData, 355 * CpaCyGenFlatBufCbFunc 356 * 357 *****************************************************************************/ 358 CpaStatus 359 cpaCyLnModInv(const CpaInstanceHandle instanceHandle, 360 const CpaCyGenFlatBufCbFunc pLnModInvCb, 361 void *pCallbackTag, 362 const CpaCyLnModInvOpData *pLnModInvOpData, 363 CpaFlatBuffer *pResult); 364 365 /** 366 ***************************************************************************** 367 * @ingroup cpaCyLn 368 * Query statistics for large number operations 369 * 370 * @deprecated 371 * As of v1.3 of the Crypto API, this function has been deprecated, 372 * replaced by @ref cpaCyLnStatsQuery64(). 373 * 374 * @description 375 * This function will query a specific instance handle for large number 376 * statistics. The user MUST allocate the CpaCyLnStats structure and pass 377 * the reference to that structure into this function call. This function 378 * writes the statistic results into the passed in CpaCyLnStats structure. 379 * 380 * Note: statistics returned by this function do not interrupt current data 381 * processing and as such can be slightly out of sync with operations that 382 * are in progress during the statistics retrieval process. 383 * 384 * @context 385 * This is a synchronous function and it can sleep. It MUST NOT be 386 * executed in a context that DOES NOT permit sleeping. 387 * @assumptions 388 * None 389 * @sideEffects 390 * None 391 * @reentrant 392 * No 393 * @threadSafe 394 * Yes 395 * 396 * @param[in] instanceHandle Instance handle. 397 * @param[out] pLnStats Pointer to memory into which the 398 * statistics will be written. 399 * 400 * @retval CPA_STATUS_SUCCESS Function executed successfully. 401 * @retval CPA_STATUS_FAIL Function failed. 402 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 403 * @retval CPA_STATUS_RESOURCE Error related to system resources. 404 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 405 * the request. 406 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 407 * 408 * @pre 409 * Acceleration Services unit has been initialized. 410 * 411 * @post 412 * None 413 * @note 414 * This function operates in a synchronous manner and no asynchronous 415 * callback will be generated. 416 * 417 * @see 418 * CpaCyLnStats 419 * 420 *****************************************************************************/ 421 CpaStatus CPA_DEPRECATED 422 cpaCyLnStatsQuery(const CpaInstanceHandle instanceHandle, 423 struct _CpaCyLnStats *pLnStats); 424 425 /** 426 ***************************************************************************** 427 * @ingroup cpaCyLn 428 * Query statistics (64-bit version) for large number operations 429 * 430 * @description 431 * This function will query a specific instance handle for the 64-bit 432 * version of the large number statistics. 433 * The user MUST allocate the CpaCyLnStats64 structure and pass 434 * the reference to that structure into this function call. This function 435 * writes the statistic results into the passed in CpaCyLnStats64 436 * structure. 437 * 438 * Note: statistics returned by this function do not interrupt current data 439 * processing and as such can be slightly out of sync with operations that 440 * are in progress during the statistics retrieval process. 441 * 442 * @context 443 * This is a synchronous function and it can sleep. It MUST NOT be 444 * executed in a context that DOES NOT permit sleeping. 445 * @assumptions 446 * None 447 * @sideEffects 448 * None 449 * @reentrant 450 * No 451 * @threadSafe 452 * Yes 453 * 454 * @param[in] instanceHandle Instance handle. 455 * @param[out] pLnStats Pointer to memory into which the 456 * statistics will be written. 457 * 458 * @retval CPA_STATUS_SUCCESS Function executed successfully. 459 * @retval CPA_STATUS_FAIL Function failed. 460 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 461 * @retval CPA_STATUS_RESOURCE Error related to system resources. 462 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 463 * the request. 464 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 465 * 466 * @pre 467 * Acceleration Services unit has been initialized. 468 * 469 * @post 470 * None 471 * @note 472 * This function operates in a synchronous manner and no asynchronous 473 * callback will be generated. 474 * 475 * @see 476 * CpaCyLnStats 477 *****************************************************************************/ 478 CpaStatus 479 cpaCyLnStatsQuery64(const CpaInstanceHandle instanceHandle, 480 CpaCyLnStats64 *pLnStats); 481 482 #ifdef __cplusplus 483 } /* close the extern "C" { */ 484 #endif 485 486 #endif /* CPA_CY_LN_H */ 487