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 *****************************************************************************/
62CpaStatus icp_sal_nrbgHealthTest(const CpaInstanceHandle instanceHandle,
63				 Cpa32U *pContinuousRngTestFailures);
64
65#endif
66