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_NOLOCK_H_HEADER_INCLUDED_ 15 #define OTTERY_NOLOCK_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_nolock; 29 30 /** Size reserved for struct ottery_state_nolock */ 31 #define OTTERY_STATE_NOLOCK_DUMMY_SIZE_ 1536 32 33 #ifndef OTTERY_INTERNAL 34 /** 35 * The state for a non-thread-safe libottery PRNG 36 * 37 * Like struct ottery_state, but this structure (and its associated functions) 38 * are not thread safe. If you try to use this structure in more than one 39 * thread at a time, your program's behavior will be undefined. It might 40 * crash. It might insecurely give the same random sequence to multiple 41 * threads. It might fail in strange ways that you'd never predict. 42 * 43 * An ottery_state_nolock structure is constucted with ottery_st_init(). It 44 * MUST be aligned on a 16-byte boundary. 45 * 46 * You may not use an ottery_state_nolock structure with any other function 47 * before you have first initialized it with ottery_st_init_nolock(). 48 * 49 * The contents of this structure are opaque; The definition here is 50 * defined to be large enough so that programs that allocate it will get 51 * more than enough room. 52 */ 53 struct __attribute__((aligned(16))) ottery_state_nolock { 54 /** Nothing to see here */ 55 uint8_t dummy_[OTTERY_STATE_NOLOCK_DUMMY_SIZE_]; 56 }; 57 #endif 58 59 /** 60 * Get the minimal size for allocating an ottery_state_nolock. 61 * 62 * sizeof(ottery_state_nolock) will give an overestimate to allow binary 63 * compatibility with future versions of libottery. Use this function instead 64 * to get the minimal number of bytes to allocate. 65 * 66 * @return The minimal number of bytes to use when allocating an 67 * ottery_state_nolock structure. 68 */ 69 size_t ottery_get_sizeof_state_nolock(void); 70 71 /** 72 * Initialize an ottery_state_nolock structure. 73 * 74 * You must call this function on any ottery_state_nolock structure before 75 * calling any other functions on it. 76 * 77 * @param st The ottery_state_nolock to initialize. 78 * @param cfg Either NULL, or an ottery_config structure that has been 79 * initialized with ottery_config_init(). 80 * @return Zero on success, or one of the OTTERY_ERR_* error codes on failure. 81 */ 82 int ottery_st_init_nolock(struct ottery_state_nolock *st, const struct ottery_config *cfg); 83 84 /** 85 * Add more entropy to an ottery_state_nolock structure. 86 * 87 * Calling this function should be needless, if you trust your operating 88 * system's random number generator and entropy extraction features. You 89 * would want to use this function if you think the operating system's random 90 * number generator might be inadequate, and you want to add more entropy from 91 * EGD or something. 92 * 93 * You might also want to call this function if your belief system says that 94 * it's useful to periodically add more raw entropy to a well-seeded 95 * cryptographically strong PRNG. 96 * 97 * @param st The state which will receive more entropy. 98 * @param seed Bytes to add to the state. 99 * @param n The number of bytes to add. 100 * @return Zero on success, or one of the OTTERY_ERR_* error codes on failure. 101 */ 102 int ottery_st_add_seed_nolock(struct ottery_state_nolock *st, const uint8_t *seed, size_t n); 103 104 /** 105 * Destroy an ottery_state_nolock structure and release any resources that it 106 * might hold. 107 * 108 * Ordinarily, you would want to call this at exit, or before freeing an 109 * ottery_state_nolock 110 * 111 * @param st The state to wipe. 112 */ 113 void ottery_st_wipe_nolock(struct ottery_state_nolock *st); 114 115 /** 116 * Explicitly prevent backtracking attacks. (Usually needless). 117 * 118 * Once this function has been called, an attacker who compromises the state 119 * later on will not be able to recover bytes that have previously been 120 * returned by any of the ottery_st_rand_*_nolock functions. 121 * 122 * You should not usually need to call this function: Libottery provides 123 * backtracking resistance by default, so unless you have manually recompiled 124 * with the OTTERY_NO_CLEAR_AFTER_YIELD option, this function isn't 125 * necessary and has no effect. Even *with* OTTERY_NO_CLEAR_AFTER_YIELD, 126 * this function isn't necessary in ordinary operation: the libottery state is 127 * implicitly "stirred" every 1k or so. 128 * 129 * @param st The state to stir. 130 */ 131 void ottery_st_prevent_backtracking_nolock(struct ottery_state_nolock *st); 132 133 /** 134 * Use an ottery_state_nolock structure to fill a buffer with random bytes. 135 * 136 * @param st The state structure to use. 137 * @param buf The buffer to fill. 138 * @param n The number of bytes to write. 139 */ 140 void ottery_st_rand_bytes_nolock(struct ottery_state_nolock *st, void *buf, size_t n); 141 /** 142 * Use an ottery_state_nolock structure to generate a random number of type unsigned. 143 * 144 * @param st The state structure to use. 145 * @return A random number between 0 and UINT_MAX included, 146 * chosen uniformly. 147 */ 148 unsigned ottery_st_rand_unsigned_nolock(struct ottery_state_nolock *st); 149 /** 150 * Use an ottery_state_nolock structure to generate a random number of type uint32_t. 151 * 152 * @param st The state structure to use. 153 * @return A random number between 0 and UINT32_MAX included, 154 * chosen uniformly. 155 */ 156 uint32_t ottery_st_rand_uint32_nolock(struct ottery_state_nolock *st); 157 /** 158 * Use an ottery_state_nolock structure to generate a random number of type uint64_t. 159 * 160 * @param st The state structure to use. 161 * @return A random number between 0 and UINT64_MAX included, 162 * chosen uniformly. 163 */ 164 uint64_t ottery_st_rand_uint64_nolock(struct ottery_state_nolock *st); 165 /** 166 * Use an ottery_state_nolock structure to generate a random number of type unsigned 167 * in a given range. 168 * 169 * @param st The state structure to use. 170 * @param top The upper bound of the range (inclusive). 171 * @return A random number no larger than top, and no less than 0, 172 * chosen uniformly. 173 */ 174 unsigned ottery_st_rand_range_nolock(struct ottery_state_nolock *st, unsigned top); 175 /** 176 * Use an ottery_state_nolock structure to generate a random number of type uint64_t 177 * in a given range. 178 * 179 * @param st The state structure to use. 180 * @param top The upper bound of the range (inclusive). 181 * @return A random number no larger than top, and no less than 0, 182 * chosen uniformly. 183 */ 184 uint64_t ottery_st_rand_range64_nolock(struct ottery_state_nolock *st, uint64_t top); 185 186 #ifdef __cplusplus 187 } 188 #endif 189 190 #endif 191