/* ctr_prng.h - TinyCrypt interface to a CTR-PRNG implementation */
|
|
/*
|
* Copyright (c) 2016, Chris Morrison
|
* 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.
|
*
|
* 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 HOLDER 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
|
* @brief Interface to a CTR-PRNG implementation.
|
*
|
* Overview: A pseudo-random number generator (PRNG) generates a sequence
|
* of numbers that have a distribution close to the one expected
|
* for a sequence of truly random numbers. The NIST Special
|
* Publication 800-90A specifies several mechanisms to generate
|
* sequences of pseudo random numbers, including the CTR-PRNG one
|
* which is based on AES. TinyCrypt implements CTR-PRNG with
|
* AES-128.
|
*
|
* Security: A cryptographically secure PRNG depends on the existence of an
|
* entropy source to provide a truly random seed as well as the
|
* security of the primitives used as the building blocks (AES-128
|
* in this instance).
|
*
|
* Requires: - AES-128
|
*
|
* Usage: 1) call tc_ctr_prng_init to seed the prng context
|
*
|
* 2) call tc_ctr_prng_reseed to mix in additional entropy into
|
* the prng context
|
*
|
* 3) call tc_ctr_prng_generate to output the pseudo-random data
|
*
|
* 4) call tc_ctr_prng_uninstantiate to zero out the prng context
|
*/
|
|
#ifndef __TC_CTR_PRNG_H__
|
#define __TC_CTR_PRNG_H__
|
|
#include <tinycrypt/aes.h>
|
|
#define TC_CTR_PRNG_RESEED_REQ -1
|
|
#ifdef __cplusplus
|
extern "C" {
|
#endif
|
|
typedef struct {
|
/* updated each time another BLOCKLEN_BYTES bytes are produced */
|
uint8_t V[TC_AES_BLOCK_SIZE];
|
|
/* updated whenever the PRNG is reseeded */
|
struct tc_aes_key_sched_struct key;
|
|
/* number of requests since initialization/reseeding */
|
uint64_t reseedCount;
|
} TCCtrPrng_t;
|
|
|
/**
|
* @brief CTR-PRNG initialization procedure
|
* Initializes prng context with entropy and personalization string (if any)
|
* @return returns TC_CRYPTO_SUCCESS (1)
|
* returns TC_CRYPTO_FAIL (0) if:
|
* ctx == NULL,
|
* entropy == NULL,
|
* entropyLen < (TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE)
|
* @note Only the first (TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE) bytes of
|
* both the entropy and personalization inputs are used -
|
* supplying additional bytes has no effect.
|
* @param ctx IN/OUT -- the PRNG context to initialize
|
* @param entropy IN -- entropy used to seed the PRNG
|
* @param entropyLen IN -- entropy length in bytes
|
* @param personalization IN -- personalization string used to seed the PRNG
|
* (may be null)
|
* @param plen IN -- personalization length in bytes
|
*
|
*/
|
int tc_ctr_prng_init(TCCtrPrng_t * const ctx,
|
uint8_t const * const entropy,
|
unsigned int entropyLen,
|
uint8_t const * const personalization,
|
unsigned int pLen);
|
|
/**
|
* @brief CTR-PRNG reseed procedure
|
* Mixes entropy and additional_input into the prng context
|
* @return returns TC_CRYPTO_SUCCESS (1)
|
* returns TC_CRYPTO_FAIL (0) if:
|
* ctx == NULL,
|
* entropy == NULL,
|
* entropylen < (TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE)
|
* @note It is better to reseed an existing prng context rather than
|
* re-initialise, so that any existing entropy in the context is
|
* presereved. This offers some protection against undetected failures
|
* of the entropy source.
|
* @note Assumes tc_ctr_prng_init has been called for ctx
|
* @param ctx IN/OUT -- the PRNG state
|
* @param entropy IN -- entropy to mix into the prng
|
* @param entropylen IN -- length of entropy in bytes
|
* @param additional_input IN -- additional input to the prng (may be null)
|
* @param additionallen IN -- additional input length in bytes
|
*/
|
int tc_ctr_prng_reseed(TCCtrPrng_t * const ctx,
|
uint8_t const * const entropy,
|
unsigned int entropyLen,
|
uint8_t const * const additional_input,
|
unsigned int additionallen);
|
|
/**
|
* @brief CTR-PRNG generate procedure
|
* Generates outlen pseudo-random bytes into out buffer, updates prng
|
* @return returns TC_CRYPTO_SUCCESS (1)
|
* returns TC_CTR_PRNG_RESEED_REQ (-1) if a reseed is needed
|
* returns TC_CRYPTO_FAIL (0) if:
|
* ctx == NULL,
|
* out == NULL,
|
* outlen >= 2^16
|
* @note Assumes tc_ctr_prng_init has been called for ctx
|
* @param ctx IN/OUT -- the PRNG context
|
* @param additional_input IN -- additional input to the prng (may be null)
|
* @param additionallen IN -- additional input length in bytes
|
* @param out IN/OUT -- buffer to receive output
|
* @param outlen IN -- size of out buffer in bytes
|
*/
|
int tc_ctr_prng_generate(TCCtrPrng_t * const ctx,
|
uint8_t const * const additional_input,
|
unsigned int additionallen,
|
uint8_t * const out,
|
unsigned int outlen);
|
|
/**
|
* @brief CTR-PRNG uninstantiate procedure
|
* Zeroes the internal state of the supplied prng context
|
* @return none
|
* @param ctx IN/OUT -- the PRNG context
|
*/
|
void tc_ctr_prng_uninstantiate(TCCtrPrng_t * const ctx);
|
|
#ifdef __cplusplus
|
}
|
#endif
|
|
#endif /* __TC_CTR_PRNG_H__ */
|
