random.h

Go to the documentation of this file.

/**
 * \file    random.h
 * \brief   Random number generation
 * \author  marc dot pignat at hevs dot ch
 *
 * STM32F4 cpu have got a hardware based random number generator. Let expose it.
 * It should be sufficiently random to roll a dice, but care must be taken if
 * you want cryptographically secure random numbers.
 * \ingroupg misc
 * @{
 ***************************************************************************/
#ifndef HEIVS_RANDOM_H
#define HEIVS_RANDOM_H

#include <stdint.h>
#include "heivs/error.h"
#include "heivs/time.h"

#ifdef __cplusplus
    extern "C" {
#endif

/**
 * \brief Initialize the HW random number generator
 */
status_e random_init(void);

/**
 * \brief Disable the HW random number generator
 */
status_e random_suspend(void);

/*
 * \brief Get random data
 * \param data where data should be written
 * \param timeout_ms, the timeout in ms
 *
 * \return #NO_ERROR for no problem
 *
 * The returned data is only valid when the return value is NO_ERROR.
 */
status_e random_get(uint32_t *data, uint32_t timeout_ms);

/*
 * \brief Get random data
 * \param data where data should be written
 *
 * \return #NO_ERROR for no problem
 *
 * The returned data is only valid when the return value is NO_ERROR.
 *
 * When the return value is ERROR_HW_FAILED, re-call random_init()
 * When the return value is ERROR_AGAIN, retry later (the entropy pool is empty)
 *
 * \warning return value may be inaccurate if not initialized
 * \see random_init
 */
status_e random_get_nowait(uint32_t *data);

#ifdef __cplusplus
    }
#endif

/**
 * @}
 */
#endif /* HEIVS_RANDOM_H */