RNG.h

Go to the documentation of this file.

/*
 * Copyright (c) 2021-2022, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       RNG.h
 *
 *  @brief      RNG driver header
 *
 *  @anchor ti_drivers_RNG_Overview
 *  # Overview #
 *  The Random Number Generator (RNG) module generates random data of variable
 *  lengths from a pool of entropy. The pool of entropy is maintained by the
 *  driver using implementation-specific sources of entropy.
 *  The output is suitable for applications requiring cryptographically
 *  random data such as keying material for private or symmetric keys.
 *
 *  @anchor ti_drivers_RNG_Usage
 *  # Usage #
 *
 *  ## Initialization ##
 *  Unlike most drivers, there is a global instance of RNG driver data
 *  that is always available once #RNG_init() is called. This data will contain
 *  the entropy pool and any needed state information required to refill the
 *  pool. #RNG_init() should be called once before using other RNG
 *  driver APIs.
 *
 *  @note Some implementations restrict when RNG_init() may be called.
 *        Check the implementation's documentation for more information.
 *
 *  ## Before starting a RNG operation ##
 *
 *  Before starting a RNG operation, the application must do the following:
 *      - Call RNG_init() to initialize the driver's global instance data.
 *      - Call RNG_Params_init() to initialize the RNG_Params to default values.
 *      - Modify the RNG_Params as desired.
 *      - Call RNG_open() to open an instance of the driver.
 *
 *  @note Some implementations restrict when RNG_init() may be called.
 *        Check the implementation's documentation for more information.
 *
 *  ## Entropy Pool Management ##
 *
 *  At any time after calling RNG_init(), the application may call
 *  RNG_fillPoolIfLessThan() to add entropy to the pool which will then make
 *  future requests for entropy execute faster. Note that the driver never
 *  automatically refills the pool. However, if the pool is empty, the RNG
 *  driver will still generate entropy upon request (for example when
 *  RNG_getRandomBits() is called).
 *
 *  The application is responsible for deciding when it is appropriate to
 *  spend the time and energy to refill the pool. One suggested location
 *  to do so is the idle thread.
 *
 *  ## RNG operations ##
 *
 *  Use RNG_getRandomBits() to obtain random bits from the entropy pool and
 *  copy them to a buffer/array. The caller must allocate memory sufficient
 *  to hold at least the number of bits of random data requested.
 *
 *  ## After the RNG operation completes ##
 *
 *  After the RNG operation completes, the application should either start
 *  another operation or close the driver by calling RNG_close(). Note that the
 *  singleton instance of the driver, along with its associated pool of entropy
 *  will still exist and will be used by any future RNG_open() calls. Note that
 *  closing the driver instance may not be strictly required, but is good
 *  practice.
 *
 *  ## Security ##
 *
 *  ### Data Protection ###
 *
 *  The entropy pool and any required state to generate more entropy is
 *  maintained in memory, in the driver's global instance data. The entirety of
 *  this data is stored in two global variables called RNG_instanceData and
 *  RNG_instancePool. It is up to the system to provide adequate
 *  protection (primarily confidentiality and integrity) of these in-memory
 *  assets.
 *
 *  ### Timing Side Channels ###
 *
 *  Functions which provide for generation of a value within a range use
 *  an algorithm which is timing-constant when the following parameters
 *  are held constant: lowerLimit, upperLimit, bitLength,
 *  and endianess. Thus, while the driver may create multiple candidates for the
 *  value to find one within the range, timing will not leak the final
 *  value's relation to the limits. However, timing may leak the bitLength,
 *  the endianess, and the use of #CryptoUtils_limitZero, #CryptoUtils_limitOne,
 *  or NULL for the limit values.
 *
 *  @anchor ti_drivers_RNG_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_RNG_Synopsis_Code
 *  ### Generate random bytes to a user provided buffer #
 *
 *  @code
 *
 *  #include <ti/drivers/RNG.h>
 *  #include "ti_drivers_config.h"
 *
 *  // Setup RNG
 *  RNG_Init();
 *  RNG_fillPoolIfLessThan(RNG_POOL_BYTE_SIZE);
 *
 *  // Use RNG
 *  #define RANDOM_BYTES_SIZE 16u
 *  RNG_Handle handle;
 *  int_fast16_t result;
 *
 *  uint8_t randomBytesArray[RANDOM_BYTES_SIZE] = {0};
 *
 *  handle = RNG_open(0, NULL);
 *
 *  if (!handle) {
 *      // Handle error
 *      while(1);
 *  }
 *
 *  result = RNG_getRandomBits(handle, randomBytesArray, RANDOM_BYTES_SIZE * 8);
 *
 *  if (result != RNG_STATUS_SUCCESS) {
 *      // Handle error
 *      while(1);
 *  }
 *
 *  RNG_close(handle);
 *
 *  // Refill RNG Pool when convenient
 *  RNG_fillPoolIfLessThan(RNG_POOL_BYTE_SIZE);
 *  @endcode
 *
 *  @anchor ti_drivers_RNG_Examples
 *  ## Examples
 *
 *  The following examples do not show the process of initializing the RNG
 *  module and refilling the pool.
 *  See @ref ti_drivers_RNG_Synopsis RNG Driver Synopsis for an example
 *  showing those parts of RNG operation. *
 *
 *  ### Generate a number within a range ###
 *
 *  @code
 *
 *  #include <ti/drivers/RNG.h>
 *
 *  #define RANDOM_BIT_SIZE  15u
 *  #define RANDOM_BYTE_SIZE ((RANDOM_BIT_SIZE + 7u)/8u)
 *
 *  RNG_Handle handle;
 *  int_fast16_t result;
 *
 *  uint8_t randomBytesArray[RANDOM_BYTES_SIZE] = {0};
 *  uint8_t upperLimit[RANDOM_BYTES_SIZE] = {0xA9, 0x61}; // 25,001, LE format
 *
 *  handle = RNG_open(0, NULL);
 *
 *  if (!handle) {
 *      // Handle error
 *      while(1);
 *  }
 *
 *  // Generate a number from 1 to 25,000 (inclusive)
 *  // Note that lowerLimit parameter is inclusive and upperLimit is
 *  // exclusive. Thus, upperLimit is set to 25,001.
 *  result = RNG_getLERandomNumberInRange(RNG_Handle handle, RNG_limitOne,
 *                                        upperLimit, randomBytesArray,
 *                                        RANDOM_BIT_SIZE);
 *
 *
 *  if (result != RNG_STATUS_SUCCESS) {
 *      // Handle error
 *      while(1);
 *  }
 *
 *  RNG_close(handle);
 *
 *  @endcode
 *
 *
 *  ### Generate an ECC private key ###
 *
 *  @code
 *
 *  #include <ti/drivers/RNG.h>
 *  #include <ti/drivers/cryptoutils/ecc/ECCParams.h>
 *
 *  // Values are chosen to generate a NIST 256 bit key.
 *  CryptoKey privateKey;
 *  uint8_t privateKeyingMaterial[NISTP256_PARAM_SIZE_BYTES];
 *  RNG_Handle handle;
 *  int_fast16_t result;
 *
 *  handle = RNG_open(0, NULL);
 *
 *  if (!handle) {
 *      // Handle error
 *      while(1);
 *  }
 *
 *  CryptoKeyPlaintext_initBlankKey(&privateKey, privateKeyingMaterial,
 *                                  ECCParams_NISTP256.length);
 *
 *  // Generate NIST 256 bit key in BE format.
 *  result = RNG_generateBEKeyInRange(RNG_Handle handle, RNG_limitOne,
 *                                    ECCParams_NISTP256.order, privateKey,
 *                                    256);
 *
 *
 *  if (result != RNG_STATUS_SUCCESS) {
 *      // Handle error
 *      while(1);
 *  }
 *
 *  RNG_close(handle);
 *
 *  @endcode
 *
 */

#ifndef ti_drivers_RNG__include
#define ti_drivers_RNG__include

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>

#ifdef __cplusplus
extern "C" {
#endif

#define RNG_STATUS_RESERVED (-32)

#define RNG_STATUS_SUCCESS ((int_fast16_t)0)

#define RNG_STATUS_ERROR ((int_fast16_t)-1)

#define RNG_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2)

#define RNG_STATUS_INVALID_INPUTS ((int_fast16_t)-3)

#define RNG_STATUS_CANCELED ((int_fast16_t)-4)

#define RNG_ENTROPY_EXHAUSTED ((int_fast16_t)-5)

#define RNG_STATUS_INIT_NOT_ALLOWED ((int_fast16_t)-6)

#define RNG_MAX_BIT_LENGTH ((size_t)1u << 20u) /* 1 MiB */

typedef struct
{
    void *object;

    void const *hwAttrs;
} RNG_Config;

typedef const RNG_Config *RNG_Handle;

typedef enum
{
    RNG_RETURN_BEHAVIOR_CALLBACK = 1, 
    RNG_RETURN_BEHAVIOR_BLOCKING = 2, 
    RNG_RETURN_BEHAVIOR_POLLING  = 4, 
} RNG_ReturnBehavior;

typedef void (*RNG_CryptoKeyCallbackFxn)(RNG_Handle handle, int_fast16_t returnValue, CryptoKey *key);

typedef void (*RNG_RandomBitsCallbackFxn)(RNG_Handle handle,
                                          int_fast16_t returnValue,
                                          uint8_t *randomBits,
                                          size_t randomBitsLength);

typedef struct
{
    RNG_ReturnBehavior returnBehavior;               
    RNG_CryptoKeyCallbackFxn cryptoKeyCallbackFxn;   
    RNG_RandomBitsCallbackFxn randomBitsCallbackFxn; 
    uint32_t timeout;                                
} RNG_Params;

extern const RNG_Params RNG_defaultParams;

extern const size_t RNG_poolByteSize;

int_fast16_t RNG_init(void);

int_fast16_t RNG_fillPoolIfLessThan(size_t bytes);

void RNG_Params_init(RNG_Params *params);

RNG_Handle RNG_open(uint_least8_t index, const RNG_Params *params);

void RNG_close(RNG_Handle handle);

int_fast16_t RNG_getRandomBits(RNG_Handle handle, void *randomBits, size_t randomBitsLength);

int_fast16_t RNG_getLERandomNumberInRange(RNG_Handle handle,
                                          const void *lowerLimit,
                                          const void *upperLimit,
                                          void *randomNumber,
                                          size_t randomNumberBitLength);

int_fast16_t RNG_getBERandomNumberInRange(RNG_Handle handle,
                                          const void *lowerLimit,
                                          const void *upperLimit,
                                          void *randomNumber,
                                          size_t randomNumberBitLength);

int_fast16_t RNG_generateKey(RNG_Handle handle, CryptoKey *key);

int_fast16_t RNG_generateLEKeyInRange(RNG_Handle handle,
                                      const void *lowerLimit,
                                      const void *upperLimit,
                                      CryptoKey *key,
                                      size_t randomNumberBitLength);

int_fast16_t RNG_generateBEKeyInRange(RNG_Handle handle,
                                      const void *lowerLimit,
                                      const void *upperLimit,
                                      CryptoKey *key,
                                      size_t randomNumberBitLength);

RNG_Handle RNG_construct(const RNG_Config *config, const RNG_Params *params);

int_fast16_t RNG_cancelOperation(RNG_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_RNG__include */