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_prime.h 45 * 46 * @defgroup cpaCyPrime Prime Number Test API 47 * 48 * @ingroup cpaCy 49 * 50 * @description 51 * These functions specify the API for the prime number test operations. 52 * 53 * For prime number generation, this API SHOULD be used in conjunction 54 * with the Deterministic Random Bit Generation API (@ref cpaCyDrbg). 55 * 56 * @note 57 * Large numbers are represented on the QuickAssist API as described 58 * in the Large Number API (@ref cpaCyLn). 59 * 60 * In addition, the bit length of large numbers passed to the API 61 * MUST NOT exceed 576 bits for Elliptic Curve operations. 62 *****************************************************************************/ 63 64 #ifndef CPA_CY_PRIME_H 65 #define CPA_CY_PRIME_H 66 67 #ifdef __cplusplus 68 extern "C" { 69 #endif 70 71 #include "cpa_cy_common.h" 72 73 /** 74 ***************************************************************************** 75 * @ingroup cpaCyPrime 76 * Prime Test Operation Data. 77 * @description 78 * This structure contains the operation data for the cpaCyPrimeTest 79 * function. The client MUST allocate the memory for this structure and the 80 * items pointed to by this structure. When the structure is passed into 81 * the function, ownership of the memory passes to the function. Ownership 82 * of the memory returns to the client when this structure is returned in 83 * the callback function. 84 * 85 * All values in this structure are required to be in Most Significant Byte 86 * first order, e.g. primeCandidate.pData[0] = MSB. 87 * 88 * All numbers MUST be stored in big-endian order. 89 * 90 * @note 91 * If the client modifies or frees the memory referenced in this 92 * structure after it has been submitted to the cpaCyPrimeTest 93 * function, and before it has been returned in the callback, undefined 94 * behavior will result. 95 * 96 * @see 97 * cpaCyPrimeTest() 98 * 99 *****************************************************************************/ 100 typedef struct _CpaCyPrimeTestOpData { 101 CpaFlatBuffer primeCandidate; 102 /**< The prime number candidate to test */ 103 CpaBoolean performGcdTest; 104 /**< A value of CPA_TRUE means perform a GCD Primality Test */ 105 CpaBoolean performFermatTest; 106 /**< A value of CPA_TRUE means perform a Fermat Primality Test */ 107 Cpa32U numMillerRabinRounds; 108 /**< Number of Miller Rabin Primality Test rounds. Set to 0 to perform 109 * zero Miller Rabin tests. The maximum number of rounds supported is 50. 110 */ 111 CpaFlatBuffer millerRabinRandomInput; 112 /**< Flat buffer containing a pointer to an array of n random numbers 113 * for Miller Rabin Primality Tests. The size of the buffer MUST be 114 * 115 * n * (MAX(64,x)) 116 * 117 * where: 118 * 119 * - n is the requested number of rounds. 120 * - x is the minimum number of bytes required to represent the prime 121 * candidate, i.e. x = ceiling((ceiling(log2(p)))/8). 122 * 123 * Each random number MUST be greater than 1 and less than the prime 124 * candidate - 1, with leading zeroes as necessary. 125 */ 126 CpaBoolean performLucasTest; 127 /**< An CPA_TRUE value means perform a Lucas Primality Test */ 128 } CpaCyPrimeTestOpData; 129 130 /** 131 ***************************************************************************** 132 * @ingroup cpaCyPrime 133 * Prime Number Test Statistics. 134 * @deprecated 135 * As of v1.3 of the Crypto API, this structure has been deprecated, 136 * replaced by @ref CpaCyPrimeStats64. 137 * @description 138 * This structure contains statistics on the prime number test operations. 139 * Statistics are set to zero when the component is initialized, and are 140 * collected per instance. 141 * 142 ****************************************************************************/ 143 typedef struct _CpaCyPrimeStats { 144 Cpa32U numPrimeTestRequests; 145 /**< Total number of successful prime number test requests.*/ 146 Cpa32U numPrimeTestRequestErrors; 147 /**< Total number of prime number test requests that had an 148 * error and could not be processed. */ 149 Cpa32U numPrimeTestCompleted; 150 /**< Total number of prime number test operations that completed 151 * successfully. */ 152 Cpa32U numPrimeTestCompletedErrors; 153 /**< Total number of prime number test operations that could not be 154 * completed successfully due to errors. */ 155 Cpa32U numPrimeTestFailures; 156 /**< Total number of prime number test operations that executed 157 * successfully but the outcome of the test was that the number was not 158 * prime. */ 159 } CpaCyPrimeStats CPA_DEPRECATED; 160 161 /** 162 ***************************************************************************** 163 * @ingroup cpaCyPrime 164 * Prime Number Test Statistics (64-bit version). 165 * @description 166 * This structure contains a 64-bit version of the statistics on the 167 * prime number test operations. 168 * Statistics are set to zero when the component is initialized, and are 169 * collected per instance. 170 ****************************************************************************/ 171 typedef struct _CpaCyPrimeStats64 { 172 Cpa64U numPrimeTestRequests; 173 /**< Total number of successful prime number test requests.*/ 174 Cpa64U numPrimeTestRequestErrors; 175 /**< Total number of prime number test requests that had an 176 * error and could not be processed. */ 177 Cpa64U numPrimeTestCompleted; 178 /**< Total number of prime number test operations that completed 179 * successfully. */ 180 Cpa64U numPrimeTestCompletedErrors; 181 /**< Total number of prime number test operations that could not be 182 * completed successfully due to errors. */ 183 Cpa64U numPrimeTestFailures; 184 /**< Total number of prime number test operations that executed 185 * successfully but the outcome of the test was that the number was not 186 * prime. */ 187 } CpaCyPrimeStats64; 188 189 /** 190 ***************************************************************************** 191 * @ingroup cpaCyPrime 192 * Definition of callback function invoked for cpaCyPrimeTest 193 * requests. 194 * 195 * @description 196 * This is the prototype for the cpaCyPrimeTest callback function. 197 * 198 * @context 199 * This callback function can be executed in a context that DOES NOT 200 * permit sleeping to occur. 201 * @assumptions 202 * None 203 * @sideEffects 204 * None 205 * @reentrant 206 * No 207 * @threadSafe 208 * Yes 209 * 210 * @param[in] pCallbackTag User-supplied value to help identify request. 211 * @param[in] status Status of the operation. Valid values are 212 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 213 * CPA_STATUS_UNSUPPORTED. 214 * @param[in] pOpData Opaque pointer to the Operation data pointer 215 * supplied in request. 216 * @param[in] testPassed A value of CPA_TRUE means the prime candidate 217 * is probably prime. 218 * 219 * @retval 220 * None 221 * @pre 222 * Component has been initialized. 223 * @post 224 * None 225 * @note 226 * None 227 * @see 228 * cpaCyPrimeTest() 229 * 230 *****************************************************************************/ 231 typedef void (*CpaCyPrimeTestCbFunc)(void *pCallbackTag, 232 CpaStatus status, 233 void *pOpData, 234 CpaBoolean testPassed); 235 236 /** 237 ***************************************************************************** 238 * @ingroup cpaCyPrime 239 * Prime Number Test Function. 240 * 241 * @description 242 * This function will test probabilistically if a number is prime. Refer 243 * to ANSI X9.80 2005 for details. The primality result will be returned 244 * in the asynchronous callback. 245 * 246 * The following combination of GCD, Fermat, Miller-Rabin, and Lucas 247 * testing is supported: 248 * (up to 1x GCD) + (up to 1x Fermat) + (up to 50x Miller-Rabin rounds) + 249 * (up to 1x Lucas) 250 * For example: 251 * (1x GCD) + (25x Miller-Rabin) + (1x Lucas); 252 * (1x GCD) + (1x Fermat); 253 * (50x Miller-rabin); 254 * 255 * Tests are always performed in order of increasing complexity, for 256 * example GCD first, then Fermat, then Miller-Rabin, and finally Lucas. 257 * 258 * For all of the primality tests, the following prime number "sizes" 259 * (length in bits) are supported: all sizes up to and including 512 260 * bits, as well as sizes 768, 1024, 1536, 2048, 3072 and 4096. 261 * 262 * Candidate prime numbers MUST match these sizes accordingly, with 263 * leading zeroes present where necessary. 264 * 265 * When this prime number test is used in conjunction with combined 266 * Miller-Rabin and Lucas tests, it may be used as a means of performing 267 * a self test operation on the random data generator. 268 * 269 * A response status of ok (pass == CPA_TRUE) means all requested 270 * primality tests passed, and the prime candidate is probably prime 271 * (the exact probability depends on the primality tests requested). 272 * A response status of not ok (pass == CPA_FALSE) means one of the 273 * requested primality tests failed (the prime candidate has been found 274 * to be composite). 275 * @context 276 * When called as an asynchronous function it cannot sleep. It can be 277 * executed in a context that does not permit sleeping. 278 * When called as a synchronous function it may sleep. It MUST NOT be 279 * executed in a context that DOES NOT permit sleeping. 280 * @assumptions 281 * None 282 * @sideEffects 283 * None 284 * @blocking 285 * Yes when configured to operate in synchronous mode. 286 * @reentrant 287 * No 288 * @threadSafe 289 * Yes 290 * 291 * @param[in] instanceHandle Instance handle. 292 * @param[in] pCb Callback function pointer. If this is set to 293 * a NULL value the function will operate 294 * synchronously. 295 * @param[in] pCallbackTag User-supplied value to help identify request. 296 * @param[in] pOpData Structure containing all the data needed to 297 * perform the operation. The client code 298 * allocates the memory for this structure. This 299 * component takes ownership of the memory until 300 * it is returned in the callback. 301 * @param[out] pTestPassed A value of CPA_TRUE means the prime candidate 302 * is probably prime. 303 * 304 * @retval CPA_STATUS_SUCCESS Function executed successfully. 305 * @retval CPA_STATUS_FAIL Function failed. 306 * @retval CPA_STATUS_RETRY Resubmit the request. 307 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 308 * @retval CPA_STATUS_RESOURCE Error related to system resources. 309 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 310 * the request. 311 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 312 * 313 * @pre 314 * The component has been initialized via cpaCyStartInstance function. 315 * @post 316 * None 317 * @note 318 * When pCb is non-NULL an asynchronous callback of type 319 * CpaCyPrimeTestCbFunc is generated in response to this function call. 320 * For optimal performance, data pointers SHOULD be 8-byte aligned. 321 * 322 * @see 323 * CpaCyPrimeTestOpData, CpaCyPrimeTestCbFunc 324 * 325 *****************************************************************************/ 326 CpaStatus 327 cpaCyPrimeTest(const CpaInstanceHandle instanceHandle, 328 const CpaCyPrimeTestCbFunc pCb, 329 void *pCallbackTag, 330 const CpaCyPrimeTestOpData *pOpData, 331 CpaBoolean *pTestPassed); 332 333 /****************************************************************************** 334 * @ingroup cpaCyPrime 335 * Query prime number statistics specific to an instance. 336 * 337 * @deprecated 338 * As of v1.3 of the Crypto API, this function has been deprecated, 339 * replaced by @ref cpaCyPrimeQueryStats64(). 340 * 341 * @description 342 * This function will query a specific instance for prime number 343 * statistics. The user MUST allocate the CpaCyPrimeStats structure 344 * and pass the reference to that into this function call. This function 345 * will write the statistic results into the passed in 346 * CpaCyPrimeStats structure. 347 * 348 * Note: statistics returned by this function do not interrupt current data 349 * processing and as such can be slightly out of sync with operations that 350 * are in progress during the statistics retrieval process. 351 * 352 * @context 353 * This is a synchronous function and it can sleep. It MUST NOT be 354 * executed in a context that DOES NOT permit sleeping. 355 * @assumptions 356 * None 357 * @sideEffects 358 * None 359 * @blocking 360 * This function is synchronous and blocking. 361 * @reentrant 362 * No 363 * @threadSafe 364 * Yes 365 * 366 * @param[in] instanceHandle Instance handle. 367 * @param[out] pPrimeStats Pointer to memory into which the statistics 368 * will be written. 369 * 370 * @retval CPA_STATUS_SUCCESS Function executed successfully. 371 * @retval CPA_STATUS_FAIL Function failed. 372 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 373 * @retval CPA_STATUS_RESOURCE Error related to system resources. 374 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 375 * the request. 376 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 377 * 378 * @pre 379 * Component has been initialized. 380 * @post 381 * None 382 * @note 383 * This function operates in a synchronous manner and no asynchronous 384 * callback will be generated. 385 * 386 *****************************************************************************/ 387 CpaStatus CPA_DEPRECATED 388 cpaCyPrimeQueryStats(const CpaInstanceHandle instanceHandle, 389 struct _CpaCyPrimeStats *pPrimeStats); 390 391 392 /****************************************************************************** 393 * @ingroup cpaCyPrime 394 * Query prime number statistics specific to an instance. 395 * 396 * @description 397 * This function will query a specific instance for the 64-bit 398 * version of the prime number statistics. 399 * The user MUST allocate the CpaCyPrimeStats64 structure 400 * and pass the reference to that into this function call. This function 401 * will write the statistic results into the passed in 402 * CpaCyPrimeStats64 structure. 403 * 404 * Note: statistics returned by this function do not interrupt current data 405 * processing and as such can be slightly out of sync with operations that 406 * are in progress during the statistics retrieval process. 407 * 408 * @context 409 * This is a synchronous function and it can sleep. It MUST NOT be 410 * executed in a context that DOES NOT permit sleeping. 411 * @assumptions 412 * None 413 * @sideEffects 414 * None 415 * @blocking 416 * This function is synchronous and blocking. 417 * @reentrant 418 * No 419 * @threadSafe 420 * Yes 421 * 422 * @param[in] instanceHandle Instance handle. 423 * @param[out] pPrimeStats Pointer to memory into which the statistics 424 * will be written. 425 * 426 * @retval CPA_STATUS_SUCCESS Function executed successfully. 427 * @retval CPA_STATUS_FAIL Function failed. 428 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 429 * @retval CPA_STATUS_RESOURCE Error related to system resources. 430 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 431 * the request. 432 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 433 * 434 * @pre 435 * Component has been initialized. 436 * @post 437 * None 438 * @note 439 * This function operates in a synchronous manner and no asynchronous 440 * callback will be generated. 441 *****************************************************************************/ 442 CpaStatus 443 cpaCyPrimeQueryStats64(const CpaInstanceHandle instanceHandle, 444 CpaCyPrimeStats64 *pPrimeStats); 445 446 #ifdef __cplusplus 447 } /* close the extern "C" { */ 448 #endif 449 450 #endif /* CPA_CY_PRIME_H */ 451