apache / mynewt-documentation / 94c47ae2bc67c54a68d227abbb47c27ae97cc232 / . / versions / v1_4_0 / mynewt-core / crypto / tinycrypt / include / tinycrypt / hmac_prng.h

/* hmac_prng.h - TinyCrypt interface to an HMAC-PRNG implementation */ | |

/* | |

* Copyright (C) 2017 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 <tinycrypt/sha256.h> | |

#include <tinycrypt/hmac.h> | |

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

unsigned int 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 | |

*/ | |

int tc_hmac_prng_init(TCHmacPrng_t prng, | |

const uint8_t *personalization, | |

unsigned int 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 | |

*/ | |

int tc_hmac_prng_reseed(TCHmacPrng_t prng, const uint8_t *seed, | |

unsigned int seedlen, const uint8_t *additional_input, | |

unsigned int 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 | |

*/ | |

int tc_hmac_prng_generate(uint8_t *out, unsigned int outlen, TCHmacPrng_t prng); | |

#ifdef __cplusplus | |

} | |

#endif | |

#endif /* __TC_HMAC_PRNG_H__ */ |