Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
CryptoCell Random Generator APIs

Modules

 CryptoCell RND specific errors
 

Data Structures

struct  CRYS_RND_WorkBuff_t
 
struct  CRYS_RND_State_t
 
struct  CRYS_PrngFipsKatCtx_t
 

Macros

#define CRYS_RND_MAX_RESEED_COUNTER   (0xFFFFFFFF - 0xF)
 
#define CRYS_RND_MAX_GEN_VECTOR_SIZE_BITS   0x7FFFF
 
#define CRYS_RND_MAX_GEN_VECTOR_SIZE_BYTES   0xFFFF
 
#define CRYS_RND_AES_BLOCK_SIZE_IN_WORDS   SASI_AES_BLOCK_SIZE_IN_WORDS
 
#define CRYS_RND_SEED_MAX_SIZE_WORDS   12
 
#define CRYS_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS   CRYS_RND_SEED_MAX_SIZE_WORDS
 
#define CRYS_RND_AES_KEY_128_SIZE_WORDS   4
 
#define CRYS_RND_AES_KEY_192_SIZE_WORDS   6
 
#define CRYS_RND_AES_KEY_256_SIZE_WORDS   8
 
#define CRYS_RND_WORK_BUFFER_SIZE_WORDS   1528
 
#define CRYS_RND_EntropyEstimatData_t   CRYS_RND_WorkBuff_t
 
#define crysRndEntrIntBuff   crysRndWorkBuff
 
#define CRYS_RND_TRNG_SRC_INNER_OFFSET_WORDS   2
 
#define CRYS_RND_TRNG_SRC_INNER_OFFSET_BYTES   (CRYS_RND_TRNG_SRC_INNER_OFFSET_WORDS*sizeof(uint32_t))
 
#define CRYS_PRNG_FIPS_KAT_OUT_DATA_SIZE   64
 

Typedefs

typedef uint32_t(* SaSiRndGenerateVectWorkFunc_t) (void *rndState_ptr, uint16_t outSizeBytes, uint8_t *out_ptr)
 

Enumerations

Functions

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). More...
 
CRYSError_t CRYS_RND_UnInstantiation (void *rndState_ptr)
 Clears existing RNG instantiation state. More...
 
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). More...
 
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). More...
 
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.). More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description

Macro Definition Documentation

#define CRYS_PRNG_FIPS_KAT_OUT_DATA_SIZE   64

FIPS Known answer test output size.

Definition at line 124 of file crys_rnd.h.

#define CRYS_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS   CRYS_RND_SEED_MAX_SIZE_WORDS

Maximal size of additional input data in words.

Definition at line 82 of file crys_rnd.h.

#define CRYS_RND_AES_BLOCK_SIZE_IN_WORDS   SASI_AES_BLOCK_SIZE_IN_WORDS

AES output block size in words.

Definition at line 73 of file crys_rnd.h.

#define CRYS_RND_AES_KEY_128_SIZE_WORDS   4

AES key size (128 bits) in words.

Definition at line 87 of file crys_rnd.h.

#define CRYS_RND_AES_KEY_192_SIZE_WORDS   6

AES key size (192 bits) in words.

Definition at line 89 of file crys_rnd.h.

#define CRYS_RND_AES_KEY_256_SIZE_WORDS   8

AES key size (256 bits) in words.

Definition at line 91 of file crys_rnd.h.

#define CRYS_RND_EntropyEstimatData_t   CRYS_RND_WorkBuff_t

A definition for entropy estimation data type.

Definition at line 108 of file crys_rnd.h.

#define CRYS_RND_MAX_GEN_VECTOR_SIZE_BITS   0x7FFFF

Maximal size of generated vector in bits.

Definition at line 68 of file crys_rnd.h.

#define CRYS_RND_MAX_GEN_VECTOR_SIZE_BYTES   0xFFFF

Maximal size of generated vector in bytes.

Definition at line 70 of file crys_rnd.h.

#define CRYS_RND_MAX_RESEED_COUNTER   (0xFFFFFFFF - 0xF)

Maximal reseed counter - indicates maximal number of requests allowed between reseeds; according to NIST 800-90 it is (2^48 - 1), our restriction is : (0xFFFFFFFF - 0xF).

Definition at line 63 of file crys_rnd.h.

#define CRYS_RND_SEED_MAX_SIZE_WORDS   12

Maximal size of random seed in words.

Definition at line 78 of file crys_rnd.h.

#define CRYS_RND_TRNG_SRC_INNER_OFFSET_BYTES   (CRYS_RND_TRNG_SRC_INNER_OFFSET_WORDS*sizeof(uint32_t))

An internal offset definition.

Definition at line 117 of file crys_rnd.h.

#define CRYS_RND_TRNG_SRC_INNER_OFFSET_WORDS   2

An internal offset definition.

Definition at line 115 of file crys_rnd.h.

#define CRYS_RND_WORK_BUFFER_SIZE_WORDS   1528

Temporary buffer size in words.

Definition at line 98 of file crys_rnd.h.

#define crysRndEntrIntBuff   crysRndWorkBuff

A definition for entropy estimation buffer.

Definition at line 110 of file crys_rnd.h.

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

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_ptrPointer to the RND context state buffer.
[in]additonalInput_ptrThe Additional Input buffer.
[in]additonalInputSizeThe size of the Additional Input buffer. It must be <= CRYS_RND_ADDITINAL_INPUT_MAX_SIZE_WORDS and a multiple of 4.
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_ptrPointer to the RND state buffer.
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_ptrPointer to the RND context state buffer.
[in]entrData_ptrEntropy data.
[in]entrSizeEntropy size in bytes.
[in]nonce_ptrNonce.
[in]nonceSizeEntropy size in bytes.
[out]workBuff_ptrRND working buffer, must be the same buffer, which should be passed into Instantiation/Reseeding functions.
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_ptrPointer to the RND state structure, which is part of the RND context structure. Use rndContext->rndState field of the context for this parameter.
[in]outSizeBytesThe size in bytes of the random vector required. The maximal size is 2^16 -1 bytes.
[out]out_ptrThe pointer to output buffer.
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_ptrPointer to the RND state structure.
[in]rndGenerateVectFuncPointer to the random vector generation function.
[in]rndSizeInBitsThe size in bits of the random vector required. The allowed size in range 2 <= rndSizeInBits < 2^19-1, bits.
[in]maxVect_ptrPointer 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_ptrPointer to the output buffer for the random vector. Must be at least [(rndSizeInBits+7)/8] bytes. Treated as little-endian byte array.
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_ptrPointer 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_ptrScratchpad for the RND module's work.
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_ptrPointer to the RND context buffer.
[in,out]rndWorkBuff_ptrScratchpad for the RND module's work.
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_ptrPointer to the RND context state buffer.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.