Provides common Mocana functions used by NanoTAP components. More...

Functions
MOC_EXTERN const ubyte *	MERROR_lookUpErrorCode (MSTATUS errorCode)

MOC_EXTERN sbyte4	MOCANA_addEntropy32Bits (ubyte4 entropyBits)
	Add 32 random bits to application's random number generator. More...

MOC_EXTERN sbyte4	MOCANA_appendFile (const char pFilename, const ubyte pBuffer, ubyte4 bufLength)
	Appends a buffer's contents to a file, file is created if it does not exist. More...

MOC_EXTERN sbyte4	MOCANA_freeMocana (void)
	Release memory allocated by MOCANA_initMocana. More...

MOC_EXTERN sbyte4	MOCANA_freeReadFile (ubyte **ppRetBuffer)
	Release memory allocated by MOCANA_readFile(). More...

MOC_EXTERN sbyte4	MOCANA_initLog (logFn lFn)
	Register a callback function for the Digicert logging system. More...

MOC_EXTERN sbyte4	MOCANA_initMocana (void)
	Initialize Digicert common code base. More...

MOC_EXTERN sbyte4	MOCANA_readFile (const char pFilename, ubyte ppRetBuffer, ubyte4 pRetBufLength)
	Allocate a buffer and fill with data read from a file. More...

MOC_EXTERN sbyte4	MOCANA_writeFile (const char pFilename, const ubyte pBuffer, ubyte4 bufLength)
	Write a buffer's contents to a file. More...

Detailed Description

Function Documentation

◆ MERROR_lookUpErrorCode()

MOC_EXTERN const ubyte* MERROR_lookUpErrorCode ( MSTATUS errorCode )

Function to return a string description for the given errorCode

Parameters

[in] errorCode - MSTATUS

Returns: String containing error code description on success; NULL if error code not found

Note: See merrors.h for list of all error codes.

◆ MOCANA_addEntropy32Bits()

MOC_EXTERN sbyte4 MOCANA_addEntropy32Bits ( ubyte4 entropyBits )

This function adds 32 random bits to your application's random number generator. Before calling this function, your application should have already initialized the Digicert common code base by calling MOCANA_initMocana().

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

__DISABLE_MOCANA_ADD_ENTROPY__

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.

Parameters

[in] entropyBits 32-bit integer used to add randomness to your application's cryptography.

sbyte4 status = 0;
ubyte4 ebit;
status = MOCANA_addEntropy32Bits(ebit);

◆ MOCANA_appendFile()

MOC_EXTERN sbyte4 MOCANA_appendFile	(	const char *	pFilename,
		const ubyte *	pBuffer,
		ubyte4	bufLength
	)

This function appends a data buffer's contents to a file.

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

__DISABLE_MOCANA_FILE_SYSTEM_HELPER__

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.

Parameters

[in]	pFilename	Pointer to name of the file to write to.
[in]	pBuffer	Pointer to buffer containing data to write to the file.
[in]	bufLength	Number of bytes in `pBuffer`.

sbyte4 status = 0;

status = MOCANA_writeFile(CERTIFICATE_DER_FILE, pCertificate, retCertLength);

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform code.

◆ MOCANA_freeMocana()

MOC_EXTERN sbyte4 MOCANA_freeMocana ( void )

This function releases memory previously allocated by a call to MOCANA_initMocana().

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

__DISABLE_MOCANA_INIT__

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.

int status = 0;

status = MOCANA_freeMocana();

◆ MOCANA_freeReadFile()

MOC_EXTERN sbyte4 MOCANA_freeReadFile ( ubyte ** ppRetBuffer )

This function releases memory previously allocated by a call to MOCANA_readFile().

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

__DISABLE_MOCANA_FILE_SYSTEM_HELPER__

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.

Parameters

ppRetBuffer Reference to the data buffer to free.

ubyte *pCertificate;
...
status = MOCANA_freeReadFile(&pCertificate);

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform code.

◆ MOCANA_initLog()

MOC_EXTERN sbyte4 MOCANA_initLog ( logFn lFn )

This function registers a callback function for the Digicert SoT Platform logging system.

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

__DISABLE_MOCANA_FILE_SYSTEM_HELPER__

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.

Parameters

[in] lFn Callback function that you want to receive notification of Digicert logging events.

sbyte4 status = 0;

status = MOCANA_initLog(myEventHandler);

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform code.

◆ MOCANA_initMocana()

MOC_EXTERN sbyte4 MOCANA_initMocana ( void )

This is an older function, you should use MOCANA_initialize instead (see initmocana.h).

This function initializes the Digicert common code base; it is typically the first initialization step for any Digicert Security of Things Platform product.

This will also create and seed a pseudo random number generator. There are four ways this PRNG can be seeded.

First, if you do not set any build flags for PRNG seed, the NanoCrypto code will create a PRNG and seed it using the time of day, some "stack state" (whatever happens to be on the stack at the time of execution), along with a set of values derived from thread wait times (our FIPS documentation describes the process and how it produces entropy). This method will take 20 seconds or more to generate the seed material.

Second, if you set the ENABLE_MOCANA_DEV_URANDOM build flag, NanoCrypto will seed using 128 bytes from /dev/urandom and no bytes from stack state.

Third, if you set the DISABLE_MOCANA_RAND_ENTROPY_THREADS build flag, NanoCrypto will not use its thread wait seed collection technique (no 20 second wait).

Fourth, you can always add seed material of your own using RNG_SEED_addEntropyBit, MOCANA_addEntropyBit, or MOCANA_addEntropy32Bits.

The most secure is using the build flag ENABLE_MOCANA_DEV_URANDOM, and not using DISABLE_MOCANA_RAND_ENTROPY_THREADS. But if you do not want to wait for the thread wait algorithm to complete, then you should still use ENABLE_MOCANA_DEV_URANDOM if possible.


   build flags                              NanoCrypto entropy
 ---------------------------------------------------------------
  no build flags                            20 seconds or more
                                            thread wait time
                                            time of day
                                            stack state

  __ENABLE_MOCANA_DEV_URANDOM__             20 seconds or more
                                            thread wait time
                                            time of day
                                            /dev/urandom

  __DISABLE_MOCANA_RAND_ENTROPY_THREADS__   milliseconds
  __ENABLE_MOCANA_DEV_URANDOM__             time of day
                                            /dev/urandom

  __DISABLE_MOCANA_RAND_ENTROPY_THREADS__   milliseconds
                                            time of day
                                            stack state

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

__DISABLE_MOCANA_INIT__

Additionally, whether or not the following flags are defined determines which initialization functions are called:

__DISABLE_MOCANA_RAND_ENTROPY_THREADS__
__ENABLE_MOCANA_DEV_URANDOM__
__DISABLE_MOCANA_STARTUP_GUARD__
__ENABLE_MOCANA_DEBUG_CONSOLE__
__ENABLE_MOCANA_DTLS_CLIENT__
__ENABLE_MOCANA_DTLS_SERVER__
__ENABLE_MOCANA_IKE_SERVER__
__ENABLE_MOCANA_PEM_CONVERSION__
__ENABLE_MOCANA_PKCS10__
__ENABLE_MOCANA_RADIUS_CLIENT__
__ENABLE_MOCANA_SSH_SERVER__
__KERNEL__
UDP_init

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.

sbyte4 status = 0;

status = MOCANA_initMocana();

◆ MOCANA_readFile()

MOC_EXTERN sbyte4 MOCANA_readFile	(	const char *	pFilename,
		ubyte **	ppRetBuffer,
		ubyte4 *	pRetBufLength
	)

This function allocates a buffer and then fills it with data read from a file.

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

__DISABLE_MOCANA_FILE_SYSTEM_HELPER__

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.

Parameters

[in]	pFilename	Name of the file from which to read.
[out]	ppRetBuffer	Reference to the pointer to a data buffer containing data read from the file.
[out]	pRetBufLength	Reference to length of the data buffer in bytes.

sbyte4 status;
ubyte *pCertificate = NULL;
ubyte4 retCertLength = 0;
if (0 > (status = MOCANA_readFile(CERTIFICATE_DER_FILE, &pCertificate, &retCertLength)))
    goto exit;

Memory allocated b this function must be freed by a subsequent call to MOCANA_freeReadFile().

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform code.

◆ MOCANA_writeFile()

MOC_EXTERN sbyte4 MOCANA_writeFile	(	const char *	pFilename,
		const ubyte *	pBuffer,
		ubyte4	bufLength
	)

This function writes a data buffer's contents to a file.

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

__DISABLE_MOCANA_FILE_SYSTEM_HELPER__

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.

Parameters

[in]	pFilename	Pointer to name of the file to write to.
[in]	pBuffer	Pointer to buffer containing data to write to the file.
[in]	bufLength	Number of bytes in `pBuffer`.

sbyte4 status = 0;

status = MOCANA_writeFile(CERTIFICATE_DER_FILE, pCertificate, retCertLength);

Remarks: This is a convenience function provided for your application's use; it is not used by Digicert SoT Platform code.

Functions

Detailed Description

Function Documentation

◆ MERROR_lookUpErrorCode()

◆ MOCANA_addEntropy32Bits()

◆ MOCANA_appendFile()

◆ MOCANA_freeMocana()

◆ MOCANA_freeReadFile()

◆ MOCANA_initLog()

◆ MOCANA_initMocana()

◆ MOCANA_readFile()

◆ MOCANA_writeFile()