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 LLF_RND_H 8 #define LLF_RND_H 9 10 #include "cc_rnd_local.h" 11 12 #ifdef __cplusplus 13 extern "C" 14 { 15 #endif 16 17 18 19 /************************ Defines ******************************/ 20 21 /* Definitions describing the TRNG Entropy estimator parameters: 22 width of bits prefix and correlation table size */ 23 #define CC_RND_nb 8 24 #define CC_RND_NB (1 << CC_RND_nb) 25 #define H_BUFF_SIZE_WORDS CC_RND_NB 26 #define EC_BUFF_SIZE_WORDS (CC_RND_NB/2) 27 28 29 /* macro for calculation max. allowed time for */ 30 #define LLF_RND_CalcMaxTrngTime(ehrSamples, SubSamplingRatio) \ 31 (((ehrSamples) * LLF_RND_TRNG_MAX_TIME_COEFF * \ 32 LLF_RND_TRNG_VON_NEUMAN_COEFF * \ 33 LLF_RND_HW_TRNG_EHR_WIDTH_IN_BITS * \ 34 (SubSamplingRatio)) >> LLF_RND_TRNG_MAX_TIME_SCALE) 35 36 /* Macro defining Multiplication using 16x16 multiplier */ 37 #define Mult16x16(a, b) (((a)&0xffff)*((b)&0xffff)) 38 uint64_t Mult32x32(uint32_t a, uint32_t b); 39 uint64_t Mult48x16(uint64_t a, uint32_t b); 40 41 42 /************************ Enums ********************************/ 43 /************************ Typedefs ****************************/ 44 /************************ Structs *****************************/ 45 /* structure containing parameters and buffers for entropy estimator */ 46 typedef struct 47 { 48 /* estimated entropy size */ 49 uint32_t EstimEntropySizeBits; 50 /* estimated error of entropy size */ 51 uint32_t EstimEntropySizeErrorInBits; 52 53 /* special buffers */ 54 uint32_t h[CC_RND_NB]; /* histogram */ 55 uint32_t ec[CC_RND_NB/2]; /* equality counter for prefix */ 56 57 }LLF_rnd_entr_estim_db_t; 58 59 /******************** Public Functions *************************/ 60 61 /** 62 * @brief The LLF_RND_GetRngBytes returns size of random source needed for collection 63 * required entropy . 64 * 65 * The function returns size of source needed for required entropy. 66 * 67 * @param[in/out] trngParams - The pointer to structure, containing TRNG parameters. 68 * @entropySizeWords[in/out] - The pointer to size of random source. The user sets 69 * size of entropy that is required and the function returns 70 * the actual size of source needed for this count of entropy. 71 * 72 * @return CCError_t - On success CC_OK is returned, on failure a 73 * value MODULE_* as defined in ... 74 */ 75 CCError_t LLF_RND_GetEntropySourceSize( 76 CCRndParams_t *trngParams, /*in*/ 77 uint16_t *entropySizeWords_ptr); /*in/out*/ 78 79 80 /****************************************************************************************/ 81 /** 82 * @brief The function gets user provided parameters of RNG HW. 83 * 84 * This implementation is in user competence. Temporary a pseudo function 85 * is implemented for testing goals. To use this implementation the user must define 86 * compilation flag "CC_RND_TEST_MODE", otherwise 87 * 88 * Note: In temporary implementation assumed, that users parameters are placed 89 * in global structure UserRngParameters (now placed in ATP tests). 90 * 91 * @param[in] KeySizeWords - The key size: 4 or 8 words according to security 92 * strength 128 bits or 256 bits; 93 * @param[in] TrngMode - TRNG mode: 0 - SWEE mode, 1 - FE mode. 94 * @param[in] RoscsAllowed - Ring oscillator length level: should be set 95 * as 2 bits value: 0,1,2,3. 96 * @param[in] SampleCount - The sampling count - count of RND blocks of RNG HW 97 * output, required for needed entropy accumulation: 98 * - in "fe" mode a possible values are 4095 to 65535, in steps of 4096; 99 * - in "swee" mode, sampling counter limit is set to a low value - 100 * typically 1 or 2. 101 * @param[in] MaxTrngTimeCoeff - coefficient defining relation between maximal allowed and expected 102 * time for random generation (in percents). 103 * 104 * @return CCError_t - CC_OK 105 */ 106 CCError_t LLF_RND_GetRngParams( 107 uint32_t *KeySizeWords, 108 uint32_t *TrngMode, 109 uint32_t *RoscsAllowed, 110 uint32_t *SampleCount, 111 uint32_t *MaxTrngTimeCoeff); 112 113 114 /************************************************************************************/ 115 /** 116 * @brief The LLF_RND_TurnOffTrng stops the hardware random bits collection 117 * closes RND clocks and releases HW semaphore. 118 * 119 * 120 * 121 * @return CCError_t - On success CC_OK is returned, on failure a 122 * value MODULE_* as defined in ... 123 */ 124 void LLF_RND_TurnOffTrng(void); 125 126 127 CCError_t LLF_RND_GetFastestRosc( 128 CCRndParams_t *trngParams_ptr, 129 uint32_t *rosc_ptr /*in/out*/); 130 131 CCError_t LLF_RND_GetRoscSampleCnt( 132 uint32_t rosc, 133 CCRndParams_t *pTrngParams); 134 135 CCError_t LLF_RND_WaitRngInterrupt(uint32_t *isr_ptr); 136 137 uint32_t LLF_RND_GetCountRoscs( 138 uint32_t roscsAllowed, 139 uint32_t roscToStart); 140 141 void LLF_RND_TurnOffTrng(void); 142 143 CCError_t LLF_RND_EntropyEstimateFull( 144 uint32_t *ramAddr, /*in*/ 145 uint32_t blockSizeWords, /*in*/ 146 uint32_t countBlocks, /*in*/ 147 uint32_t *entrSize_ptr, /*out*/ 148 uint32_t *rndWorkBuff_ptr); /*in*/ 149 150 /** 151 * @brief: The function performs CPRNGT (Continued PRNG Test) according 152 * to NIST 900-80 and FIPS (if defined) standards. 153 * 154 * @param[in] prev_ptr - The pointer to previous saved generated random 155 * value of size 16 bytes. 156 * @param[in] buff_ptr - The pointer to generated random buffer. 157 * @param[in] last_ptr - The pointer to last generated random block 158 * of size 16 bytes used for output last bytes. 159 * @param[in] countBlocks - The count of generated random blocks, including 160 * the last block. Assumed countBlocks > 0. 161 * 162 * @return CCError_t - On success CC_OK is returned, on failure a 163 * value MODULE_* as defined in cc_error.h 164 */ 165 CCError_t LLF_RND_RndCprngt(uint8_t *prev_ptr, /*in*/ 166 uint8_t *buff_ptr, /*in*/ 167 uint8_t *last_ptr, /*in*/ 168 int32_t countBlocks); /*in*/ 169 170 171 172 173 #ifdef __cplusplus 174 #endif 175 176 #endif 177
