1 /*
2  * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 #ifndef _CC_RND_LOCAL_H
8 #define _CC_RND_LOCAL_H
9 
10 #ifdef __cplusplus
11 extern "C"
12 {
13 #endif
14 
15 
16 #include "cc_rnd_common.h"
17 #include "cc_pal_trng.h"
18 
19 /************************ Defines ****************************/
20 
21 
22 /*************************************************************/
23 /****** Common definitions for RND_DMA and non DMA     *******/
24 /*************************************************************/
25 
26 #define CC_RND_VECT_IN_RANGE_MAX_COUNT_OF_TRIES    100
27 
28 #define CC_RND_BASIC_BLOCK_SIZE_IN_WORDS 4
29 #define CC_RND_BASIC_BLOCK_SIZE_IN_BYTES (CC_RND_BASIC_BLOCK_SIZE_IN_WORDS*sizeof(uint32_t))
30 #define CC_RND_ENTROPY_BLOCK_SIZE_IN_WORDS 4
31 #define CC_RND_ENTROPY_BLOCK_SIZE_IN_BYTES (CC_RND_ENTROPY_BLOCK_SIZE_IN_WORDS*sizeof(uint32_t))
32 
33 /* Bit-fields of Instantiation steps in the StateFlag:
34     - b'0: 0 - not instantiated, 1 - instantiated normally;
35     - b'1: 1 - loss samples, 0 - no loss;
36     - b'2: 1 - time exceeding, 0 - no time exceeding.
37     In case of sample loss or time exceed b`0 must be 0 */
38 #define CC_RND_NOT_INSTANTIATED                 0UL
39 #define CC_RND_INSTANTIATED                 1UL
40 #define CC_RND_INSTANTRESEED_AUTOCORR_ERRORS    2UL
41 #define CC_RND_INSTANTRESEED_TIME_EXCEED        4UL
42 #define CC_RND_INSTANTRESEED_LESS_ENTROPY       8UL
43 
44 /* The 2-bit field in the StateFlag, defining the working or KAT modes:
45      - b`9,8: 0 - working mode, 1 - KAT DRBG mode, 2 - KAT TRNG mode, 3 - KAT
46        DRBG or/and TRNG mode */
47 #define CC_RND_WORK_Mode                  (0UL << 8)
48 #define CC_RND_KAT_DRBG_Mode              (1UL << 8)
49 #define CC_RND_KAT_TRNG_Mode              (2UL << 8)
50 #define CC_RND_KAT_Mode               CC_RND_KAT_DRBG_Mode
51 
52 /* The bit-field in the StateFlag, defining that the previous generated random
53    block is valid for comparison with current block or not */
54 #define CC_RND_PreviousIsValid          (1UL << 16)
55 
56 /* RND WorkBuffer = ESTIM_BUFF || ENTROPY_SOURCE_BUFF. Size of buffer = 1KB = *
57 *  1024 words.  Max size (in words) of internal buffers:              */
58 #define CC_RND_FULL_ENTROPY_SOURCE_BUFF_SIZE_WORDS 504
59 #define CC_RND_ESTIM_BUFF_SIZE_WORDS           386 /*256+128+2*/
60 #define CC_RND_ENTROPY_SOURCE_BUFF_SIZE_WORDS     1024/*2+504+504+12+1+padding */
61 /* Offsets of buffers used in KAT mode */
62 #define CC_RND_WORK_BUFF_TMP1_OFFSET  (CC_RND_ESTIM_BUFF_SIZE_WORDS + CC_RND_ENTROPY_SOURCE_BUFF_SIZE_WORDS + 4)
63 #define CC_RND_WORK_BUFF_TMP2_OFFSET  (CC_RND_WORK_BUFF_TMP1_OFFSET + CC_RND_SEED_MAX_SIZE_WORDS + 4)
64 
65 /* max size of KAT entropy and nonce data in words on SWEE and FE modes*/
66 #define CC_RND_ENTROPY_TEMP_BUFFER_MAX_SIZE_WORDS  126
67 
68 #define CC_RND_SRC_BUFF_OFFSET_WORDS  0
69 
70 
71 /* Offsets (in words) of RND estimator buffer members inside the buffer */
72 #define CC_RND_H_BUFF_OFFSET   0
73 #define CC_RND_EC_BUFF_OFFSET  256
74 
75 /* Validation tag for random working state: should be set by:             *
76    RndInstantiateOrReseed function on not continued mode or by           *
77 *  LLF_RND_StartTrngHW function on continued mode                     */
78 #define CC_RND_WORK_STATE_VALID_TAG  0X0123ABCD
79 
80 /*Values for entropy flag*/
81 #define LLF_RNG_ENTROPY_FLAG_REQUIRED   0x0
82 #define LLF_RNG_ENTROPY_FLAG_LOW        0x1
83 #define LLF_RNG_ENTROPY_FLAG_NULL       0x2
84 #define LLF_RNG_ENTROPY_FLAG_KAT_MODE   0x3
85 
86 #define LLF_RNG_MAX_COLLECTION_ITERATION_SIZE 0x5
87 
88 #define LLF_RND_MAX_NUM_OF_ROSCS 0x4
89 /************************ Enums ********************************/
90 
91 
92 /************************ Structs  ******************************/
93 
94 /* The CC Random Generator Parameters  structure CCRndParams_t -
95    structure containing the user given Parameters */
96 typedef struct  CCRndParams_t
97 {
98     CC_PalTrngParams_t  userParams;
99 
100     /* parameters defining TRNG */
101     CCRndMode_t TrngMode;
102 
103     /* allowed ring oscillator lengths: bits 0,1,2,3  */
104     uint32_t  RoscsAllowed;
105 
106     /* sampling interval: count of ring oscillator cycles between
107        consecutive bits sampling */
108     uint32_t  SubSamplingRatio;
109 
110 }CCRndParams_t;
111 
112 
113 /************************ Typedefs  ****************************/
114 
115 /************************ Public Variables **********************/
116 
117 /************************ Public Functions **********************/
118 
119 /**********************************************************************************************************/
120 /*!
121 @brief Generates a random vector with specific limitations by testing candidates (described and used in FIPS Publication 186-4: Digital
122 Signature Standard (DSS): B.1.2, B.4.2 etc.).
123 
124 This function draws a random vector, compare it to the range limits, and if within range - return it in rndVect_ptr.
125 If outside the range, the function continues retrying until a conforming vector is found, or the maximal retries limit is exceeded.
126 If maxVect_ptr is provided, rndSizeInBits specifies its size, and the output vector must conform to the range [1 < rndVect < maxVect_ptr].
127 If maxVect_ptr is NULL, rndSizeInBits specifies the exact required vector size, and the output vector must be the exact same
128 bit size (with its most significant bit = 1).
129 \note The RND module must be instantiated prior to invocation of this API.
130 
131 @return CC_OK on success.
132 @return A non-zero value from cc_rnd_error.h on failure.
133 */
134 CIMPORT_C CCError_t CC_RndGenerateVectorInRange(
135                     CCRndContext_t *rndContext_ptr,     /*!< [in/out] Pointer to the RND context buffer. */
136                     size_t   rndSizeInBits,                 /*!< [in]  The size in bits of the random vector required. The allowed size in range  2 <= rndSizeInBits < 2^19-1, bits. */
137                     uint8_t  *maxVect_ptr,                  /*!< [in]  Pointer to the vector defining the upper limit for the random vector output, Given as little-endian byte array.
138                                                                        If not NULL, its actual size is treated as [(rndSizeInBits+7)/8] bytes. */
139                     uint8_t  *rndVect_ptr                   /*!< [in/out] Pointer to the output buffer for the random vector. Must be at least [(rndSizeInBits+7)/8] bytes.
140                                                                  Treated as little-endian byte array. */
141 );
142 
143 #ifdef __cplusplus
144 }
145 #endif
146 
147 #endif
148 
149 
150