/* 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__ */