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