123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351 |
- /* 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_COMMON_H_HEADER_INCLUDED_
- #define OTTERY_COMMON_H_HEADER_INCLUDED_
- #include <stdint.h>
- #include <sys/types.h>
-
- /** @file */
-
- struct ottery_config;
-
- /* Error codes */
-
- /**
- * @name libottery error codes and flags
- *
- * @{
- */
- /** No error has occurred. */
- #define OTTERY_ERR_NONE 0x0000
- /** We failed to allocate or initialize a lock. */
- #define OTTERY_ERR_LOCK_INIT 0x0001
- /** An internal error occurrred. This is probably a programming mistake
- * in libottery. */
- #define OTTERY_ERR_INTERNAL 0x0002
- /** We were unable to connect to the operating system's strong RNG. */
- #define OTTERY_ERR_INIT_STRONG_RNG 0x0003
- /** We were unable to retrieve sufficient random bytes from the
- * operating system's strong RNG. */
- #define OTTERY_ERR_ACCESS_STRONG_RNG 0x0004
- /** At least one argument to the function was invalid. */
- #define OTTERY_ERR_INVALID_ARGUMENT 0x0005
- /** An ottery_state structure was not aligned to a 16-byte boundary. */
- #define OTTERY_ERR_STATE_ALIGNMENT 0x0006
-
- /** FATAL ERROR: An ottery_st function other than ottery_st_init() was
- * called on and uninitialized state. */
- #define OTTERY_ERR_STATE_INIT 0x1000
- /** FLAG; FATAL ERROR: The error occurred while initializing the global
- * state during the first call to an ottery_rand_* function. */
- #define OTTERY_ERR_FLAG_GLOBAL_PRNG_INIT 0x2000
- /** FLAG; FATAL ERROR: The error occurred while reinitializing a state
- * after a fork(). (We need to do this, or else both processes would
- * generate the same values, which could give dire results.)
- */
- #define OTTERY_ERR_FLAG_POSTFORK_RESEED 0x4000
-
- /**
- * Checks whether an OTTERY_ERR value is a fatal error.
- *
- * @param err an OTTERY_ERR_* valuer
- * @return True if err is fatal; false if it is not fatal.
- */
- #define OTTERY_ERR_IS_FATAL(err) \
- (((err) & ~0xfff) != 0)
-
- /* Functions to interact with the library on a global level */
-
- /**
- * Override the behavior of libottery on a fatal error.
- *
- * By default, libottery will call abort() in a few circumstances, in
- * order to keep the program from operating insecurely. If you want,
- * you can provide another function to call instead.
- *
- * If your function does not itself abort() or exit() the process, or throw an
- * exception (assuming some C family that has exceptions), libottery will
- * continue running insecurely -- it might return predictable random numbers,
- * leak secrets, or just return 0 for everything -- so you should really be
- * very careful here.
- *
- * (The alternative to fatal errors would have been having all the
- * ottery_rand_* functions able to return an error, and requiring users
- * to check those codes. But experience suggests that C programmers
- * frequently do not check error codes.)
- *
- * @param fn A function to call in place of abort(). It will receive as
- * its argument one of the OTTERY_ERR_* error codes.
- */
- void ottery_set_fatal_handler(void (*fn)(int errorcode));
-
- /* Functions to manipulate parameters. */
-
- /**
- * @name Names of prfs for use with ottery_config_force_implementation
- *
- * @{ */
- #define OTTERY_PRF_CHACHA "CHACHA"
- #define OTTERY_PRF_CHACHA8 "CHACHA8"
- #define OTTERY_PRF_CHACHA12 "CHACHA12"
- #define OTTERY_PRF_CHACHA20 "CHACHA20"
- #define OTTERY_PRF_CHACHA_SIMD "CHACHA-SIMD"
- #define OTTERY_PRF_CHACHA8_SIMD "CHACHA8-SIMD"
- #define OTTERY_PRF_CHACHA12_SIMD "CHACHA12-SIMD"
- #define OTTERY_PRF_CHACHA20_SIMD "CHACHA20-SIMD"
- #define OTTERY_PRF_CHACHA_NO_SIMD "CHACHA-NOSIMD"
- #define OTTERY_PRF_CHACHA8_NO_SIMD "CHACHA8-NOSIMD"
- #define OTTERY_PRF_CHACHA12_NO_SIMD "CHACHA12-NOSIMD"
- #define OTTERY_PRF_CHACHA20_NO_SIMD "CHACHA20-NOSIMD"
- /** @} */
-
- /**
- * Initialize an ottery_config structure.
- *
- * You must call this function on any ottery_config structure before it
- * can be passed to ottery_init() or ottery_st_init().
- *
- * @param cfg The configuration object to initialize.
- * @return Zero on success, or one of the OTTERY_ERR_* error codes on
- * failure.
- */
- int ottery_config_init(struct ottery_config *cfg);
-
- /**
- * Try to force the use of a particular pseudorandom function for a given
- * libottery instance.
- *
- * To use this function, you call it on an ottery_config structure after
- * ottery_config_init(), and before passing that structure to
- * ottery_st_init() or ottery_init().
- *
- * @param cfg The configuration structure to configure.
- * @param impl The name of a pseudorandom function. One of the
- * OTTERY_PRF_* values.
- * @return Zero on success, or one of the OTTERY_ERR_* error codes on
- * failure.
- */
- int ottery_config_force_implementation(struct ottery_config *cfg,
- const char *impl);
-
- /**
- * Set a device file to use as a source of strong entropy.
- *
- * To use this function, you call it on an ottery_config structure after
- * ottery_config_init(), and before passing that structure to
- * ottery_st_init() or ottery_init().
- *
- * By default, libottery will try /dev/urandom on Unix-like systems.
- *
- * @param cfg The configuration structure to configure.
- * @param fname The name of the device to use instead of /dev/urandom. This
- * pointer is copied around, and must not be freed while any libottery state
- * configured using this structure is still in use.
- *
- */
- void ottery_config_set_urandom_device(struct ottery_config *cfg,
- const char *fname);
-
- /**
- * Set a device file to use as a source of strong entropy from the operating
- * system.
- *
- * To use this function, you call it on an ottery_config structure after
- * ottery_config_init(), and before passing that structure to
- * ottery_st_init() or ottery_init().
- *
- * This function overrides the default behavior, and overrides any
- * setting in ottery_config_set_urandom_device.
- *
- * You MUST NOT change the the file descriptor while any libottery PRNG
- * configured with it is still running. For example, don't close it, or use
- * dup2 to make it refer to a different file, or anything like that.
- *
- * It is probably a good idea to open the file with the CLOEXEC flag set.
- *
- * @param cfg The configuration structure to configure.
- * @param fd A file descriptor to use as an OS rng source.
- */
- void ottery_config_set_urandom_fd(struct ottery_config *cfg,
- int fd);
-
- struct sockaddr;
-
- /**
- * Configure a socket at which to find a local copy of some service
- * implementing the EGD (entropy-gathering daemon) protocol.
- *
- * Unless this function is called, EGD is not used by default.
-
- * To use this function, you call it on an ottery_config structure after
- * ottery_config_init(), and before passing that structure to
- * ottery_st_init() or ottery_init().
- *
- * TODO: This is not implemented for Windows yet.
- *
- * @param cfg The configuration structure to configure.
- * @param addr The address of the daemon. Obviously, this should be
- * some port on localhost, or a unix socket. This pointer is copied
- * around, and must not be freed while any libottery state configured
- * using this structure is still in use.
- * @param len the length of the address.
- *
- */
- void ottery_config_set_egd_socket(struct ottery_config *cfg,
- const struct sockaddr *addr,
- int len);
-
- /**
- * @brief External entropy sources.
- *
- * These can be passed as a bitmask to ottery_config_disable_entropy_sources.
- *
- * @{ */
- /** A unix-style /dev/urandom device. */
- #define OTTERY_ENTROPY_SRC_RANDOMDEV 0x0010000
- /** The Windows CryptGenRandom call. */
- #define OTTERY_ENTROPY_SRC_CRYPTGENRANDOM 0x0020000
- /** The Intel RDRAND instruction. */
- #define OTTERY_ENTROPY_SRC_RDRAND 0x0040000
- /** Some local server obeying the EGD protocol. Has no effect unless
- * ottery_config_set_egd_socket was called. */
- #define OTTERY_ENTROPY_SRC_EGD 0x0080000
- /** @} */
-
- /**
- * Disable the use of one or more entropy sources.
- *
- * Note that if enough entropy sources are disabled, the state will
- * not be able to get initialized, and libottery might not work.
- *
- * To use this function, you call it on an ottery_config structure after
- * ottery_config_init(), and before passing that structure to
- * ottery_st_init() or ottery_init().
- *
- * @param cfg A configuration in which to disable one or more entropy sources.
- * @param disabled_sources a bitwise combination of one or more
- * OTTERY_ENTROPY_SRC_* values to disable. This will replace
- * any previous bitmask of disabled sources.
- *
- */
- void ottery_config_disable_entropy_sources(struct ottery_config *cfg,
- uint32_t disabled_sources);
-
- /**
- * Mark one or more entropy sources as "weak".
- *
- * Unlike a disabled source, we will still try to read entropy from
- * a weak source -- but we will fail if _only_ weak sources are available.
- *
- * Note that if enough entropy sources are disabled and/or weak sources are
- * failing, the state will not be able to get initialized, and libottery might
- * not work.
- *
- * To use this function, you call it on an ottery_config structure after
- * ottery_config_init(), and before passing that structure to
- * ottery_st_init() or ottery_init().
- *
- * @param cfg A configuration in which to disable one or more entropy sources.
- * @param weak_sources a bitwise combination of one or more
- * OTTERY_ENTROPY_SRC_* values to mark as weak. This will replace
- * any previous bitmask of weak sources.
- */
- void ottery_config_mark_entropy_sources_weak(struct ottery_config *cfg,
- uint32_t weak_source);
-
- /** Size reserved for struct ottery_config */
- #define OTTERY_CONFIG_DUMMY_SIZE_ 1024
-
- #ifndef OTTERY_INTERNAL
- /**
- * A configuration object for setting up a libottery instance.
- *
- * An ottery_config structure is initialized with ottery_config_init,
- * and passed to ottery_init() or 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 ottery_config {
- /** Nothing to see here */
- uint8_t dummy_[OTTERY_CONFIG_DUMMY_SIZE_];
- };
- #endif
-
- /**
- * Get the minimal size for allocating an ottery_config.
- *
- * sizeof(ottery_config) 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_config structure.
- */
- size_t ottery_get_sizeof_config(void);
-
- /**
- * @name libottery build flag
- *
- * @see ottery_Get_build_flags()
- *
- * @{
- */
- /** Set if libottery was built with PID checking disabled. If this option is
- * present, fork()ing can be dangerous. */
- #define OTTERY_BLDFLG_NO_PID_CHECK 0x00000001
- /** Set if libottery was built with initialization checking disabled. If this
- * option is present, libottery might use an uninitialized, unseeded PRNGs.
- */
- #define OTTERY_BLDFLG_NO_INIT_CHECK 0x00000002
- /** Set if locking was disabled. If this option is present, no libottery
- * state, including the global state, is thread-safe. */
- #define OTTERY_BLDFLG_NO_LOCKING 0x00000004
- /** Set if the clear-after-yield feature was disabled. If this option is
- * present, backtracking-resistance is somewhat compromised. */
- #define OTTERY_BLDFLG_NO_CLEAR_AFTER_YIELD 0x00000008
- /** Set if the stack-wiping feature was disabled. If this option is
- * present, programs which accidentally read uninitialized data from the
- * stack may leak some cryptographic state. */
- #define OTTERY_BLDFLG_NO_WIPE_STACK 0x00000010
- /** Set if SIMD support was disabled. This will make libottery slower. */
- #define OTTERY_BLDFLG_NO_SIMD 0x00010000
- /** @} */
-
- /** A bitmask of any flags that might affect safe and secure program
- * operation. */
- #define OTTERY_BLDFLG_MASK_SAFETY 0x0000ffff
-
- /**
- * Return a bitmask of flags describing the compile-time options that this
- * libottery instance was built with. Some of these flags might make the
- * library less safe to use!
- */
- uint32_t ottery_get_build_flags(void);
-
- /**
- * Return a run-time version number for Libottery. The first three bytes are
- * the major number, minor number, and patch-level respectively. The final
- * byte is 0 for a released version, and nonzero otherwise.
- */
- uint32_t ottery_get_version(void);
- /**
- * Return a human-readable string representing the run-time Libottery version.
- */
- const char *ottery_get_version_string(void);
-
- const char *ottery_get_impl_name(void);
-
- #endif
|