MCCI TweetNaCl
TweetNaCl library adapted for embedded use
+ Collaboration diagram for Framework:

Typedefs

typedef mcci_tweetnacl_randombytes_error_t() mcci_tweetnacl_randombytes_fn_t(mcci_tweetnacl_randombytes_handle_t hDriver, unsigned char *pOutBuffer, size_t nBuffer)
 symbolic type for function implementing local random-number generator More...
 
typedef struct mcci_tweetnacl_randombytes_driver_s * mcci_tweetnacl_randombytes_handle_t
 abstract type for randombytes driver context More...
 
typedef int mcci_tweetnacl_result_t
 symbolic type for result of TweetNaCl primitives More...
 

Enumerations

enum  mcci_tweetnacl_randombytes_error_t {
  MCCI_TWEETNACL_RANDOMBYTES_ERROR_SUCCESS = 0, MCCI_TWEETNACL_RANDOMBYTES_ERROR_UNKNOWN = 1, MCCI_TWEETNACL_RANDOMBYTES_ERROR_NOT_INITIALIZED = 2, MCCI_TWEETNACL_RANDOMBYTES_ERROR_INVALID_PARAMETER = 3,
  MCCI_TWEETNACL_RANDOMBYTES_ERROR_CRYPTO_API_FAILED = 4
}
 error codes from mcci_tweetnacl_randombytes_fn_t implementations errors More...
 
enum  mcci_tweetnacl_result_e { MCCI_TWEETNACL_RESULT_SUCCESS, MCCI_TWEETNACL_RESULT_FAILED = -1 }
 result codes for TweetNaCl primitives More...
 

Functions

mcci_tweetnacl_result_t mcci_tweetnacl_configure_randombytes (mcci_tweetnacl_randombytes_fn_t *pRandomBytesFn, mcci_tweetnacl_randombytes_handle_t hDriver)
 setup the random number generator connection More...
 
void mcci_tweetnacl_hal_randombytes (unsigned char *pBuffer, unsigned long long nBuffer)
 generate stream of random bytes More...
 
mcci_tweetnacl_randombytes_error_t mcci_tweetnacl_hal_randombytes_getlasterror (void)
 Get the last error reported in the randombytes() mechanism. More...
 
void mcci_tweetnacl_hal_randombytes_setlasterror (mcci_tweetnacl_randombytes_error_t lastError)
 Change the last error cell for the randombytes() mechanism. More...
 
static bool mcci_tweetnacl_result_is_success (mcci_tweetnacl_result_t resultCode)
 check whether an API result code indicates succcess More...
 

Detailed Description

Typedef Documentation

◆ mcci_tweetnacl_randombytes_fn_t

typedef mcci_tweetnacl_randombytes_error_t() mcci_tweetnacl_randombytes_fn_t(mcci_tweetnacl_randombytes_handle_t hDriver, unsigned char *pOutBuffer, size_t nBuffer)

symbolic type for function implementing local random-number generator

Parameters
[in]hDriveris the driver handle supplied to MCCI TweetNaCl at initialization.
[out]pOutBufferpoints to the buffer to be filled
[in]nBufferspecifies the size of pOutBuffer.
Returns
error code; 0 for success, non-zero for failure.
Note
This function must provide a cryptographically strong RNG. If not provided, mcci_tweetnacl_sign_keypair() and mcci_tweetnacl_box_kaypair() will not be available.

Definition at line 130 of file mcci_tweetnacl.h.

◆ mcci_tweetnacl_randombytes_handle_t

typedef struct mcci_tweetnacl_randombytes_driver_s* mcci_tweetnacl_randombytes_handle_t

abstract type for randombytes driver context

This abstract type simply is passed through unmodified, and may be used for any needed dynamic context for the random bytes implementation.

Definition at line 60 of file mcci_tweetnacl.h.

◆ mcci_tweetnacl_result_t

symbolic type for result of TweetNaCl primitives

NaCl and TweetNaCl primitives generally return 0 for success, and non-zero (generally -1) for failures. We formerly converted to boolean as part of the API wrapper, but this proved to be a bad idea; the wrappers are too close to the underlying primitives. Now we return the same value returned by the primitive, but we use a typedef for clarity.

See also
mcci_tweetnacl_result_is_success()
mcci_tweetnacl_result_e

Definition at line 92 of file mcci_tweetnacl.h.

Enumeration Type Documentation

◆ mcci_tweetnacl_randombytes_error_t

error codes from mcci_tweetnacl_randombytes_fn_t implementations errors

Enumerator
MCCI_TWEETNACL_RANDOMBYTES_ERROR_SUCCESS 

success (not an error)

MCCI_TWEETNACL_RANDOMBYTES_ERROR_UNKNOWN 

bad param to mcci_tweetnacl_hal_randombytes_raise()

MCCI_TWEETNACL_RANDOMBYTES_ERROR_NOT_INITIALIZED 

random number driver not intialized

MCCI_TWEETNACL_RANDOMBYTES_ERROR_INVALID_PARAMETER 

invalid parameter

MCCI_TWEETNACL_RANDOMBYTES_ERROR_CRYPTO_API_FAILED 

the related crypto API failed

Definition at line 67 of file mcci_tweetnacl.h.

◆ mcci_tweetnacl_result_e

result codes for TweetNaCl primitives

We define symbolic constants for success and the typical failure code. Note, however, that any non-zero value is a failure; codes should be tested using mcci_tweetnacl_result_is_success(), not by direct comparison. These codes should be used in return statements and other contexts where a result code is prepared, but not to analyze results.

See also
mcci_tweetnacl_result_t
Enumerator
MCCI_TWEETNACL_RESULT_SUCCESS 

API succeeded.

MCCI_TWEETNACL_RESULT_FAILED 

API failed.

Definition at line 109 of file mcci_tweetnacl.h.

Function Documentation

◆ mcci_tweetnacl_configure_randombytes()

mcci_tweetnacl_result_t mcci_tweetnacl_configure_randombytes ( mcci_tweetnacl_randombytes_fn_t pRandomBytesFn,
mcci_tweetnacl_randombytes_handle_t  hDriver 
)

setup the random number generator connection

Parameters
[in]pRandomBytesFnpoints to the function to be called by randombytes.
[in]hDriveris an optional driver handle to be passed to the random byte generator.
Returns
true if the random number generator was set, false if the driver could not be established.

◆ mcci_tweetnacl_hal_randombytes()

void mcci_tweetnacl_hal_randombytes ( unsigned char *  pBuffer,
unsigned long long  nBuffer 
)

generate stream of random bytes

Parameters
[out]pBufferpointer to buffer to be filled
[in]nBuffernumber of bytes in buffer to be filled.
Note
This must return cryptographically random numbers; don't try to use your own RNG unless you've tested extensively.
If the RNG can't generate a suitable value, the default implementation will use longjmp() to bail out. This means that this function can't be used directly by clients.

◆ mcci_tweetnacl_hal_randombytes_getlasterror()

mcci_tweetnacl_randombytes_error_t mcci_tweetnacl_hal_randombytes_getlasterror ( void  )

Get the last error reported in the randombytes() mechanism.

Returns
last error code posted.
Note
The client must explicity call mcci_tweetnacl_hal_randombytes_setlasterror() to clear the last error if desired.
See also
mcci_tweetnacl_hal_randombytes_setlasterror()

◆ mcci_tweetnacl_hal_randombytes_setlasterror()

void mcci_tweetnacl_hal_randombytes_setlasterror ( mcci_tweetnacl_randombytes_error_t  lastError)

Change the last error cell for the randombytes() mechanism.

See also
mcci_tweetnacl_hal_randombytes_getlasterror()

◆ mcci_tweetnacl_result_is_success()

static bool mcci_tweetnacl_result_is_success ( mcci_tweetnacl_result_t  resultCode)
inlinestatic

check whether an API result code indicates succcess

Parameters
[in]resultCode
Returns
true if result code indicates success, false otherwise.

Definition at line 153 of file mcci_tweetnacl.h.