AESCTRDRBG.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019, 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       AESCTRDRBG.h
 *
 * @brief      AESCTRDRBG driver header
 *
 * @warning    This is a beta API. It may change in future releases.
 *
 * @anchor ti_drivers_AESCTRDRBG_Overview
 * <h3> Overview </h3>
 * AES_CTR_DRBG is a cryptographically secure deterministic random bit generator
 * that is used to efficiently generate random numbers for use in keying material
 * or other security related purposes. It is based on the AES block cipher
 * operating in Counter (CTR) mode and is defined by NIST SP 800-90A.
 *
 * AES_CTR_DRBG derives a sequence of pseudo-random numbers based on an initial
 * secret seed and additional, non-secret personalization data provided during
 * instantiation. A sequence of random bits generated by AES_CTR_DRBG will have
 * an equivalent entropy content of MIN(sequenceLength, security strength).
 * The security strength is based on the seed length and the AES key length used
 * in the AES_CTR_DRBG instance.
 *
 * |                                       | AES-128 | AES-192 | AES-256 |
 * |---------------------------------------|---------|---------|---------|
 * | Security Strength (bits)              | 128     | 192     | 256     |
 * | Seed Length (bits)                    | 192     | 320     | 384     |
 * | Personalization String Length (bits)  | <= 192  | <= 320  | <= 384  |
 * | Max Requests Between Reseeds          | 2^48    | 2^48    | 2^48    |
 * | Max Request Length (bits)             | 2^19    | 2^19    | 2^19    |
 *
 * <h3> Security Strength </h3>
 * The seed must be sourced from a cryptographically secure source such as
 * a true random number generator and contain seed length bits of entropy.
 * Since the seed length is always larger than the security strength for
 * any one AES key length, the output of one AES_CTR_DRBG instance may not
 * be used to seed another instance of the same or higher security strength.
 *
 * <h3> Reseeding </h3>
 * Because of the way AES CTR operates, there are a limited number of output
 * bitstreams that may be generated before the AES_CTR_DRBG instance must be
 * reseeded. The time between reseeding is set by the number of random bit
 * sequences generated not by their individual or combined lengths. Each time
 * random bits are requested of the AES_CTR_DRBG instance by the application,
 * the reseed counter is incremented by one regardless of how many bits at a
 * time are requested. When this counter reaches the configured reseed limit,
 * the AES_CTR_DRBG instance will return #AESCTRDRBG_STATUS_RESEED_REQUIRED
 * until it is reseeded.
 *
 * The maximum permitted number of requests between reseeds is 2^48.
 * The default counter is only 2^32 long for ease of implementation.
 * A more conservative reseed limit may be configured by the application
 * for increased security.
 *
 * A previously used seed may never be reused to reseed an AESCTRDRBG instance.
 * The seed used to instantiate or reseed an instance must be generated by
 * an approved entropy source and never be reused.
 *
 * <h3> Derivation Function </h3>
 * NIST specifies the the use of an optional derivation function to reduced
 * enctropy and personalizationg string lengths longer than the seed
 * length down to the seed length. This feature is not presently supported.
 *
 * @anchor ti_drivers_AESCTRDRBG_Usage
 * <h3> Usage </h3>
 *
 * This documentation provides a basic @ref ti_drivers_AESCTRDRBG_Synopsis
 * "usage summary" and a set of @ref ti_drivers_AESCTRDRBG_Examples "examples"
 * in the form of commented code fragments. Detailed descriptions of the
 * APIs are provided in subsequent sections.
 *
 * @anchor ti_drivers_AESCTRDRBG_Synopsis
 * <h3> Synopsis </h3>
 * @anchor ti_drivers_AESCTRDRBG_Synopsis_Code
 * @code
 *     #include <ti/drivers/AESCTRDRBG.h>
 *
 *     AESCTRDRBG_init();
 *
 *     // Instantiate the AESCTRDRBG instance
 *     AESCTRDRBG_Params_init(&params);
 *     params.keyLength = AESCTRDRBG_AES_KEY_LENGTH_128;
 *     params.reseedInterval = 0xFFFFFFFF;
 *     params.seed = seedBuffer;
 *
 *     handle = AESCTRDRBG_open(0, &params);
 *
 *     result = AESCTRDRBG_getBytes(handle, &resultKey);
 *
 *     reseedResult = AESCTRDRBG_reseed(handle, reseedBuffer, NULL, 0);
 *
 *     AESCTRDRBG_close(handle);
 * @endcode
 *
 * @anchor ti_drivers_AESCTRDRBG_Examples
 * <h3> Examples </h3>
 *
 * <h4> Instantiating an AESCTRDRBG Instance with TRNG </h4>
 * @code
 *
 * #include <ti/drivers/AESCTRDRBG.h>
 * #include <ti/drivers/TRNG.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 *     AESCTRDRBG_Handle handle;
 *     AESCTRDRBG_Params params;
 *     TRNG_Handle trngHandle;
 *     CryptoKey seedKey;
 *     int_fast16_t result;
 *
 *     uint8_t seedBuffer[AESCTRDRBG_SEED_LENGTH_AES_128];
 *
 *     // Generate the seed
 *     trngHandle = TRNG_open(0, NULL);
 *
 *     if (trngHandle == NULL) {
 *         // Handle error
 *         while(1);
 *     }
 *
 *     CryptoKeyPlaintext_initBlankKey(&seedKey, seedBuffer, AESCTRDRBG_SEED_LENGTH_AES_128);
 *
 *     result = TRNG_generateEntropy(trngHandle, &seedKey);
 *     if (result != TRNG_STATUS_SUCCESS) {
 *         // Handle error
 *         while(1);
 *     }
 *
 *     TRNG_close(trngHandle);
 *
 *     // Instantiate the AESCTRDRBG instance
 *     AESCTRDRBG_Params_init(&params);
 *     params.keyLength = AESCTRDRBG_AES_KEY_LENGTH_128;
 *     params.reseedInterval = 0xFFFFFFFF;
 *     params.seed = seedBuffer;
 *
 *     handle = AESCTRDRBG_open(0, &params);
 *     if (handle == NULL) {
 *         // Handle error
 *         while(1);
 *     }
 * @endcode
 *
 * <h4> Generating Random Data with Reseeding </h4>
 *
 * @code
 *
 * #include <ti/drivers/AESCTRDRBG.h>
 * #include <ti/drivers/TRNG.h>
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 *
 * ...
 *
 *     #define ENTROPY_REQUEST_LENGTH 256
 *
 *     AESCTRDRBG_Handle handle;
 *     TRNG_Handle trngHandle;
 *     CryptoKey entropyKey;
 *     int_fast16_t result;
 *
 *     uint8_t entropyBuffer[ENTROPY_REQUEST_LENGTH];
 *
 *     // Initialise the AESCTRDRBG instance here
 *     ...
 *
 *     // Start generating random numbers
 *     CryptoKeyPlaintext_initBlankKey(&entropyKey, entropyBuffer, ENTROPY_REQUEST_LENGTH);
 *
 *     result = AESCTRDRBG_getBytes(handle, &resultKey);
 *
 *     // Check return value and reseed if needed. This should happen only after many invocations
 *     // of AESCTRDRBG_getBytes().
 *     if (result == AESCTRDRBG_STATUS_RESEED_REQUIRED) {
 *         TRNG_Handle trngHandle;
 *         CryptoKey seedKey;
 *         int_fast16_t reseedResult;
 *         uint8_t reseedBuffer[AESCTRDRBG_SEED_LENGTH_AES_128];
 *
 *         CryptoKeyPlaintext_initBlankKey(&seedKey, reseedBuffer, AESCTRDRBG_SEED_LENGTH_AES_128);
 *
 *         reseedResult = TRNG_generateEntropy(trngHandle, &seedKey);
 *         if (reseedResult != TRNG_STATUS_SUCCESS) {
 *             // Handle error
 *             while(1);
 *         }
 *
 *         TRNG_close(trngHandle);
 *
 *         reseedResult = AESCTRDRBG_reseed(handle, reseedBuffer, NULL, 0);
 *         if (reseedResult != AESCTRDRBG_STATUS_SUCCESS) {
 *             // Handle error
 *             while(1);
 *         }
 *     }
 *     else if (result != AESCTRDRBG_STATUS_SUCCESS) {
 *         // Handle error
 *         while(1);
 *     }
 *
 * @endcode
 *
 */

#ifndef ti_drivers_AESCTRDRBG__include
#define ti_drivers_AESCTRDRBG__include

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

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

#ifdef __cplusplus
extern "C" {
#endif


#define AESCTRDRBG_STATUS_RESERVED        (-32)

#define AESCTRDRBG_STATUS_SUCCESS         (0)

#define AESCTRDRBG_STATUS_ERROR           (-1)

#define AESCTRDRBG_STATUS_RESOURCE_UNAVAILABLE (-2)

#define AESCTRDRBG_STATUS_RESEED_REQUIRED (-3)

#define AESCTRDRBG_AES_BLOCK_SIZE_BYTES 16

typedef enum {
    AESCTRDRBG_AES_KEY_LENGTH_128 = 16,
    AESCTRDRBG_AES_KEY_LENGTH_256 = 32,
} AESCTRDRBG_AES_KEY_LENGTH;

typedef enum {
    AESCTRDRBG_SEED_LENGTH_AES_128 = AESCTRDRBG_AES_KEY_LENGTH_128 + AESCTRDRBG_AES_BLOCK_SIZE_BYTES,
    AESCTRDRBG_SEED_LENGTH_AES_256 = AESCTRDRBG_AES_KEY_LENGTH_256 + AESCTRDRBG_AES_BLOCK_SIZE_BYTES,
} AESCTRDRBG_SEED_LENGTH;

typedef enum {
    AESCTRDRBG_RETURN_BEHAVIOR_BLOCKING = AESCTR_RETURN_BEHAVIOR_BLOCKING,
    AESCTRDRBG_RETURN_BEHAVIOR_POLLING  = AESCTR_RETURN_BEHAVIOR_POLLING,
} AESCTRDRBG_ReturnBehavior;

typedef struct {
    void               *object;

    void         const *hwAttrs;
} AESCTRDRBG_Config;

typedef AESCTRDRBG_Config *AESCTRDRBG_Handle;

typedef struct {
    AESCTRDRBG_AES_KEY_LENGTH   keyLength;                      
    uint32_t                    reseedInterval;                 
    const void                  *seed;                          
    const void                  *personalizationData;           
    size_t                      personalizationDataLength;      
    AESCTRDRBG_ReturnBehavior   returnBehavior;                 
    void                        *custom;                        
} AESCTRDRBG_Params;

extern const AESCTRDRBG_Params AESCTRDRBG_defaultParams;

void AESCTRDRBG_init(void);

void AESCTRDRBG_Params_init(AESCTRDRBG_Params *params);

AESCTRDRBG_Handle AESCTRDRBG_open(uint_least8_t index, const AESCTRDRBG_Params *params);

void AESCTRDRBG_close(AESCTRDRBG_Handle handle);

int_fast16_t AESCTRDRBG_getBytes(AESCTRDRBG_Handle handle, CryptoKey *randomBytes);

int_fast16_t AESCTRDRBG_reseed(AESCTRDRBG_Handle handle,
                               const void *seed,
                               const void *additionalData,
                               size_t additionalDataLength);

AESCTRDRBG_Handle AESCTRDRBG_construct(AESCTRDRBG_Config *config, const AESCTRDRBG_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_AESCTRDRBG__include */