1 /* Libottery by Nick Mathewson. 2 3 This software has been dedicated to the public domain under the CC0 4 public domain dedication. 5 6 To the extent possible under law, the person who associated CC0 with 7 libottery has waived all copyright and related or neighboring rights 8 to libottery. 9 10 You should have received a copy of the CC0 legalcode along with this 11 work in doc/cc0.txt. If not, see 12 <http://creativecommons.org/publicdomain/zero/1.0/>. 13 */ 14 #ifndef OTTERY_ST_H_HEADER_INCLUDED_ 15 #define OTTERY_ST_H_HEADER_INCLUDED_ 16 #include <stdint.h> 17 #include <sys/types.h> 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 #include "ottery_common.h" 24 25 /** @file */ 26 27 struct ottery_config; 28 struct ottery_state; 29 30 /** Size reserved for struct ottery_state */ 31 #define OTTERY_STATE_DUMMY_SIZE_ 1536 32 33 #ifndef OTTERY_INTERNAL 34 /** 35 * The state for a libottery PRNG. 36 * 37 * An ottery_state structure is constucted with ottery_st_init(). It MUST be 38 * aligned on a 16-byte boundary. 39 * 40 * You may not use an ottery_state structure with any other function before 41 * you have first initialized it with ottery_st_init(). 42 * 43 * The contents of this structure are opaque; The definition here is 44 * defined to be large enough so that programs that allocate it will get 45 * more than enough room. 46 */ 47 struct __attribute__((aligned(16))) ottery_state { 48 /** Nothing to see here */ 49 uint8_t dummy_[OTTERY_STATE_DUMMY_SIZE_]; 50 }; 51 #endif 52 53 /** 54 * Get the minimal size for allocating an ottery_state. 55 * 56 * sizeof(ottery_state) will give an overestimate to allow binary 57 * compatibility with future versions of libottery. Use this function instead 58 * to get the minimal number of bytes to allocate. 59 * 60 * @return The minimal number of bytes to use when allocating an 61 * ottery_state structure. 62 */ 63 size_t ottery_get_sizeof_state(void); 64 65 /** 66 * Initialize an ottery_state structure. 67 * 68 * You must call this function on any ottery_state structure before 69 * calling any other functions on it. 70 * 71 * @param st The ottery_state to initialize. 72 * @param cfg Either NULL, or an ottery_config structure that has been 73 * initialized with ottery_config_init(). 74 * @return Zero on success, or one of the OTTERY_ERR_* error codes on failure. 75 */ 76 int ottery_st_init(struct ottery_state *st, const struct ottery_config *cfg); 77 78 /** 79 * Add more entropy to an ottery_state structure. 80 * 81 * Calling this function should be needless, if you trust your operating 82 * system's random number generator and entropy extraction features. You 83 * would want to use this function if you think the operating system's random 84 * number generator might be inadequate, and you want to add more entropy from 85 * EGD or something. 86 * 87 * You might also want to call this function if your belief system says that 88 * it's useful to periodically add more raw entropy to a well-seeded 89 * cryptographically strong PRNG. 90 * 91 * @param st The state which will receive more entropy. 92 * @param seed Bytes to add to the state. 93 * @param n The number of bytes to add. 94 * @return Zero on success, or one of the OTTERY_ERR_* error codes on failure. 95 */ 96 int ottery_st_add_seed(struct ottery_state *st, const uint8_t *seed, size_t n); 97 98 /** 99 * Destroy an ottery_state structure and release any resources that it might 100 * hold. 101 * 102 * Ordinarily, you would want to call this at exit, or before freeing an 103 * ottery_state 104 * 105 * @param st The state to wipe. 106 */ 107 void ottery_st_wipe(struct ottery_state *st); 108 109 /** 110 * Explicitly prevent backtracking attacks. (Usually needless). 111 * 112 * Once this function has been called, an attacker who compromises the state 113 * later on will not be able to recover bytes that have previously been 114 * returned by any of the ottery_st_rand_* functions. 115 * 116 * You should not usually need to call this function: Libottery provides 117 * backtracking resistance by default, so unless you have manually recompiled 118 * with the OTTERY_NO_CLEAR_AFTER_YIELD option, this function isn't 119 * necessary and has no effect. Even *with* OTTERY_NO_CLEAR_AFTER_YIELD, 120 * this function isn't necessary in ordinary operation: the libottery state is 121 * implicitly "stirred" every 1k or so. 122 * 123 * @param st The state to stir. 124 */ 125 void ottery_st_prevent_backtracking(struct ottery_state *st); 126 127 /** 128 * Use an ottery_state structure to fill a buffer with random bytes. 129 * 130 * @param st The state structure to use. 131 * @param buf The buffer to fill. 132 * @param n The number of bytes to write. 133 */ 134 void ottery_st_rand_bytes(struct ottery_state *st, void *buf, size_t n); 135 /** 136 * Use an ottery_state structure to generate a random number of type unsigned. 137 * 138 * @param st The state structure to use. 139 * @return A random number between 0 and UINT_MAX included, 140 * chosen uniformly. 141 */ 142 unsigned ottery_st_rand_unsigned(struct ottery_state *st); 143 /** 144 * Use an ottery_state structure to generate a random number of type uint32_t. 145 * 146 * @param st The state structure to use. 147 * @return A random number between 0 and UINT32_MAX included, 148 * chosen uniformly. 149 */ 150 uint32_t ottery_st_rand_uint32(struct ottery_state *st); 151 /** 152 * Use an ottery_state structure to generate a random number of type uint64_t. 153 * 154 * @param st The state structure to use. 155 * @return A random number between 0 and UINT64_MAX included, 156 * chosen uniformly. 157 */ 158 uint64_t ottery_st_rand_uint64(struct ottery_state *st); 159 /** 160 * Use an ottery_state structure to generate a random number of type unsigned 161 * in a given range. 162 * 163 * @param st The state structure to use. 164 * @param top The upper bound of the range (inclusive). 165 * @return A random number no larger than top, and no less than 0, 166 * chosen uniformly. 167 */ 168 unsigned ottery_st_rand_range(struct ottery_state *st, unsigned top); 169 /** 170 * Use an ottery_state structure to generate a random number of type uint64_t 171 * in a given range. 172 * 173 * @param st The state structure to use. 174 * @param top The upper bound of the range (inclusive). 175 * @return A random number no larger than top, and no less than 0, 176 * chosen uniformly. 177 */ 178 uint64_t ottery_st_rand_range64(struct ottery_state *st, uint64_t top); 179 180 #ifdef __cplusplus 181 } 182 #endif 183 184 #endif 185