NTRU_IoT/legacy-code/include/ntru_crypto_drbg.h

/******************************************************************************
 * NTRU Cryptography Reference Source Code
 *
 * Copyright (C) 2009-2016  Security Innovation (SI)
 *
 * SI has dedicated the work to the public domain by waiving all of its rights
 * to the work worldwide under copyright law, including all related and
 * neighboring rights, to the extent allowed by law.
 *
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * You can copy, modify, distribute and perform the work, even for commercial
 * purposes, all without asking permission. You should have received a copy of
 * the creative commons license (CC0 1.0 universal) along with this program.
 * See the license file for more information. 
 *
 *
 *********************************************************************************/
 
 
 
/******************************************************************************
 *
 * File:  ntru_crypto_drbg.h
 *
 * Contents: Public header file for ntru_crypto_drbg.c.
 *
 *****************************************************************************/


#ifndef NTRU_CRYPTO_DRBG_H
#define NTRU_CRYPTO_DRBG_H

#include "ntru_crypto_platform.h"
#include "ntru_crypto_error.h"

#if !defined( NTRUCALL )
  #if !defined(WIN32) || defined (NTRUCRYPTO_STATIC)
    /* Linux, or a Win32 static library */
    #define NTRUCALL extern uint32_t
  #elif defined (NTRUCRYPTO_EXPORTS)
    /* Win32 DLL build */
    #define NTRUCALL extern __declspec(dllexport) uint32_t
  #else
    /* Win32 DLL import */
    #define NTRUCALL extern __declspec(dllimport) uint32_t
  #endif
#endif /* NTRUCALL */

#if defined ( __cplusplus )
extern "C" {
#endif /* __cplusplus */


/*******************
 * DRBG parameters *
 *******************/

#if !defined(DRBG_MAX_INSTANTIATIONS)
#define DRBG_MAX_INSTANTIATIONS                 4
#endif
#define DRBG_MAX_SEC_STRENGTH_BITS              256
#define DRBG_MAX_BYTES_PER_BYTE_OF_ENTROPY      8


/************************
 * HMAC_DRBG parameters *
 ************************/

#define HMAC_DRBG_MAX_PERS_STR_BYTES            32
#define HMAC_DRBG_MAX_BYTES_PER_REQUEST         1024


/********************
 * type definitions *
 ********************/

typedef uint32_t DRBG_HANDLE;               /* drbg handle */

typedef enum {                              /* drbg types */
    EXTERNAL_DRBG,
    SHA256_HMAC_DRBG,
} DRBG_TYPE;

typedef enum {                              /* entropy-function commands */
    GET_NUM_BYTES_PER_BYTE_OF_ENTROPY = 0,
    INIT,
    GET_BYTE_OF_ENTROPY,
} ENTROPY_CMD;
typedef uint8_t (*ENTROPY_FN)(              /* get entropy function */
                    ENTROPY_CMD  cmd,       /* command */
                    uint8_t     *out);      /* address for output */


/* Type for external PRNG functions. Must return DRBG_OK on success */
typedef uint32_t (*RANDOM_BYTES_FN)(        /* random bytes function */
                    uint8_t *out,           /* output buffer */
                    uint32_t num_bytes);    /* number of bytes */


/***************
 * error codes *
 ***************/

#define DRBG_OK             0x00000000 /* no errors */
#define DRBG_OUT_OF_MEMORY  0x00000001 /* can't allocate memory */
#define DRBG_BAD_PARAMETER  0x00000002 /* null pointer */
#define DRBG_BAD_LENGTH     0x00000003 /* invalid no. of bytes */
#define DRBG_NOT_AVAILABLE  0x00000004 /* no instantiation slot available */
#define DRBG_ENTROPY_FAIL   0x00000005 /* entropy function failure */

/***************
 * error macro *
 ***************/

#define DRBG_RESULT(r)  ((uint32_t)((r) ? DRBG_ERROR_BASE + (r) : (r)))
#define DRBG_RET(r)     return DRBG_RESULT(r);


/*************************
 * function declarations *
 *************************/

/* ntru_crypto_drbg_instantiate
 *
 * This routine instantiates a drbg with the requested security strength.
 * See ANS X9.82: Part 3-2007.
 *
 * Returns DRBG_OK if successful.
 * Returns DRBG_ERROR_BASE + DRBG_BAD_PARAMETER if an argument pointer is NULL.
 * Returns DRBG_ERROR_BASE + DRBG_BAD_LENGTH if the security strength requested
 *  or the personalization string is too large.
 * Returns DRBG_ERROR_BASE + DRBG_OUT_OF_MEMORY if the internal state cannot be
 *  allocated from the heap.
 */

NTRUCALL
ntru_crypto_drbg_instantiate(
    uint32_t       sec_strength_bits, /*  in - requested sec strength in bits */
    uint8_t const *pers_str,          /*  in - ptr to personalization string */
    uint32_t       pers_str_bytes,    /*  in - no. personalization str bytes */
    ENTROPY_FN     entropy_fn,        /*  in - pointer to entropy function */
    DRBG_HANDLE   *handle);           /* out - address for drbg handle */

/* ntru_crypto_drbg_external_instantiate
 *
 * This routine instruments an external DRBG so that ntru_crypto routines
 * can call it. randombytesfn must be of type
 * uint32_t (randombytesfn*)(unsigned char *out, unsigned long long num_bytes);
 * and should return DRBG_OK on success.
 *
 * Returns DRBG_OK if successful.
 * Returns DRBG_ERROR_BASE + DRBG_NOT_AVAILABLE if there are no instantiation
 *  slots available
 * Returns DRBG_ERROR_BASE + DRBG_OUT_OF_MEMORY if the internal state cannot be
 *  allocated from the heap.
 */

NTRUCALL
ntru_crypto_drbg_external_instantiate(
    RANDOM_BYTES_FN  randombytesfn, /*  in - pointer to random bytes function */
    DRBG_HANDLE     *handle);       /* out - address for drbg handle */

/* ntru_crypto_drbg_uninstantiate
 *
 * This routine frees a drbg given its handle.
 *
 * Returns DRBG_OK if successful.
 * Returns DRBG_ERROR_BASE + DRBG_BAD_PARAMETER if handle is not valid.
 */

NTRUCALL
ntru_crypto_drbg_uninstantiate(
    DRBG_HANDLE handle);            /* in - drbg handle */


/* ntru_crypto_drbg_reseed
 *
 * This routine reseeds an instantiated drbg.
 * See ANS X9.82: Part 3-2007.
 *
 * Returns DRBG_OK if successful.
 * Returns DRBG_ERROR_BASE + DRBG_BAD_PARAMETER if handle is not valid.
 * Returns NTRU_CRYPTO_HMAC errors if they occur.
 */

NTRUCALL
ntru_crypto_drbg_reseed(
    DRBG_HANDLE handle);            /* in - drbg handle */


/* ntru_crypto_drbg_generate
 *
 * This routine generates pseudorandom bytes using an instantiated drbg.
 * If the maximum number of requests has been reached, reseeding will occur.
 * See ANS X9.82: Part 3-2007.
 *
 * Returns DRBG_OK if successful.
 * Returns DRBG_ERROR_BASE + DRBG_BAD_PARAMETER if handle is not valid or if
 *  an argument pointer is NULL.
 * Returns DRBG_ERROR_BASE + DRBG_BAD_LENGTH if the security strength requested
 *  is too large or the number of bytes requested is zero or too large.
 * Returns NTRU_CRYPTO_HMAC errors if they occur.
 */

NTRUCALL
ntru_crypto_drbg_generate(
    DRBG_HANDLE handle,             /*  in - drbg handle */
    uint32_t    sec_strength_bits,  /*  in - requested sec strength in bits */
    uint32_t    num_bytes,          /*  in - number of octets to generate */
    uint8_t    *out);               /* out - address for generated octets */


#if defined ( __cplusplus )
}
#endif /* __cplusplus */


#endif /* NTRU_CRYPTO_DRBG_H */