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