You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
166 lines
6.3 KiB
166 lines
6.3 KiB
/* 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__ */
|
|
|