Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
CryptoCell Random Generator APIs
Data Structures | |
struct | CRYS_RND_WorkBuff_t |
struct | CRYS_RND_State_t |
struct | CRYS_PrngFipsKatCtx_t |
Modules | |
CryptoCell RND specific errors | |
Typedefs | |
typedef uint32_t(* | SaSiRndGenerateVectWorkFunc_t )(\void *rndState_ptr,\uint16_t outSizeBytes,\uint8_t *out_ptr) |
Enumerations | |
enum | CRYS_RND_mode_t { CRYS_RND_Fast = 0, CRYS_RND_Slow = 1, CRYS_RND_ModeLast = 0x7FFFFFFF } |
Functions | |
CIMPORT_C CRYSError_t | CRYS_RND_Instantiation (void *rndState_ptr, CRYS_RND_WorkBuff_t *rndWorkBuff_ptr) |
This function initializes the RND context. 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 cryptography key generation and signatures). It is called as part of ARM TrustZone CryptoCell library initialization, which initializes and returns the primary RND context. This primary context can be used as a single global context for all RND needs. Alternatively, other contexts may be initialized and used with a more limited scope (for specific applications or specific threads). The call to this function must be followed by a call to CRYS_RND_SetGenerateVectorFunc API to set the generate vector function. It implements referenced standard [SP800-90] - 10.2.1.3.2 - CTR-DRBG Instantiate algorithm using AES (FIPS-PUB 197) and Derivation Function (DF). | |
CIMPORT_C CRYSError_t | CRYS_RND_UnInstantiation (void *rndState_ptr) |
Clears existing RNG instantiation state. | |
CIMPORT_C CRYSError_t | CRYS_RND_Reseeding (void *rndState_ptr, CRYS_RND_WorkBuff_t *rndWorkBuff_ptr) |
This function is used for reseeding the RNG with additional entropy and additional user-provided input. (additional data should be provided by calling CRYS_RND_AddAdditionalInput prior to using this API). It implements referenced standard [SP800-90] - 10.2.1.4.2 - CTR-DRBG Reseeding algorithm, using AES (FIPS-PUB 197) and Derivation Function (DF). | |
CIMPORT_C CRYSError_t | CRYS_RND_GenerateVector (void *rndState_ptr, uint16_t outSizeBytes, uint8_t *out_ptr) |
Generates a random vector according to the algorithm defined in referenced standard [SP800-90] - 10.2.1.5.2 - CTR-DRBG. The generation algorithm uses AES (FIPS-PUB 197) and Derivation Function (DF). | |
CIMPORT_C CRYSError_t | CRYS_RND_GenerateVectorInRange (void *rndState_ptr, SaSiRndGenerateVectWorkFunc_t rndGenerateVectFunc, uint32_t rndSizeInBits, uint8_t *maxVect_ptr, uint8_t *rndVect_ptr) |
Generates a random vector with specific limitations by testing candidates (described and used in FIPS 186-4: B.1.2, B.4.2 etc.). | |
CIMPORT_C CRYSError_t | CRYS_RND_AddAdditionalInput (void *rndState_ptr, uint8_t *additonalInput_ptr, uint16_t additonalInputSize) |
Used for adding additional input/personalization data provided by the user, to be later used by the CRYS_RND_Instantiation/CRYS_RND_Reseeding/CRYS_RND_GenerateVector functions. | |
CIMPORT_C CRYSError_t | CRYS_RND_EnterKatMode (void *rndState_ptr, uint8_t *entrData_ptr, uint32_t entrSize, uint8_t *nonce_ptr, uint32_t nonceSize, CRYS_RND_WorkBuff_t *workBuff_ptr) |
The CRYS_RND_EnterKatMode function sets KAT mode bit into StateFlag of global CRYS_RND_WorkingState structure. | |
CIMPORT_C void | CRYS_RND_DisableKatMode (void *rndState_ptr) |
The CRYS_RND_DisableKatMode function disables KAT mode bit into StateFlag of global CRYS_RND_State_t structure. |
Typedef Documentation
typedef uint32_t(* SaSiRndGenerateVectWorkFunc_t)(\void *rndState_ptr,\uint16_t outSizeBytes,\uint8_t *out_ptr) |
The RND Generate vector function pointer type definition. The prototype intendent for External and CRYS internal RND functions pointers definitions. Full description can be found in CRYS_RND_GenerateVector function API.
Definition at line 206 of file crys_rnd.h.
Enumeration Type Documentation
enum CRYS_RND_mode_t |
Definition of random operation modes.
- Enumerator:
CRYS_RND_Fast SW entropy estimation mode.
CRYS_RND_Slow Full entropy mode.
CRYS_RND_ModeLast Reserved.
Definition at line 129 of file crys_rnd.h.
Function Documentation
CIMPORT_C CRYSError_t CRYS_RND_AddAdditionalInput | ( | void * | rndState_ptr, |
uint8_t * | additonalInput_ptr, | ||
uint16_t | additonalInputSize | ||
) |
Used for adding additional input/personalization data provided by the user, to be later used by the CRYS_RND_Instantiation/CRYS_RND_Reseeding/CRYS_RND_GenerateVector functions.
- Returns:
- CRYS_OK on success.
- A non-zero value from crys_rnd_error.h on failure.
- Parameters:
-
[in,out] rndState_ptr Pointer to the RND context state buffer. [in] additonalInput_ptr The Additional Input buffer. [in] additonalInputSize The size of the Additional Input buffer. It must be <= CRYS_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS and a multiple of 4.
CIMPORT_C void CRYS_RND_DisableKatMode | ( | void * | rndState_ptr ) |
The CRYS_RND_DisableKatMode function disables KAT mode bit into StateFlag of global CRYS_RND_State_t structure.
The user must call this function after KAT tests before actual using RND module (Instantiation etc.).
- Returns:
- CRYS_OK on success.
- A non-zero value from crys_rnd_error.h on failure.
- Parameters:
-
[in,out] rndState_ptr Pointer to the RND state buffer.
CIMPORT_C CRYSError_t CRYS_RND_EnterKatMode | ( | void * | rndState_ptr, |
uint8_t * | entrData_ptr, | ||
uint32_t | entrSize, | ||
uint8_t * | nonce_ptr, | ||
uint32_t | nonceSize, | ||
CRYS_RND_WorkBuff_t * | workBuff_ptr | ||
) |
The CRYS_RND_EnterKatMode function sets KAT mode bit into StateFlag of global CRYS_RND_WorkingState structure.
The user must call this function before calling functions performing KAT tests.
- Note:
- Total size of entropy and nonce must be not great than 126 words (maximal size of entropy and nonce).
- Returns:
- CRYS_OK on success.
- A non-zero value from crys_rnd_error.h on failure.
- Parameters:
-
[in,out] rndState_ptr Pointer to the RND context state buffer. [in] entrData_ptr Entropy data. [in] entrSize Entropy size in bytes. [in] nonce_ptr Nonce. [in] nonceSize Entropy size in bytes. [out] workBuff_ptr RND working buffer, must be the same buffer, which should be passed into Instantiation/Reseeding functions.
CIMPORT_C CRYSError_t CRYS_RND_GenerateVector | ( | void * | rndState_ptr, |
uint16_t | outSizeBytes, | ||
uint8_t * | out_ptr | ||
) |
Generates a random vector according to the algorithm defined in referenced standard [SP800-90] - 10.2.1.5.2 - CTR-DRBG. The generation algorithm uses AES (FIPS-PUB 197) and Derivation Function (DF).
- Note:
- The RND module must be instantiated prior to invocation of this API.
-
In the following cases, Reseeding operation must be performed prior to vector generation:
- Prediction resistance is required.
- The function returns CRYS_RND_RESEED_COUNTER_OVERFLOW_ERROR, stating that the Reseed Counter has passed its upper-limit (2^32-2).
- Returns:
- CRYS_OK on success.
- A non-zero value from crys_rnd_error.h on failure.
- Parameters:
-
[in,out] rndState_ptr Pointer to the RND state structure, which is part of the RND context structure. Use rndContext->rndState field of the context for this parameter. [in] outSizeBytes The size in bytes of the random vector required. The maximal size is 2^16 -1 bytes. [out] out_ptr The pointer to output buffer.
CIMPORT_C CRYSError_t CRYS_RND_GenerateVectorInRange | ( | void * | rndState_ptr, |
SaSiRndGenerateVectWorkFunc_t | rndGenerateVectFunc, | ||
uint32_t | rndSizeInBits, | ||
uint8_t * | maxVect_ptr, | ||
uint8_t * | rndVect_ptr | ||
) |
Generates a random vector with specific limitations by testing candidates (described and used in FIPS 186-4: B.1.2, B.4.2 etc.).
This function draws a random vector, compare it to the range limits, and if within range - return it in rndVect_ptr. If outside the range, the function continues retrying until a conforming vector is found, or the maximal retries limit is exceeded. If maxVect_ptr is provided, rndSizeInBits specifies its size, and the output vector must conform to the range [1 < rndVect < maxVect]. If maxVect_ptr is NULL, rndSizeInBits specifies the exact required vector size, and the output vector must be the exact same bit size (with its most significant bit = 1).
- Note:
- The RND module must be instantiated prior to invocation of this API.
- Returns:
- CRYS_OK on success.
- A non-zero value from crys_rnd_error.h on failure.
- Parameters:
-
[in,out] rndState_ptr Pointer to the RND state structure. [in] rndGenerateVectFunc Pointer to the random vector generation function. [in] rndSizeInBits The size in bits of the random vector required. The allowed size in range 2 <= rndSizeInBits < 2^19-1, bits. [in] maxVect_ptr Pointer to the vector defining the upper limit for the random vector output, Given as little-endian byte array. If not NULL, its actual size is treated as [(rndSizeInBits+7)/8] bytes and its value must be in range (3, 2^19) [in,out] rndVect_ptr Pointer to the output buffer for the random vector. Must be at least [(rndSizeInBits+7)/8] bytes. Treated as little-endian byte array.
CIMPORT_C CRYSError_t CRYS_RND_Instantiation | ( | void * | rndState_ptr, |
CRYS_RND_WorkBuff_t * | rndWorkBuff_ptr | ||
) |
This function initializes the RND context. 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 cryptography key generation and signatures). It is called as part of ARM TrustZone CryptoCell library initialization, which initializes and returns the primary RND context. This primary context can be used as a single global context for all RND needs. Alternatively, other contexts may be initialized and used with a more limited scope (for specific applications or specific threads). The call to this function must be followed by a call to CRYS_RND_SetGenerateVectorFunc API to set the generate vector function. It implements referenced standard [SP800-90] - 10.2.1.3.2 - CTR-DRBG Instantiate algorithm using AES (FIPS-PUB 197) and Derivation Function (DF).
- 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.
- Returns:
- CRYS_OK on success.
- A non-zero value from crys_rnd_error.h on failure.
- Parameters:
-
[in,out] rndState_ptr Pointer to the RND state buffer allocated by the user, which is used to maintain the RND state. This context state must be saved and provided as a parameter to any API that uses the RND module.
- Note:
- the context must be cleared before sent to the function.
- Parameters:
-
[in,out] rndWorkBuff_ptr Scratchpad for the RND module's work.
CIMPORT_C CRYSError_t CRYS_RND_Reseeding | ( | void * | rndState_ptr, |
CRYS_RND_WorkBuff_t * | rndWorkBuff_ptr | ||
) |
This function is used for reseeding the RNG with additional entropy and additional user-provided input. (additional data should be provided by calling CRYS_RND_AddAdditionalInput prior to using this API). It implements referenced standard [SP800-90] - 10.2.1.4.2 - CTR-DRBG Reseeding algorithm, using AES (FIPS-PUB 197) and Derivation Function (DF).
- Returns:
- CRYS_OK on success.
- A non-zero value from crys_rnd_error.h on failure.
- Parameters:
-
[in,out] rndState_ptr Pointer to the RND context buffer. [in,out] rndWorkBuff_ptr Scratchpad for the RND module's work.
CIMPORT_C CRYSError_t CRYS_RND_UnInstantiation | ( | void * | rndState_ptr ) |
Clears existing RNG instantiation state.
- Returns:
- CRYS_OK on success.
- A non-zero value from crys_rnd_error.h on failure.
- Parameters:
-
[in,out] rndState_ptr Pointer to the RND context state buffer.
Generated on Tue Jul 12 2022 13:55:21 by
