diff --git a/src/os.rs b/src/os.rs index a5461d17c1..e4598a3c50 100644 --- a/src/os.rs +++ b/src/os.rs @@ -24,10 +24,17 @@ use rand_core::{RngCore, Error, ErrorKind, impls}; /// most applications. Commonly it is used to initialize a user-space RNG, which /// can then be used with much lower overhead. /// -/// Sometimes there is the misconception that `OsRng` somehow provides 'better' -/// random numbers than some good user-space cryptographic random number -/// generator. This is not true, but `OsRng` has a role in initializing such an -/// RNG. The initial seed of randomness has to come from somewhere. +/// Generally you can say that the values generated by `OsRng` are not in some +/// way 'better' than those generated by a good user-space cryptographic random +/// number generator. It is not necessary to use `OsRng` if your only +/// requirements are 'good' random numbers. +/// +/// Where `OsRng` especially has a role is in seeding user-space RNGs. The +/// initial seed of randomness has to come from somewhere. And it can also be a +/// good choice if you need a small number of secure random values. We can +/// expect the RNG of the operating system to have mitigations in place for +/// vulnerabilities such as side-channel attacks. But in general it is best rely +/// on security-oriented libraries in such cases, such as OpenSSL or Ring. /// /// You may prefer to use [`EntropyRng`] instead of `OsRng`. Is is unlikely, but /// not entirely theoretical, for `OsRng` to fail. In such cases `EntropyRng`