crypto_interface_random.h File Reference

Cryptographic Interface header file for declaring RANDOM functions. More...

Go to the source code of this file.

Functions
MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_RANDOM_acquireContextEx (randomContext **ppRandomContext, ubyte algoId)
	This function is used to acquire an AES based CTR-DRBG random context. More...
MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_RANDOM_addEntropyBitEx (randomContext *pRandomContext, ubyte entropyBit)
	This function is used to add individual bits of entropy into the entropy pool. More...
MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_RANDOM_releaseContextEx (randomContext **pp_randomContext)
	This function is used to release and free a random context previously created using CRYPTO_INTERFACE_RANDOM_acquireContextEx. More...
MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_registerEntropyFunc (MGetEntropyFunc EntropyFunc, ubyte4 entropyLen)
	This function is used to register a function pointer for entropy collection. More...
MOC_EXTERN MSTATUS	CRYPTO_INTERFACE_regsterGetPersoStrCallback (MGetPersoStrCallback GetPersoStr)
	This function is used to register a function pointer for retrieving the personalization string. More...

Detailed Description

Add details here.

crypto_interface_random.h

Function Documentation

CRYPTO_INTERFACE_RANDOM_acquireContextEx()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_RANDOM_acquireContextEx	(	randomContext **	ppRandomContext,
		ubyte	algoId
	)

Any function pointers registered will be invoked during this call to retrieve the entropy and personalization string. If they have not been registered then the Digicert defaults are used. The key length to use will be the Digicert default value of NIST_CTRDRBG_DEFAULT_KEY_LEN_BYTES.

Parameters

ppRandomContext	Pointer to the location that will recieve the newly allocated random context.
algoId	Must be MODE_DRBG_CTR to recieve a crypto interface DRBG.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h.

CRYPTO_INTERFACE_RANDOM_addEntropyBitEx()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_RANDOM_addEntropyBitEx	(	randomContext *	pRandomContext,
		ubyte	entropyBit
	)

Note the bits do not get added exactly as is, the pool gets continously stirred so this should not be used for vector tests. Once enough bits have been added to make a full seed, the pool will be extracted into a buffer and provided to the random object as a reseed request.

Parameters

pRandomContext	Pointer to the random context to be reseeded.
entropyBit	The entropy bit to be added to the pool.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h.

CRYPTO_INTERFACE_RANDOM_releaseContextEx()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_RANDOM_releaseContextEx

(

randomContext **

pp_randomContext

)

Parameters

pp_randomContext

Pointer to the random context being freed.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h.

CRYPTO_INTERFACE_registerEntropyFunc()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_registerEntropyFunc	(	MGetEntropyFunc	EntropyFunc,
		ubyte4	entropyLen
	)

Random operators frequently prefer (or are bound by their APIs) to use a function pointer for collection entropy. After registration, the callback will be used to perform the initial seeding upon a call to CRYPTO_INTERFACE_RANDOM_acquireContextEx. It should be noted this function is not thread safe. Make sure to register any entropy functions before a call to CRYPTO_INTERFACE_RANDOM_acquireContextEx. If you would like the global rng to use this for entropy, you must register it before the call to MOCANA_initialize.

Parameters

EntropyFunc	Function pointer to be used to collect entropy for the initial seeding of a random object.
entropyLen	Number of bytes of entropy to collect for each call, must be greater than the security strength of the underlying block cipher.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h.

CRYPTO_INTERFACE_regsterGetPersoStrCallback()

MOC_EXTERN MSTATUS CRYPTO_INTERFACE_regsterGetPersoStrCallback

(

MGetPersoStrCallback

GetPersoStr

)

After registration, the callback will be used as input to the initial seeding upon a call to CRYPTO_INTERFACE_RANDOM_acquireContextEx. It should be noted this function is not thred safe. Make sure to register any callback functions before a call to CRYPTO_INTERFACE_RANDOM_acquireContextEx. If you would like the global rng to use this for entropy, you must register it before the call to MOCANA_initialize.

Parameters

GetPersoStr

Function pointer to be used to retrieve the personalization string for use in the initial seeding of a random object.

Returns

OK (0) if successful; otherwise a negative number error code definition from merrors.h.