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 _LEGA_RND_H_ 17 #define _LEGA_RND_H_ 18 19 /*****************************************************************************/ 20 /********************** Public Functions *************************/ 21 /*****************************************************************************/ 22 void lega_rnd_init(void); 23 void lega_rnd_deinit(void); 24 25 /*! 26 @brief This function is used for reseeding the RNG with additional entropy and additional user-provided input. 27 (additional data should be provided by calling ::CRYS_RND_AddAdditionalInput prior to using this API). 28 It implements referenced standard [SP800-90] - 10.2.1.4.2 - CTR-DRBG Reseeding algorithm, using AES (FIPS-PUB 197) and Derivation Function (DF). 29 30 @return CRYS_OK on success. 31 @return A non-zero value from crys_rnd_error.h on failure. 32 */ 33 int lega_RND_Reseeding( 34 uint8_t *rndContext_ptr, /* !< [in/out] Pointer to the RND context buffer. */ 35 uint8_t *rndWorkBuff_ptr /* !< [in/out] Scratchpad for the RND module's work. */ 36 ); 37 38 /****************************************************************************************/ 39 /*! 40 @brief Generates a random vector according to the algorithm defined in referenced standard [SP800-90] - 10.2.1.5.2 - CTR-DRBG. 41 The generation algorithm uses AES (FIPS-PUB 197) and Derivation Function (DF). 42 43 \note 44 <ul id="noteb"><li> The RND module must be instantiated prior to invocation of this API.</li> 45 <li> In the following cases, Reseeding operation must be performed prior to vector generation:</li> 46 <ul><li> Prediction resistance is required.</li> 47 <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> 48 49 @return CRYS_OK on success. 50 @return A non-zero value from crys_rnd_error.h on failure. 51 */ 52 int lega_RND_GenerateVector( 53 uint8_t *rndState_ptr, /* !< [in/out] Pointer to the RND state structure, which is part of the RND context structure. 54 Use rndContext->rndState field of the context for this parameter. */ 55 uint16_t 56 outSizeBytes, /* !< [in] The size in bytes of the random vector required. The maximal size is 2^16 -1 bytes. */ 57 uint8_t *out_ptr /* !< [out] The pointer to output buffer. */ 58 ); 59 60 /*************************************************************************************/ 61 /*! 62 @brief Used for adding additional input/personalization data provided by the user, 63 to be later used by the ::CRYS_RND_Instantiation/::CRYS_RND_Reseeding/::CRYS_RND_GenerateVector functions. 64 65 @return CRYS_OK on success. 66 @return A non-zero value from crys_rnd_error.h on failure. 67 */ 68 int lega_RND_AddAdditionalInput( 69 uint8_t *rndContext_ptr, /* !< [in/out] Pointer to the RND context buffer. */ 70 uint8_t *additonalInput_ptr, /* !< [in] The Additional Input buffer. */ 71 uint16_t additonalInputSize /* !< [in] The size of the Additional Input buffer. Must be <= 48, and a multiple of 4. */ 72 ); 73 74 #endif // _LEGA_RND_H_