/* hmac_prng.h - TinyCrypt interface to an HMAC-PRNG implementation */ /* * Copyright (C) 2015 by Intel Corporation, 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 Intel Corporation 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 * @brief Interface to an HMAC-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 HMAC-PRNG one * which is based on HMAC. TinyCrypt implements HMAC-PRNG with * certain modifications from the NIST SP 800-90A spec. * * 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 (HMAC and * SHA256, for TinyCrypt). * * The NIST SP 800-90A standard tolerates a null personalization, * while TinyCrypt requires a non-null personalization. This is * because a personalization string (the host name concatenated * with a time stamp, for example) is easily computed and might be * the last line of defense against failure of the entropy source. * * Requires: - SHA-256 * - HMAC * * Usage: 1) call tc_hmac_prng_init to set the HMAC key and process the * personalization data. * * 2) call tc_hmac_prng_reseed to process the seed and additional * input. * * 3) call tc_hmac_prng_generate to out put the pseudo-random data. */ #ifndef __TC_HMAC_PRNG_H__ #define __TC_HMAC_PRNG_H__ #include #include #ifdef __cplusplus extern "C" { #endif #define TC_HMAC_PRNG_RESEED_REQ -1 struct tc_hmac_prng_struct { /* the HMAC instance for this PRNG */ struct tc_hmac_state_struct h; /* the PRNG key */ uint8_t key[TC_SHA256_DIGEST_SIZE]; /* PRNG state */ uint8_t v[TC_SHA256_DIGEST_SIZE]; /* calls to tc_hmac_prng_generate left before re-seed */ uint32_t countdown; }; typedef struct tc_hmac_prng_struct *TCHmacPrng_t; /** * @brief HMAC-PRNG initialization procedure * Initializes prng with personalization, disables tc_hmac_prng_generate * @return returns TC_CRYPTO_SUCCESS (1) * returns TC_CRYPTO_FAIL (0) if: * prng == NULL, * personalization == NULL, * plen > MAX_PLEN * @note Assumes: - personalization != NULL. * The personalization is a platform unique string (e.g., the host * name) and is the last line of defense against failure of the * entropy source * @warning NIST SP 800-90A specifies 3 items as seed material during * initialization: entropy seed, personalization, and an optional * nonce. TinyCrypts requires instead a non-null personalization * (which is easily computed) and indirectly requires an entropy * seed (since the reseed function is mandatorily called after * init) * @param prng IN/OUT -- the PRNG state to initialize * @param personalization IN -- personalization string * @param plen IN -- personalization length in bytes */ int32_t tc_hmac_prng_init(TCHmacPrng_t prng, const uint8_t *personalization, uint32_t plen); /** * @brief HMAC-PRNG reseed procedure * Mixes seed into prng, enables tc_hmac_prng_generate * @return returns TC_CRYPTO_SUCCESS (1) * returns TC_CRYPTO_FAIL (0) if: * prng == NULL, * seed == NULL, * seedlen < MIN_SLEN, * seendlen > MAX_SLEN, * additional_input != (const uint8_t *) 0 && additionallen == 0, * additional_input != (const uint8_t *) 0 && additionallen > MAX_ALEN * @note Assumes:- tc_hmac_prng_init has been called for prng * - seed has sufficient entropy. * * @param prng IN/OUT -- the PRNG state * @param seed IN -- entropy to mix into the prng * @param seedlen IN -- length of seed in bytes * @param additional_input IN -- additional input to the prng * @param additionallen IN -- additional input length in bytes */ int32_t tc_hmac_prng_reseed(TCHmacPrng_t prng, const uint8_t *seed, uint32_t seedlen, const uint8_t *additional_input, uint32_t additionallen); /** * @brief HMAC-PRNG generate procedure * Generates outlen pseudo-random bytes into out buffer, updates prng * @return returns TC_CRYPTO_SUCCESS (1) * returns TC_HMAC_PRNG_RESEED_REQ (-1) if a reseed is needed * returns TC_CRYPTO_FAIL (0) if: * out == NULL, * prng == NULL, * outlen == 0, * outlen >= MAX_OUT * @note Assumes tc_hmac_prng_init has been called for prng * @param out IN/OUT -- buffer to receive output * @param outlen IN -- size of out buffer in bytes * @param prng IN/OUT -- the PRNG state */ int32_t tc_hmac_prng_generate(uint8_t *out, uint32_t outlen, TCHmacPrng_t prng); #ifdef __cplusplus } #endif #endif