diff --git a/man2/getrandom.2 b/man2/getrandom.2 index db3a0f639..32c55bde2 100644 --- a/man2/getrandom.2 +++ b/man2/getrandom.2 @@ -41,20 +41,6 @@ with up to random bytes. These bytes can be used to seed user-space random number generators or for cryptographic purposes. -.PP -.BR getrandom () -relies on entropy gathered from device drivers and other sources of -environmental noise. -Unnecessarily reading large quantities of data will have a negative impact -on other users of the -.I /dev/random -and -.I /dev/urandom -devices. -Therefore, -.BR getrandom () -should not be used for Monte Carlo simulations or other -programs/algorithms which are doing probabilistic sampling. By default, .BR getrandom () @@ -277,19 +263,75 @@ a return of fewer bytes than requested should never happen, but the careful programmer will check for this anyway! .SS Choice of random device Unless you are doing long-term key generation (and perhaps not even -then), you probably shouldn't be using -.B GRND_RANDOM. -The cryptographic algorithms used for -.I /dev/urandom +then), you probably shouldn't be using the +.BR getrandom () +.BR GRND_RANDOM +flag or the +.IR /dev/random +device. + +Instead, use +.IR /dev/urandom ; +the cryptographic algorithms used for +.IR /dev/urandom ; are quite conservative, and so should be sufficient for all purposes. + The disadvantage of .B GRND_RANDOM -is that it can block. +and reads from +.I dev/random +is that the operation can block. Furthermore, dealing with the partially fulfilled -.BR getrandom () requests that can occur when using .B GRND_RANDOM +or when reading from +.I /dev/random increases code complexity. +.\" +.SS Usage recommendations +The kernel random-number generator +relies on entropy gathered from device drivers and other sources of +environmental noise. +It is designed to produce a small +amount of high-quality seed material to seed a +cryptographic pseudo-random number generator (CPRNG). +It is designed for security, not speed, and is poorly +suited to generating large amounts of cryptographic random data. +Users should be very economical in the amount of seed +material that they consume via +.BR getrandom (), +.IR /dev/urandom , +and +.IR /dev/random . +Consuming unnecessarily large quantities of data via these interfaces +will have a negative impact on other consumers of randomness. + +These interfaces should not be used to provide large quantities +of data for Monte Carlo simulations or other +programs/algorithms which are doing probabilistic sampling. +And indeed, such usage is unnecessary (and will be slow): +instead, use these interfaces to provide a small amount of +data used to seed a user-space pseudo-random number generator +for use by such applications. +.\" +.SS Generating cryptographic keys +The amount of seed material required to generate a cryptographic key +equals the effective key size of the key. +For example, a 3072-bit RSA +or Diffie-Hellman private key has an effective key size of 128 bits +(it requires about 2^128 operations to break) so a key generator +needs only 128 bits (16 bytes) of seed material from +.IR /dev/random . + +While some safety margin above that minimum is reasonable, as a guard +against flaws in the CPRNG algorithm, no cryptographic primitive +available today can hope to promise more than 256 bits of security, +so if any program reads more than 256 bits (32 bytes) from the kernel +random pool per invocation, or per reasonable reseed interval (not less +than one minute), that should be taken as a sign that its cryptography is +.I not +skillfully implemented. +.\" .SS Emulating OpenBSD's getentropy() The .BR getentropy () diff --git a/man4/random.4 b/man4/random.4 index 5e6c29652..3fbb16184 100644 --- a/man4/random.4 +++ b/man4/random.4 @@ -139,35 +139,9 @@ may block, users will usually want to open it in nonblocking mode and provide some sort of user notification if the desired entropy is not immediately available. -The kernel random-number generator is designed to produce a small -amount of high-quality seed material to seed a -cryptographic pseudo-random number generator (CPRNG). -It is designed for security, not speed, and is poorly -suited to generating large amounts of random data. -Users should be very economical in the amount of seed -material that they read from -.IR /dev/urandom -(and -.IR /dev/random ); -unnecessarily reading large quantities of data from this device will have -a negative impact on other users of the device. - -The amount of seed material required to generate a cryptographic key -equals the effective key size of the key. -For example, a 3072-bit RSA -or Diffie-Hellman private key has an effective key size of 128 bits -(it requires about 2^128 operations to break) so a key generator -needs only 128 bits (16 bytes) of seed material from -.IR /dev/random . - -While some safety margin above that minimum is reasonable, as a guard -against flaws in the CPRNG algorithm, no cryptographic primitive -available today can hope to promise more than 256 bits of security, -so if any program reads more than 256 bits (32 bytes) from the kernel -random pool per invocation, or per reasonable reseed interval (not less -than one minute), that should be taken as a sign that its cryptography is -.I not -skillfully implemented. +For further recommendations on the use of these devices, see +.BR getrandom (2). +.\" .SS Configuration If your system does not have \fI/dev/random\fP and \fI/dev/urandom\fP created already, they