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