1 /************************************************************************************** 2 * Copyright (c) 2016-2019, Arm Limited (or its affiliates). All rights reserved * 3 * * 4 * This file and the related binary are licensed under the following license: * 5 * * 6 * ARM Object Code and Header Files License, v1.0 Redistribution. * 7 * * 8 * Redistribution and use of object code, header files, and documentation, without * 9 * modification, are permitted provided that the following conditions are met: * 10 * * 11 * 1) Redistributions must reproduce the above copyright notice and the * 12 * following disclaimer in the documentation and/or other materials * 13 * provided with the distribution. * 14 * * 15 * 2) Unless to the extent explicitly permitted by law, no reverse * 16 * engineering, decompilation, or disassembly of is permitted. * 17 * * 18 * 3) Redistribution and use is permitted solely for the purpose of * 19 * developing or executing applications that are targeted for use * 20 * on an ARM-based product. * 21 * * 22 * DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND * 23 * CONTRIBUTORS "AS IS." ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT * 24 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, * 25 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE * 26 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * 27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED * 28 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR * 29 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF * 30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * 31 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * 32 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * 33 **************************************************************************************/ 34 35 /*! 36 @addtogroup cc_rnd 37 @{ 38 */ 39 40 /*! 41 @file 42 @brief This file contains the CryptoCell random-number generation (RNG) APIs. 43 44 The random-number generation module implements <em>NIST Special Publication 45 800-90A: Recommendation for Random Number Generation Using Deterministic 46 Random Bit Generators.</em> 47 */ 48 49 50 #ifndef _CC_RND_COMMON_H 51 #define _CC_RND_COMMON_H 52 53 #include "cc_error.h" 54 #include "cc_aes_defs.h" 55 56 #ifdef __cplusplus 57 extern "C" 58 { 59 #endif 60 61 /************************ Defines ******************************/ 62 63 /* RND seed and additional input sizes */ 64 /*! The maximal size of the random seed in words. */ 65 #define CC_RND_SEED_MAX_SIZE_WORDS 12 66 #ifndef USE_MBEDTLS_CRYPTOCELL 67 #ifndef CC_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS 68 /*! The maximal size of the additional input-data in words. */ 69 #define CC_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS CC_RND_SEED_MAX_SIZE_WORDS 70 #endif 71 #endif 72 /* maximal requested size counter (12 bits active) - maximal count 73 of generated random 128 bit blocks allowed per one request of 74 Generate function according NIST 800-90 it is (2^12 - 1) = 0x3FFFF */ 75 /* Max size for one RNG generation (in bits) = 76 max_num_of_bits_per_request = 2^19 (FIPS 800-90 Tab.3) */ 77 /*! The maximal size of the generated vector in bits. */ 78 #define CC_RND_MAX_GEN_VECTOR_SIZE_BITS 0x7FFFF 79 /*! The maximal size of the generated random vector in bytes. */ 80 #define CC_RND_MAX_GEN_VECTOR_SIZE_BYTES 0xFFFF 81 /*! The maximal size of the generated vector in bytes. */ 82 #define CC_RND_REQUESTED_SIZE_COUNTER 0x3FFFF 83 84 /* Definitions of temp buffer for RND_DMA */ 85 /*******************************************************************/ 86 /* Definitions of temp buffer for DMA */ 87 /*! The size of the temporary buffer in words. */ 88 #define CC_RND_WORK_BUFFER_SIZE_WORDS 136 89 90 /*! The definition of the RAM buffer, for internal use in instantiation or 91 reseeding operations. */ 92 typedef struct 93 { 94 /*! The internal buffer. */ 95 uint32_t ccRndIntWorkBuff[CC_RND_WORK_BUFFER_SIZE_WORDS]; 96 }CCRndWorkBuff_t; 97 98 99 /* RND source buffer inner (entrpopy) offset */ 100 /*! The definition of the internal offset in words. */ 101 #define CC_RND_TRNG_SRC_INNER_OFFSET_WORDS 2 102 /*! The definition of the internal offset in bytes. */ 103 #define CC_RND_TRNG_SRC_INNER_OFFSET_BYTES (CC_RND_TRNG_SRC_INNER_OFFSET_WORDS*sizeof(uint32_t)) 104 105 106 /************************ Enumerators ****************************/ 107 108 /*! The definition of the random operation modes. */ 109 typedef enum 110 { 111 /*! HW entropy estimation: 800-90B or full. */ 112 CC_RND_FE = 1, 113 /*! Reserved. */ 114 CC_RND_ModeLast = 0x7FFFFFFF, 115 } CCRndMode_t; 116 117 118 /************************ Structs *****************************/ 119 120 121 /* The internal state of DRBG mechanism based on AES CTR and CBC-MAC 122 algorithms. It is set as global data defined by the following 123 structure */ 124 /*! 125 126 @brief The structure for the RND state. 127 This includes internal data that must be saved by the user between boots. 128 */ 129 typedef struct 130 { 131 #ifndef USE_MBEDTLS_CRYPTOCELL 132 /* Seed buffer, consists from concatenated Key||V: max size 12 words */ 133 /*! The random-seed buffer. */ 134 uint32_t Seed[CC_RND_SEED_MAX_SIZE_WORDS]; 135 /* Previous value for continuous test */ 136 /*! The previous random data, used for continuous test. */ 137 uint32_t PreviousRandValue[CC_AES_CRYPTO_BLOCK_SIZE_IN_WORDS]; 138 /* AdditionalInput buffer max size = seed max size words + 4w for padding*/ 139 /*! The previous additional-input buffer. */ 140 uint32_t PreviousAdditionalInput[CC_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS+3]; 141 /*! The additional-input buffer. */ 142 uint32_t AdditionalInput[CC_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS+4]; 143 /*! The size of the additional input in words. */ 144 uint32_t AddInputSizeWords; 145 /*! The size of the entropy source in words. */ 146 uint32_t EntropySourceSizeWords; 147 /*! The Reseed counter (32-bit active). Indicates the number of requests 148 for entropy since instantiation or reseeding. */ 149 uint32_t ReseedCounter; 150 /*! The key size in words, according to security strength: 128 bits: 151 4 words. 256 bits: 8 words. */ 152 uint32_t KeySizeWords; 153 /* State flag (see definition of StateFlag above), containing bit-fields, defining: 154 - b'0: instantiation steps: 0 - not done, 1 - done; 155 - 2b'9,8: working or testing mode: 0 - working, 1 - KAT DRBG test, 2 - 156 KAT TRNG test; 157 b'16: flag defining is Previous random valid or not: 158 0 - not valid, 1 - valid */ 159 /*! The state flag used internally in the code. */ 160 uint32_t StateFlag; 161 /* validation tag */ 162 /*! The validation tag used internally in the code. */ 163 uint32_t ValidTag; 164 /*! The size of the RND source entropy in bits. */ 165 uint32_t EntropySizeBits; 166 167 #endif 168 /*! The TRNG process state used internally in the code. */ 169 uint32_t TrngProcesState; 170 171 } CCRndState_t; 172 173 174 /*! The RND vector-generation function pointer. */ 175 typedef int (*CCRndGenerateVectWorkFunc_t)( \ 176 /*! A pointer to the RND-state context. */ 177 void *rndState_ptr, \ 178 /*! A pointer to the output buffer. */ 179 unsigned char *out_ptr, \ 180 /*! The size of the output in bytes. */ 181 size_t outSizeBytes 182 ); 183 184 185 /*! The definition of the RND context that includes the CryptoCell 186 RND state structure, and a function pointer for the RND-generation 187 function. */ 188 typedef struct 189 { 190 /*! A pointer to the internal state of the RND. 191 Note: This pointer should be allocated in a physical and contiguous 192 memory, that is accessible to the CryptoCell DMA. This pointer should 193 be allocated and assigned before calling CC_LibInit(). */ 194 void * rndState; 195 /*! A pointer to the entropy context. Note: This pointer should be 196 allocated and assigned before calling CC_LibInit(). */ 197 void * entropyCtx; 198 /*! A pointer to the user-given function for generation a random 199 vector. */ 200 CCRndGenerateVectWorkFunc_t rndGenerateVectFunc; 201 } CCRndContext_t; 202 203 204 205 206 207 /*****************************************************************************/ 208 /********************** Public Functions *************************/ 209 /*****************************************************************************/ 210 211 212 /****************************************************************************************/ 213 /*! 214 @brief This function sets the RND vector-generation function into the RND 215 context. 216 217 It is called as part of Arm CryptoCell library initialization, to 218 set the RND vector generation function into the primary RND context. 219 220 @note It must be called before any other API that requires the RND context as 221 a parameter. 222 223 @return \c CC_OK on success. 224 @return A non-zero value from cc_rnd_error.h on failure. 225 */ 226 CCError_t CC_RndSetGenerateVectorFunc( 227 /*! [in/out] A pointer to the RND context buffer that is allocated 228 by the user, which is used to maintain the RND state, as well as 229 pointers to the functions used for random vector generation. */ 230 CCRndContext_t *rndContext_ptr, 231 /*! [in] A pointer to the \c CC_RndGenerateVector random 232 vector-generation function. */ 233 CCRndGenerateVectWorkFunc_t rndGenerateVectFunc 234 ); 235 236 237 238 239 #ifdef __cplusplus 240 } 241 #endif 242 243 /*! 244 @} 245 */ 246 #endif /* #ifndef _CC_RND_COMMON_H */ 247
