1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /* Copyright(c) 2007-2022 Intel Corporation */
3 /**
4  *****************************************************************************
5  * @file icp_sal_nrbg_ht.h
6  *
7  * @ingroup LacSym
8  *
9  * @description
10  *      This file contains declaration of function used to test the health
11  *      of NRBG entropy source.
12  *
13  *****************************************************************************/
14 #ifndef ICP_SAL_NRBG_HT_H
15 #define ICP_SAL_NRBG_HT_H
16 
17 /**
18  ******************************************************************************
19  * @ingroup LacSym
20  *      NRBG Health Test
21  *
22  * @description
23  *      This function performs a check on the deterministic parts of the
24  *      NRBG. It also provides the caller the value of continuous random
25  *      number generator test failures for n=64 bits, refer to FIPS 140-2
26  *      section 4.9.2 for details. A non-zero value for the counter does
27  *      not necessarily indicate a failure; it is statistically possible
28  *      that consecutive blocks of 64 bits will be identical, and the RNG
29  *      will discard the identical block in such cases. This counter allows
30  *      the calling application to monitor changes in this counter and to
31  *      use this to decide whether to mark the NRBG as faulty, based on
32  *      local policy or statistical model.
33  *
34  * @context
35  *      MUST NOT be executed in a context that DOES NOT permit sleeping.
36  * @assumptions
37  *      None
38  * @sideEffects
39  *      None
40  * @blocking
41  *      Yes.
42  * @reentrant
43  *      No
44  * @threadSafe
45  *      Yes
46  *
47  * @param[in] instanceHandle               Instance handle.
48  * @param[out] pContinuousRngTestFailures  Number of continuous random number
49  *                                         generator test failures.
50  *
51  * @retval CPA_STATUS_SUCCESS              Health test passed.
52  * @retval CPA_STATUS_FAIL                 Health test failed.
53  * @retval CPA_STATUS_RETRY                Resubmit the request.
54  * @retval CPA_STATUS_INVALID_PARAM        Invalid parameter passed in.
55  * @retval CPA_STATUS_RESOURCE             Error related to system resources.
56  *
57  * @note
58  *      The return value of this function is not impacted by the value
59  *      of continuous random generator test failures.
60  *
61  *****************************************************************************/
62 CpaStatus icp_sal_nrbgHealthTest(const CpaInstanceHandle instanceHandle,
63 				 Cpa32U *pContinuousRngTestFailures);
64 
65 #endif
66