1 /* 2 * Copyright (c) 2022 ASR Microelectronics (Shanghai) Co., Ltd. All rights reserved. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 #ifndef _DUET_RND_H_ 17 #define _DUET_RND_H_ 18 19 #include "sns_silib.h" 20 #include "crys_rnd.h" 21 #include "crys_error.h" 22 /*****************************************************************************/ 23 /********************** Public Functions *************************/ 24 /*****************************************************************************/ 25 26 /*! 27 @brief This function initializes the RND context. 28 It must be called at least once prior to using this context with any API that requires it as a parameter (e.g., other RND APIs, asymmetric 29 cryptography key generation and signatures). 30 It is called as part of ARM TrustZone CryptoCell library initialization, which initializes and returns the primary RND context. 31 This primary context can be used as a single global context for all RND needs. 32 Alternatively, other contexts may be initialized and used with a more limited scope (for specific applications or specific threads). 33 The call to this function must be followed by a call to ::CRYS_RND_SetGenerateVectorFunc API to set the generate vector function. 34 It implements referenced standard [SP800-90] - 10.2.1.3.2 - CTR-DRBG Instantiate algorithm using AES (FIPS-PUB 197) and Derivation Function (DF). 35 \note Additional data can be mixed with the random seed (personalization data or nonce). If required, this data should be provided by calling ::CRYS_RND_AddAdditionalInput prior to using this API. 36 37 @return CRYS_OK on success. 38 @return A non-zero value from crys_rnd_error.h on failure. 39 */ 40 int duet_RND_Instantiation(CRYS_RND_Context_t 41 *rndContext_ptr, /* !< [in/out] Pointer to the RND context buffer allocated by the user, which is used to 42 maintain the RND state, as well as pointers to the functions used for 43 random vector generation. This context must be saved and provided as a 44 parameter to any API that uses the RND module. 45 \note the context must be cleared before sent to the function. */ 46 CRYS_RND_WorkBuff_t *rndWorkBuff_ptr /* !< [in/out] Scratchpad for the RND module's work. */ 47 ); 48 49 /*! 50 @brief Clears existing RNG instantiation state. 51 52 @return CRYS_OK on success. 53 @return A non-zero value from crys_rnd_error.h on failure. 54 */ 55 int duet_RND_UnInstantiation(CRYS_RND_Context_t *rndContext_ptr); /* !< [in/out] Pointer to the RND context 56 * buffer. */ 57 58 /*! 59 @brief This function is used for reseeding the RNG with additional entropy and additional user-provided input. 60 (additional data should be provided by calling ::CRYS_RND_AddAdditionalInput prior to using this API). 61 It implements referenced standard [SP800-90] - 10.2.1.4.2 - CTR-DRBG Reseeding algorithm, using AES (FIPS-PUB 197) and Derivation Function (DF). 62 63 @return CRYS_OK on success. 64 @return A non-zero value from crys_rnd_error.h on failure. 65 */ 66 int duet_RND_Reseeding(CRYS_RND_Context_t *rndContext_ptr, /* !< [in/out] Pointer to the RND context buffer. */ 67 CRYS_RND_WorkBuff_t *rndWorkBuff_ptr /* !< [in/out] Scratchpad for the RND module's work. */ 68 ); 69 70 /****************************************************************************************/ 71 /*! 72 @brief Generates a random vector according to the algorithm defined in referenced standard [SP800-90] - 10.2.1.5.2 - CTR-DRBG. 73 The generation algorithm uses AES (FIPS-PUB 197) and Derivation Function (DF). 74 75 \note 76 <ul id="noteb"><li> The RND module must be instantiated prior to invocation of this API.</li> 77 <li> In the following cases, Reseeding operation must be performed prior to vector generation:</li> 78 <ul><li> Prediction resistance is required.</li> 79 <li> The function returns CRYS_RND_RESEED_COUNTER_OVERFLOW_ERROR, stating that the Reseed Counter has passed its upper-limit (2^32-2).</li></ul></ul> 80 81 @return CRYS_OK on success. 82 @return A non-zero value from crys_rnd_error.h on failure. 83 */ 84 int duet_RND_GenerateVector(CRYS_RND_State_t 85 *rndState_ptr, /* !< [in/out] Pointer to the RND state structure, which is part of the RND context structure. 86 Use rndContext->rndState field of the context for this parameter. */ 87 uint16_t outSizeBytes, /* !< [in] The size in bytes of the random vector required. The maximal size is 2^16 -1 bytes. */ 88 uint8_t *out_ptr /* !< [out] The pointer to output buffer. */ 89 ); 90 91 /****************************************************************************************/ 92 /*! 93 94 @brief This function sets the RND vector generation function into the RND context. 95 96 It must be called after ::CRYS_RND_Instantiation, and prior to any other API that requires the RND context as parameter. 97 It is called as part of ARM TrustZone CryptoCell library initialization, to set the RND vector generation function into the primary RND context, 98 after ::CRYS_RND_Instantiation is called. 99 100 @return CRYS_OK on success. 101 @return A non-zero value from crys_rnd_error.h on failure. 102 */ 103 int duet_RND_SetGenerateVectorFunc(CRYS_RND_Context_t 104 *rndContext_ptr, /* !< [in/out] Pointer to the RND context buffer allocated by the user, 105 which is used to maintain the RND state as well as pointers 106 to the functions used for random vector generation. */ 107 SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc /* !< [in] Pointer to the random vector generation function. 108 The pointer should point to the ::CRYS_RND_GenerateVector function. */ 109 ); 110 111 /**********************************************************************************************************/ 112 /*! 113 @brief Generates a random vector with specific limitations by testing candidates (described and used in FIPS 186-4: B.1.2, B.4.2 etc.). 114 115 This function will draw a random vector, compare it to the range limits, and if within range - return it in rndVect_ptr. 116 If outside the range, the function will continue retrying until a conforming vector is found, or the maximal retries limit is exceeded. 117 If maxVect_ptr is provided, rndSizeInBits specifies its size, and the output vector must conform to the range [1 < rndVect < maxVect_ptr]. 118 If maxVect_ptr is NULL, rndSizeInBits specifies the exact required vector size, and the output vector must be the exact same 119 bit size (with its most significant bit = 1). 120 \note 121 The RND module must be instantiated prior to invocation of this API. 122 123 @return CRYS_OK on success. 124 @return A non-zero value from crys_rnd_error.h on failure. 125 */ 126 int duet_RND_GenerateVectorInRange( 127 CRYS_RND_Context_t *rndContext_ptr, /* !< [in/out] Pointer to the RND context buffer. */ 128 uint32_t rndSizeInBits, /* !< [in] The size in bits of the random vector required. The allowed size in range 2 <= rndSizeInBits < 2^19-1, bits. */ 129 uint8_t *maxVect_ptr, /* !< [in] Pointer to the vector defining the upper limit for the random vector output, Given as little-endian byte array. 130 If not NULL, its actual size is treated as [(rndSizeInBits+7)/8] bytes. */ 131 uint8_t *rndVect_ptr /* !< [in/out] Pointer to the output buffer for the random vector. Must be at least [(rndSizeInBits+7)/8] bytes. 132 Treated as little-endian byte array. */ 133 ); 134 135 /*************************************************************************************/ 136 /*! 137 @brief Used for adding additional input/personalization data provided by the user, 138 to be later used by the ::CRYS_RND_Instantiation/::CRYS_RND_Reseeding/::CRYS_RND_GenerateVector functions. 139 140 @return CRYS_OK on success. 141 @return A non-zero value from crys_rnd_error.h on failure. 142 */ 143 int duet_RND_AddAdditionalInput(CRYS_RND_Context_t 144 *rndContext_ptr, /* !< [in/out] Pointer to the RND context buffer. */ 145 uint8_t *additonalInput_ptr, /* !< [in] The Additional Input buffer. */ 146 uint16_t additonalInputSize /* !< [in] The size of the Additional Input buffer. Must be <= 48, and a multiple of 4. */ 147 ); 148 149 /*! 150 @brief The CRYS_RND_EnterKatMode function sets KAT mode bit into StateFlag of global CRYS_RND_WorkingState structure. 151 152 The user must call this function before calling functions performing KAT tests. 153 154 \note Total size of entropy and nonce must be not great than: ::CRYS_RND_MAX_KAT_ENTROPY_AND_NONCE_SIZE, defined. 155 156 @return CRYS_OK on success. 157 @return A non-zero value from crys_rnd_error.h on failure. 158 */ 159 int duet_RND_EnterKatMode(CRYS_RND_Context_t *rndContext_ptr, /* !< [in/out] Pointer to the RND context buffer. */ 160 uint8_t *entrData_ptr, /* !< [in] Entropy data. */ 161 uint32_t entrSize, /* !< [in] Entropy size in bytes. */ 162 uint8_t *nonce_ptr, /* !< [in] Nonce. */ 163 uint32_t nonceSize, /* !< [in] Entropy size in bytes. */ 164 CRYS_RND_WorkBuff_t 165 *workBuff_ptr /* !< [out] RND working buffer, must be the same buffer, which should be passed into 166 Instantiation/Reseeding functions. */ 167 ); 168 169 /**********************************************************************************************************/ 170 /*! 171 @brief The CRYS_RND_DisableKatMode function disables KAT mode bit into StateFlag of global CRYS_RND_WorkingState structure. 172 173 The user must call this function after KAT tests before actual using RND module (Instantiation etc.). 174 175 @return CRYS_OK on success. 176 @return A non-zero value from crys_rnd_error.h on failure. 177 */ 178 void duet_RND_DisableKatMode(CRYS_RND_Context_t *rndContext_ptr /* !< [in/out] Pointer to the RND context buffer. */ 179 ); 180 181 #endif // _DUET_RND_H_