123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184 |
- /* Libottery by Nick Mathewson.
-
- This software has been dedicated to the public domain under the CC0
- public domain dedication.
-
- To the extent possible under law, the person who associated CC0 with
- libottery has waived all copyright and related or neighboring rights
- to libottery.
-
- You should have received a copy of the CC0 legalcode along with this
- work in doc/cc0.txt. If not, see
- <http://creativecommons.org/publicdomain/zero/1.0/>.
- */
- #ifndef OTTERY_ST_H_HEADER_INCLUDED_
- #define OTTERY_ST_H_HEADER_INCLUDED_
- #include <stdint.h>
- #include <sys/types.h>
-
- #ifdef __cplusplus
- extern "C" {
- #endif
-
- #include "ottery_common.h"
-
- /** @file */
-
- struct ottery_config;
- struct ottery_state;
-
- /** Size reserved for struct ottery_state */
- #define OTTERY_STATE_DUMMY_SIZE_ 1536
-
- #ifndef OTTERY_INTERNAL
- /**
- * The state for a libottery PRNG.
- *
- * An ottery_state structure is constucted with ottery_st_init(). It MUST be
- * aligned on a 16-byte boundary.
- *
- * You may not use an ottery_state structure with any other function before
- * you have first initialized it with ottery_st_init().
- *
- * The contents of this structure are opaque; The definition here is
- * defined to be large enough so that programs that allocate it will get
- * more than enough room.
- */
- struct __attribute__((aligned(16))) ottery_state {
- /** Nothing to see here */
- uint8_t dummy_[OTTERY_STATE_DUMMY_SIZE_];
- };
- #endif
-
- /**
- * Get the minimal size for allocating an ottery_state.
- *
- * sizeof(ottery_state) will give an overestimate to allow binary
- * compatibility with future versions of libottery. Use this function instead
- * to get the minimal number of bytes to allocate.
- *
- * @return The minimal number of bytes to use when allocating an
- * ottery_state structure.
- */
- size_t ottery_get_sizeof_state(void);
-
- /**
- * Initialize an ottery_state structure.
- *
- * You must call this function on any ottery_state structure before
- * calling any other functions on it.
- *
- * @param st The ottery_state to initialize.
- * @param cfg Either NULL, or an ottery_config structure that has been
- * initialized with ottery_config_init().
- * @return Zero on success, or one of the OTTERY_ERR_* error codes on failure.
- */
- int ottery_st_init(struct ottery_state *st, const struct ottery_config *cfg);
-
- /**
- * Add more entropy to an ottery_state structure.
- *
- * Calling this function should be needless, if you trust your operating
- * system's random number generator and entropy extraction features. You
- * would want to use this function if you think the operating system's random
- * number generator might be inadequate, and you want to add more entropy from
- * EGD or something.
- *
- * You might also want to call this function if your belief system says that
- * it's useful to periodically add more raw entropy to a well-seeded
- * cryptographically strong PRNG.
- *
- * @param st The state which will receive more entropy.
- * @param seed Bytes to add to the state.
- * @param n The number of bytes to add.
- * @return Zero on success, or one of the OTTERY_ERR_* error codes on failure.
- */
- int ottery_st_add_seed(struct ottery_state *st, const uint8_t *seed, size_t n);
-
- /**
- * Destroy an ottery_state structure and release any resources that it might
- * hold.
- *
- * Ordinarily, you would want to call this at exit, or before freeing an
- * ottery_state
- *
- * @param st The state to wipe.
- */
- void ottery_st_wipe(struct ottery_state *st);
-
- /**
- * Explicitly prevent backtracking attacks. (Usually needless).
- *
- * Once this function has been called, an attacker who compromises the state
- * later on will not be able to recover bytes that have previously been
- * returned by any of the ottery_st_rand_* functions.
- *
- * You should not usually need to call this function: Libottery provides
- * backtracking resistance by default, so unless you have manually recompiled
- * with the OTTERY_NO_CLEAR_AFTER_YIELD option, this function isn't
- * necessary and has no effect. Even *with* OTTERY_NO_CLEAR_AFTER_YIELD,
- * this function isn't necessary in ordinary operation: the libottery state is
- * implicitly "stirred" every 1k or so.
- *
- * @param st The state to stir.
- */
- void ottery_st_prevent_backtracking(struct ottery_state *st);
-
- /**
- * Use an ottery_state structure to fill a buffer with random bytes.
- *
- * @param st The state structure to use.
- * @param buf The buffer to fill.
- * @param n The number of bytes to write.
- */
- void ottery_st_rand_bytes(struct ottery_state *st, void *buf, size_t n);
- /**
- * Use an ottery_state structure to generate a random number of type unsigned.
- *
- * @param st The state structure to use.
- * @return A random number between 0 and UINT_MAX included,
- * chosen uniformly.
- */
- unsigned ottery_st_rand_unsigned(struct ottery_state *st);
- /**
- * Use an ottery_state structure to generate a random number of type uint32_t.
- *
- * @param st The state structure to use.
- * @return A random number between 0 and UINT32_MAX included,
- * chosen uniformly.
- */
- uint32_t ottery_st_rand_uint32(struct ottery_state *st);
- /**
- * Use an ottery_state structure to generate a random number of type uint64_t.
- *
- * @param st The state structure to use.
- * @return A random number between 0 and UINT64_MAX included,
- * chosen uniformly.
- */
- uint64_t ottery_st_rand_uint64(struct ottery_state *st);
- /**
- * Use an ottery_state structure to generate a random number of type unsigned
- * in a given range.
- *
- * @param st The state structure to use.
- * @param top The upper bound of the range (inclusive).
- * @return A random number no larger than top, and no less than 0,
- * chosen uniformly.
- */
- unsigned ottery_st_rand_range(struct ottery_state *st, unsigned top);
- /**
- * Use an ottery_state structure to generate a random number of type uint64_t
- * in a given range.
- *
- * @param st The state structure to use.
- * @param top The upper bound of the range (inclusive).
- * @return A random number no larger than top, and no less than 0,
- * chosen uniformly.
- */
- uint64_t ottery_st_rand_range64(struct ottery_state *st, uint64_t top);
-
- #ifdef __cplusplus
- }
- #endif
-
- #endif
|