Random Number Generator (RNG) API header. More...

Typedefs
typedef sbyte4(*	RNGFun) (void rngFunArg, ubyte4 length, ubyte buffer)
	Function pointer type for a method that produces (pseudo) random bytes. More...

Enumerations
enum	randomContextType { NIST_FIPS186 = 0, NIST_CTR_DRBG = 2, MOC_RAND = 3 }

Functions
MOC_EXTERN ubyte *	GetNullPersonalizationString (ubyte4 *pLen)
	Returns a NULL string. More...

MOC_EXTERN MSTATUS	RANDOM_acquireContext (randomContext **pp_randomContext)
	Create an RNG (random number generator) context data structure. More...

MOC_EXTERN MSTATUS	RANDOM_acquireContextEx (randomContext **pp_randomContext, ubyte algoId)

MOC_EXTERN MSTATUS	RANDOM_addEntropyBit (randomContext *pRandomContext, ubyte entropyBit)
	Add entropy to the RNG (random number generator) module. More...

MOC_EXTERN MSTATUS	RANDOM_addEntropyBitEx (randomContext *pRandomContext, ubyte entropyBit)

MOC_EXTERN MSTATUS	RANDOM_deleteFIPS186Context (randomContext **ppRandomContext)
	Deletes a FIPS186 RNG context. More...

MOC_EXTERN MSTATUS	RANDOM_generateASCIIString (randomContext pRandomContext, ubyte pBuffer, ubyte4 bufferLen)
	Function to return a random ASCII character string. More...

MOC_EXTERN MSTATUS	RANDOM_getAutoSeedBytes (ubyte *pSeedBytes, ubyte4 numBytes)
	Collect entropy bytes for seed material. More...

MOC_EXTERN ubyte	RANDOM_getEntropySource (void)
	Gets the global entropy source flag. More...

MOC_EXTERN MSTATUS	RANDOM_isMocSymContext (randomContext *ppRandomContext, intBoolean pIsMocSym)
	Determine if a randomContext refers to a MocSym random implementation. More...

MOC_EXTERN MSTATUS	RANDOM_KSrcGenerator (randomContext *pRandomContext, ubyte buffer[40])

MOC_EXTERN MSTATUS	RANDOM_launchAutoSeed (randomContext *pCtx)
	Seed a random context using the built-in entropy collection. More...

MOC_EXTERN MSTATUS	RANDOM_newFIPS186Context (randomContext **ppRandomContext, ubyte b, const ubyte pXKey[], sbyte4 seedLen, const ubyte pXSeed[])
	Generate FIPS-specific RNG context data structure using provided seed. More...

MOC_EXTERN MSTATUS	RANDOM_numberGenerator (randomContext pRandomContext, ubyte pBuffer, sbyte4 bufSize)
	Generate the specified number of random bits. More...

MOC_EXTERN MSTATUS	RANDOM_numberGeneratorAdd (randomContext pRandomContext, ubyte pRetRandomBytes, ubyte4 numRandomBytes, ubyte *pAdditionalData, ubyte4 additionalDataLen)
	Generate random bytes with optional additional input. More...

MOC_EXTERN MSTATUS	RANDOM_numberGeneratorFIPS186 (randomContext pRandomContext, ubyte pRetRandomBytes, sbyte4 numRandomBytes)
	Generate the specified number of random bits via FIPS186. More...

MOC_EXTERN MSTATUS	RANDOM_releaseContext (randomContext **pp_randomContext)
	Delete RNG (random number generator) context data structure. More...

MOC_EXTERN MSTATUS	RANDOM_releaseContextEx (randomContext **pp_randomContext)

MOC_EXTERN MSTATUS	RANDOM_reseedContext (randomContext pCtx, ubyte pEntropy, ubyte4 entropyLen, ubyte *pAdditionalData, ubyte4 additionalDataLen)
	Reseed a random context. More...

MOC_EXTERN sbyte4	RANDOM_rngFun (void rngFunArg, ubyte4 length, ubyte buffer)
	Generate a random number. More...

MOC_EXTERN MSTATUS	RANDOM_seedFIPS186Context (randomContext pRandomCtx, ubyte seed, ubyte4 seedLen)
	Seed a previously allocated FIPS186 Random Context. More...

MOC_EXTERN MSTATUS	RANDOM_seedFromDevURandom (randomContext *pCtx, ubyte4 numBytes)
	Seed a random context with bytes from /dev/urandom. More...

MOC_EXTERN MSTATUS	RANDOM_seedOldRandom (randomContext pCtx, ubyte pSeedBytes, ubyte4 seedLen)
	Seeds randomContexts that are not MocSym Operators. More...

MOC_EXTERN MSTATUS	RANDOM_setEntropySource (ubyte EntropySrc)
	Sets the global entropy source flag. More...

MOC_EXTERN void	resetRNGFail (void)
	Resets the global RNG fail flag back to FALSE (0).

MOC_EXTERN void	triggerRNGFail (void)
	Sets the global RNG fail flag to TRUE (1).

Variables
MOC_EXTERN_RANDOM_H randomContext *	g_pRandomContext

Detailed Description

This file documents the definitions, enumerations, structures, and function of the Digicert Security of Things (SoT) Platform Random Number Generator.

Whether the following flag is defined determines which functions are declared:

__DISABLE_MOCANA_ADD_ENTROPY__

random.h

Typedef Documentation

◆ RNGFun

typedef sbyte4(* RNGFun) (void *rngFunArg, ubyte4 length, ubyte *buffer)

Function pointer type for a method that produces (pseudo) random bytes.

random.h

Parameters

rngFunArg	Optional argument that may be needed by your implementation. Often this will be a random context.
length	The number of bytes requested.
buffer	Buffer to hold the resuling output bytes.

Returns: Must return OK (0) if successful and non-zero if unsuccessful.

random.h

Function Documentation

◆ GetNullPersonalizationString()

MOC_EXTERN ubyte* GetNullPersonalizationString ( ubyte4 * pLen )

Parameters

pLen	Contents will be set to the length of a `NULL` string, ie 0.

Returns: NULL pointer.

◆ RANDOM_acquireContext()

MOC_EXTERN MSTATUS RANDOM_acquireContext ( randomContext ** pp_randomContext )

This function creates a new RNG (random number generator) context data structure.

There are no flag dependencies to enable this function.

random.h

Parameters

pp_randomContext On return, pointer to new RNG context.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

random.h

◆ RANDOM_addEntropyBit()

MOC_EXTERN MSTATUS RANDOM_addEntropyBit	(	randomContext *	pRandomContext,
		ubyte	entropyBit
	)

This function adds entropy to the RNG (random number generator) module, thereby increasing randomness.

random.h

To enable this function, the following flag must not be defined:

__DISABLE_MOCANA_ADD_ENTROPY__

Parameters

pRandomContext	Pointer to RNG context.
entropyBit	Entropy to add.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

random.h

◆ RANDOM_deleteFIPS186Context()

MOC_EXTERN MSTATUS RANDOM_deleteFIPS186Context ( randomContext ** ppRandomContext )

Deletes a FIPS186 RNG context.

random.h

Parameters

ppRandomContext Pointer to the location of the context to be deleted.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

random.h

◆ RANDOM_generateASCIIString()

MOC_EXTERN MSTATUS RANDOM_generateASCIIString	(	randomContext *	pRandomContext,
		ubyte *	pBuffer,
		ubyte4	bufferLen
	)

This function is the same as RANDOM_numberGenerator, except all the output will be ASCII characters.

Each byte of output will be a value in the following space.


   numbers     0 - 9    0x30 - 0x39
   upper-case  A - Z    0x41 - 0x5a
   lower-case  a - z    0x61 - 0x7a

   62 possible characters

Note: This function will generate numerical values that map to ASCII characters. If you call this function on an EBCDIC platform, you must convert the result to get the actual EBCDIC characters (i.e., map 0x30 to 0xF0, 0x41 to 0xC1, and so on).

The caller supplies a randomContext. If you called MOCANA_initMocana, you can pass in g_pRandomContext. If you did not call MOCANA_initMocana, you can call RANDOM_acquireContext to get one.

The caller provides the buffer into which the function will place the random characters. The caller also specifies how many random ASCII bytes to generate.

Parameters

[in]	pRandomContext	The random object to use to generate.
[in,out]	pBuffer	The buffer into which the function will deposit the random ASCII characters.
[in]	bufferLen	The number of bytes to generate.

Returns: An MSTATUS, which is an integer type, OK = 0 for no error, or a non-zero error code. See common/merrors.h for more info on the possible values.

◆ RANDOM_getAutoSeedBytes()

MOC_EXTERN MSTATUS RANDOM_getAutoSeedBytes	(	ubyte *	pSeedBytes,
		ubyte4	numBytes
	)

Parameters

pSeedBytes	Pointer to caller allocated buffer that will recieve the computed entropy bytes.
numBytes	Number of bytes to collect, must be a multiple of 8 between 8 and 64.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Flags

To enable this function, the following flag must not be defined

__DISABLE_MOCANA_RNG__

Example: MSTATUS status = OK;
ubyte entropy[48] = {0};
status = RANDOM_getAutoSeedBytes(entropy, 48);
if (OK != status)
goto exit;
. . .
exit:
return status;

◆ RANDOM_getEntropySource()

MOC_EXTERN ubyte RANDOM_getEntropySource ( void )

Gets the global entropy source flag.

random.h

Returns: returns the globally stored entropy source flag ENTROPY_SRC_EXTERNAL or ENTROPY_SRC_INTERNAL.

random.h

◆ RANDOM_isMocSymContext()

MOC_EXTERN MSTATUS RANDOM_isMocSymContext	(	randomContext **	ppRandomContext,
		intBoolean *	pIsMocSym
	)

This function takes a pointer to a randomContext pointer, determines if it refers to a MocSym random implementation, and stores the result in the boolean pointed to by the second parameter.

Parameters

ppRandomContext	Pointer to a randomContext pointer.
pIsMocSym	Pointer to a intBoolean that will recieve the result.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Flags

To enable this function, the following flag must be defined

__ENABLE_MOCANA_SYM__

To enable this function, the following flag must not be defined

__DISABLE_MOCANA_RNG__

Example: MSTATUS status = OK;
intBoolean isMocSymRand = FALSE;
status = RANDOM_isMocSymContext(&g_pRandomContext, &isMocSymRand);
if (OK != status)
goto exit;
if (isMocSymRand == TRUE)
{
. . .
}
. . .
exit:
return status;

◆ RANDOM_launchAutoSeed()

MOC_EXTERN MSTATUS RANDOM_launchAutoSeed ( randomContext * pCtx )

Launch the automatic entropy collection to gather seed material, then use that material to seed the random context.

Parameters

pCtx	Pointer to an allocated random context.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

Flags

To enable this function, the following flag must not be defined

__DISABLE_MOCANA_RNG__

◆ RANDOM_newFIPS186Context()

MOC_EXTERN MSTATUS RANDOM_newFIPS186Context	(	randomContext **	ppRandomContext,
		ubyte	b,
		const ubyte	pXKey[],
		sbyte4	seedLen,
		const ubyte	pXSeed[]
	)

This function generates a FIPS-specific RNG context data structure, using the provided seed.

Warning: Your application must successfully call this function before calling any other function in the random.h header file.

random.h

There are no flag dependencies to enable this function.

Parameters

ppRandomContext	Pointer to address of RNG context.
b	Number of bytes in the X key (`pXKey`).
pXKey	X key value.
seedLen	Number of bytes in the X seed (`pXSeed`).
pXSeed	X seed value.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

random.h

◆ RANDOM_numberGenerator()

MOC_EXTERN MSTATUS RANDOM_numberGenerator	(	randomContext *	pRandomContext,
		ubyte *	pBuffer,
		sbyte4	bufSize
	)

This function generates a specified number of random bits, which can be used as needed by your application code.

Warning: To avoid buffer overflow, be sure that the buffer pointed to by the pBuffer parameter is at least bufSize bytes long.

random.h

There are no flag dependencies to enable this function.

Parameters

pRandomContext	Pointer to RNG context.
pBuffer	Pointer to buffer at least `bufSize` bytes long in which to store the generated random bytes.
bufSize	Number of random bytes to return.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

random.h

◆ RANDOM_numberGeneratorAdd()

MOC_EXTERN MSTATUS RANDOM_numberGeneratorAdd	(	randomContext *	pRandomContext,
		ubyte *	pRetRandomBytes,
		ubyte4	numRandomBytes,
		ubyte *	pAdditionalData,
		ubyte4	additionalDataLen
	)

Parameters

pRandomContext	Random context to use for generation.
pRetRandomBytes	Buffer to place the generated bytes.
numRandomBytes	Number of random bytes to generate.
pAdditionalData	Optional additional data.
additionalDataLen	Length in bytes of the additional data.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ RANDOM_numberGeneratorFIPS186()

MOC_EXTERN MSTATUS RANDOM_numberGeneratorFIPS186	(	randomContext *	pRandomContext,
		ubyte *	pRetRandomBytes,
		sbyte4	numRandomBytes
	)

This function generates a specified number of random bits via FIPS188, which can be used as needed by your application code.

Warning: To avoid buffer overflow, be sure that the buffer pointed to by the pRetRandomBytes parameter is at least numRandomBytes bytes long.

random.h

There are no flag dependencies to enable this function.

Parameters

pRandomContext	Pointer to a FIPS186 RNG context.
pRetRandomBytes	Pointer to buffer at least `numRandomBytes` bytes long in which to store the generated random bytes.
numRandomBytes	Number of random bytes to return.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

random.h

◆ RANDOM_releaseContext()

MOC_EXTERN MSTATUS RANDOM_releaseContext ( randomContext ** pp_randomContext )

This function deletes an RNG (random number generator) context and frees associated memory. To avoid memory leaks, your application must call this function.

There are no flag dependencies to enable this function.

random.h

Parameters

pp_randomContext Pointer to RNG context pointer to free and delete.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

random.h

◆ RANDOM_reseedContext()

MOC_EXTERN MSTATUS RANDOM_reseedContext	(	randomContext *	pCtx,
		ubyte *	pEntropy,
		ubyte4	entropyLen,
		ubyte *	pAdditionalData,
		ubyte4	additionalDataLen
	)

This function will reseed the provided random context. If the underlying context does not accept direct entropy material for reseeding (ie, uses a previously established function pointer for entropy collection), then the entropy bytes will be unused.

Parameters

pCtx	The random context to reseed.
pEntropy	Entropy input to use for the reseeding. May be NULL if the underlying random object does not accept direct entropy injection.
entropyLen	Length in bytes of the entropy material.
pAdditionalData	Optional additional data.
additionalDataLen	Length in bytes of the additional data.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ RANDOM_rngFun()

MOC_EXTERN sbyte4 RANDOM_rngFun	(	void *	rngFunArg,
		ubyte4	length,
		ubyte *	buffer
	)

This function generates a random number. (This function provides a common prototype, or wrapper, around the random number generator function — typically the NanoCrypto RANDOM_numberGenerator() function.)

See also: RANDOM_numberGenerator()

random.h

There are no flag dependencies to enable this function.

Parameters

rngFunArg	Pointer to RNG function argument.
length	Number of bytes in the output buffer, `buffer`.
buffer	Pointer to buffer in which to store the resultant random number.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

random.h

◆ RANDOM_seedFIPS186Context()

MOC_EXTERN MSTATUS RANDOM_seedFIPS186Context	(	randomContext *	pRandomCtx,
		ubyte *	seed,
		ubyte4	seedLen
	)

Parameters

pRandomCtx	Pointer to a previously allocated random context.
seed	Pointer to a buffer containing the new seed material.
seedLen	Length in bytes of the new seed material, must be between 20 and 64 bytes.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ RANDOM_seedFromDevURandom()

MOC_EXTERN MSTATUS RANDOM_seedFromDevURandom	(	randomContext *	pCtx,
		ubyte4	numBytes
	)

Parameters

pCtx	Pointer to the random context being seeded.
numBytes	Number of bytes of seed material to collect. Must be <= 64.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

◆ RANDOM_seedOldRandom()

MOC_EXTERN MSTATUS RANDOM_seedOldRandom	(	randomContext *	pCtx,
		ubyte *	pSeedBytes,
		ubyte4	seedLen
	)

This function will seed the random context implementation pointed to by pWrap with the bytes provided in the pSeedBytes buffer. Currently there are only two random context implementations that are not MocSym Operators, the NIST CTR DRBG and the FIPS186 PRNG. If the random context type is one of those two this function will call the appropriate seed function, otherwise it will return an error.

Parameters

pCtx	Pointer to a previously allocated randomContext.
pSeedBytes	Pointer to buffer which contains new seed material.
seedLen	Length in bytes of the seed material.

◆ RANDOM_setEntropySource()

MOC_EXTERN MSTATUS RANDOM_setEntropySource ( ubyte EntropySrc )

Sets the global entropy source flag.

random.h

There are no flag dependencies to enable this function but if + __DISABLE_MOCANA_RAND_ENTROPY_THREADS__ is defined then only the ENTROPY_SRC_EXTERNAL flag is allowed.

Parameters

EntropySrc The input flag. This is either ENTROPY_SRC_EXTERNAL, or if internal entropy is not disabled, ENTROPY_SRC_INTERNAL.

Returns: OK (0) if successful; otherwise a negative number error code definition from merrors.h. To retrieve a string containing an English text error identifier corresponding to the function's returned error status, use the DISPLAY_ERROR macro.

random.h

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ RNGFun

Function Documentation

◆ GetNullPersonalizationString()

◆ RANDOM_acquireContext()

◆ RANDOM_addEntropyBit()

◆ RANDOM_deleteFIPS186Context()

◆ RANDOM_generateASCIIString()

◆ RANDOM_getAutoSeedBytes()

◆ RANDOM_getEntropySource()

◆ RANDOM_isMocSymContext()

◆ RANDOM_launchAutoSeed()

◆ RANDOM_newFIPS186Context()

◆ RANDOM_numberGenerator()

◆ RANDOM_numberGeneratorAdd()

◆ RANDOM_numberGeneratorFIPS186()

◆ RANDOM_releaseContext()

◆ RANDOM_reseedContext()

◆ RANDOM_rngFun()

◆ RANDOM_seedFIPS186Context()

◆ RANDOM_seedFromDevURandom()

◆ RANDOM_seedOldRandom()

◆ RANDOM_setEntropySource()