1 /* boost random/random_device.hpp header file 2 * 3 * Copyright Jens Maurer 2000 4 * Copyright Steven Watanabe 2010-2011 5 * Distributed under the Boost Software License, Version 1.0. (See 6 * accompanying file LICENSE_1_0.txt or copy at 7 * http://www.boost.org/LICENSE_1_0.txt) 8 * 9 * $Id$ 10 * 11 * Revision history 12 * 2000-02-18 Portability fixes (thanks to Beman Dawes) 13 */ 14 15 // See http://www.boost.org/libs/random for documentation. 16 17 18 #ifndef BOOST_RANDOM_RANDOM_DEVICE_HPP 19 #define BOOST_RANDOM_RANDOM_DEVICE_HPP 20 21 #include <string> 22 #include <boost/config.hpp> 23 #include <boost/noncopyable.hpp> 24 #include <boost/random/detail/auto_link.hpp> 25 #include <boost/system/config.hpp> // force autolink to find Boost.System 26 27 namespace boost { 28 namespace random { 29 30 /** 31 * Class \random_device models a \nondeterministic_random_number_generator. 32 * It uses one or more implementation-defined stochastic processes to 33 * generate a sequence of uniformly distributed non-deterministic random 34 * numbers. For those environments where a non-deterministic random number 35 * generator is not available, class random_device must not be implemented. See 36 * 37 * @blockquote 38 * "Randomness Recommendations for Security", D. Eastlake, S. Crocker, 39 * J. Schiller, Network Working Group, RFC 1750, December 1994 40 * @endblockquote 41 * 42 * for further discussions. 43 * 44 * @xmlnote 45 * Some operating systems abstract the computer hardware enough 46 * to make it difficult to non-intrusively monitor stochastic processes. 47 * However, several do provide a special device for exactly this purpose. 48 * It seems to be impossible to emulate the functionality using Standard 49 * C++ only, so users should be aware that this class may not be available 50 * on all platforms. 51 * @endxmlnote 52 * 53 * <b>Implementation Note for Linux</b> 54 * 55 * On the Linux operating system, token is interpreted as a filesystem 56 * path. It is assumed that this path denotes an operating system 57 * pseudo-device which generates a stream of non-deterministic random 58 * numbers. The pseudo-device should never signal an error or end-of-file. 59 * Otherwise, @c std::ios_base::failure is thrown. By default, 60 * \random_device uses the /dev/urandom pseudo-device to retrieve 61 * the random numbers. Another option would be to specify the /dev/random 62 * pseudo-device, which blocks on reads if the entropy pool has no more 63 * random bits available. 64 * 65 * <b>Implementation Note for Windows</b> 66 * 67 * On the Windows operating system, token is interpreted as the name 68 * of a cryptographic service provider. By default \random_device uses 69 * MS_DEF_PROV. 70 * 71 * <b>Performance</b> 72 * 73 * The test program <a href="\boost/libs/random/performance/nondet_random_speed.cpp"> 74 * nondet_random_speed.cpp</a> measures the execution times of the 75 * random_device.hpp implementation of the above algorithms in a tight 76 * loop. The performance has been evaluated on an 77 * Intel(R) Core(TM) i7 CPU Q 840 \@ 1.87GHz, 1867 Mhz with 78 * Visual C++ 2010, Microsoft Windows 7 Professional and with gcc 4.4.5, 79 * Ubuntu Linux 2.6.35-25-generic. 80 * 81 * <table cols="2"> 82 * <tr><th>Platform</th><th>time per invocation [microseconds]</th></tr> 83 * <tr><td> Windows </td><td>2.9</td></tr> 84 * <tr><td> Linux </td><td>1.7</td></tr> 85 * </table> 86 * 87 * The measurement error is estimated at +/- 1 usec. 88 */ 89 class random_device : private noncopyable 90 { 91 public: 92 typedef unsigned int result_type; 93 BOOST_STATIC_CONSTANT(bool, has_fixed_range = false); 94 95 /** Returns the smallest value that the \random_device can produce. */ BOOST_PREVENT_MACRO_SUBSTITUTION()96 static result_type min BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; } 97 /** Returns the largest value that the \random_device can produce. */ BOOST_PREVENT_MACRO_SUBSTITUTION()98 static result_type max BOOST_PREVENT_MACRO_SUBSTITUTION () { return ~0u; } 99 100 /** Constructs a @c random_device, optionally using the default device. */ 101 BOOST_RANDOM_DECL random_device(); 102 /** 103 * Constructs a @c random_device, optionally using the given token as an 104 * access specification (for example, a URL) to some implementation-defined 105 * service for monitoring a stochastic process. 106 */ 107 BOOST_RANDOM_DECL explicit random_device(const std::string& token); 108 109 BOOST_RANDOM_DECL ~random_device(); 110 111 /** 112 * Returns: An entropy estimate for the random numbers returned by 113 * operator(), in the range min() to log2( max()+1). A deterministic 114 * random number generator (e.g. a pseudo-random number engine) 115 * has entropy 0. 116 * 117 * Throws: Nothing. 118 */ 119 BOOST_RANDOM_DECL double entropy() const; 120 /** Returns a random value in the range [min, max]. */ 121 BOOST_RANDOM_DECL unsigned int operator()(); 122 123 /** Fills a range with random 32-bit values. */ 124 template<class Iter> generate(Iter begin,Iter end)125 void generate(Iter begin, Iter end) 126 { 127 for(; begin != end; ++begin) { 128 *begin = (*this)(); 129 } 130 } 131 132 private: 133 class impl; 134 impl * pimpl; 135 }; 136 137 } // namespace random 138 139 using random::random_device; 140 141 } // namespace boost 142 143 #endif /* BOOST_RANDOM_RANDOM_DEVICE_HPP */ 144