From b149d2d1d97084ea0f9ff6209318ebc51e0d2b5d Mon Sep 17 00:00:00 2001 From: Matthew Dillon Date: Mon, 10 Jul 2006 22:52:31 +0000 Subject: [PATCH] Update the manual pages for the kernel random number generator. --- usr.sbin/rndcontrol/random.4 | 149 +++++++++++-------------------- usr.sbin/rndcontrol/rndcontrol.8 | 15 ++-- 2 files changed, 62 insertions(+), 102 deletions(-) diff --git a/usr.sbin/rndcontrol/random.4 b/usr.sbin/rndcontrol/random.4 index e10620d428..dd83383b8f 100644 --- a/usr.sbin/rndcontrol/random.4 +++ b/usr.sbin/rndcontrol/random.4 @@ -37,7 +37,7 @@ .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD: src/usr.sbin/rndcontrol/random.4,v 1.9.2.2 2001/11/24 16:14:18 dd Exp $ -.\" $DragonFly: src/usr.sbin/rndcontrol/random.4,v 1.4 2006/02/17 19:40:22 swildner Exp $ +.\" $DragonFly: src/usr.sbin/rndcontrol/random.4,v 1.5 2006/07/10 22:52:31 dillon Exp $ .\" .Dd October 21, 1995 .Dt RANDOM 4 i386 @@ -65,122 +65,81 @@ must be hard for outside attackers to observe, and use that to generate random numbers. In a Unix environment, this is best done from inside the kernel. .Pp -Sources of randomness from the environment include inter-keyboard -timings, inter-interrupt timings from some interrupts, and other -events which are both (a) non-deterministic and (b) hard for an -outside observer to measure. Randomness from these sources are -added to an "entropy pool", which is periodically mixed using the -MD5 compression function in CBC mode. As random bytes are mixed -into the entropy pool, the routines keep an -.Em estimate -of how many bits of randomness have been stored into the random number -generator's internal state. +Previous and contemporary +.Xr random 4 +implementations typically used +an "entropy" pool which was processed with a cryptographic hash +function such as MD5. However, at the time of this writing security +issues have been discovered in some of these functions +(MD4, MD5, SHA0, SHA1). .Pp -When random bytes are desired, they are obtained by taking the MD5 -hash of a counter plus the contents of the "entropy pool". The -reason for the MD5 hash is so that we can avoid exposing the -internal state of random number generator. Although the MD5 hash -does protect the pool, each random byte which is generated from -the pool reveals some information which was derived from the -internal state, and thus increases the amount of information an -outside attacker has available to try to make some guesses about -the random number generator's internal state. For this reason, -the routine decreases its internal estimate of how many bits of -"true randomness" are contained in the entropy pool as it outputs -random numbers. +This implementation uses A CSPRNG (Cryptographically Secure Pseudo +Random Number Generator) which is continuously reseeded as described above. .Pp -If this estimate goes to zero, the routine can still generate random -numbers; however it may now be possible for an attacker to analyze -the output of the random number generator, and the MD5 algorithm, -and thus have some success in guessing the output of the routine. -Phil Karn (who devised this mechanism of using MD5 plus a counter -to extract random numbers from an entropy pool) calls this -"practical randomness", since in the worst case this is equivalent -to hashing MD5 with a counter and an undisclosed secret. If MD5 is -a strong cryptographic hash, this should be fairly resistant to attack. -.Ss Exported interfaces \(em output -There are three exported interfaces; the first is one designed to -be used from within the kernel: -.Pp -.Bl -tag -width Pa -compact -.It Pa void get_random_bytes(void *buf, int nbytes); -.El -.Pp -This interface will return the requested number of random bytes, -and place it in the requested buffer. -.Pp -The two other interfaces are two character devices +The user interface consists of two character devices .Pa /dev/random and .Pa /dev/urandom . The .Pa /dev/random device is suitable for use when very high quality randomness is desired -(e.g. for key generation), as it will only return a maximum -of the number of bits of randomness (as estimated by the random number -generator) contained in the entropy pool. +(e.g. for key generation). Previous implementations of this device +attempted to limit the number of returned bytes based on a guess as to +the secureness of the pool. However, this resulted in the interface being +so undependable that most programs just started using /dev/urandom +instead of /dev/random. +The current +.Dx +implementation will return all requested bytes but the system reserves the +right in the future to limit the transfer rate to maintain the high quality +of randomness requested. .Pp The .Pa /dev/urandom -device does not have this limit, and will return as many bytes as are -requested. As more and more random bytes are requested without giving -time for the entropy pool to recharge, this will result in lower quality -random numbers. For many applications, however, this is acceptable. -.Ss Exported interfaces \(em input -The two current exported interfaces for gathering environmental -noise from the devices are: -.Pp -.Bl -tag -width Pa -compact -.It Pa void add_keyboard_randomness(unsigned char scancode); -.It Pa void add_interrupt_randomness(int irq); -.El -.Pp -The first function uses the inter-keypress timing, as well as the -scancode as random inputs into the "entropy pool". +device uses a different and much faster algorithm, but one which is not +considered to be as secure (though for all practical purposes it probably +is good enough). .Pp -The second function uses the inter-interrupt timing as random -inputs to the entropy pool. Note that not all interrupts are good -sources of randomness! For example, the timer interrupts is not a -good choice, because the periodicity of the interrupts is too -regular, and hence predictable to an attacker. Disk interrupts are -a better measure, since the timing of the disk interrupts are more -unpredictable. The routines try to estimate how many bits of -randomness a particular interrupt channel offers, by keeping track -of the first and second order deltas in the interrupt timings. +Root may write entropy to +.Pa /dev/random +to seed the random number generator only if the securelevel is less then +or equal to zero and the kern.seedenable sysctl is non-zero. A certain +degree of entropy is added by RC scripts during the boot sequence. .Sh ACKNOWLEDGEMENTS -The original core code was written by -.An Theodore Ts'o , -and was intended -for the Linux platform. -This was ported to -.Fx +The current algorithms are implemented by +.An Robin Carey +and were ported to +.Dx by -.An Mark Murray , -who also wrote the -.Xr rndcontrol 8 -utility. +.An Matthew Dillon . .Pp -Ideas for constructing this random number generator were derived -from the Pretty Good Privacy's random number generator, and from -private discussions with Phil Karn. This design has been further -modified by myself, so any flaws are solely my responsibility, and -should not be attributed to the authors of PGP or to Phil. -.Pp -The code for MD5 transform was taken from Colin Plumb's -implementation, which has been placed in the public domain. The -MD5 cryptographic checksum was devised by Ronald Rivest, and is -documented in RFC 1321, "The MD5 Message Digest Algorithm". +Mark Murray +wrote the +.Xr rndcontrol 8 +utility for +.Fx . .Pp -Further background information on this topic may be obtained from -RFC 1750, "Randomness Recommendations for Security", by Donald -Eastlake, Steve Crocker, and Jeff Schiller. +The +.Em IBAA +CSPRNG was developed by +.An Bob Jenkins +and is used by +.Pa /dev/random . +The +.Em L15 +CSPRNG (based on ARC4) +was developed by +.An Robin Carey +and is used by +.Pa /dev/urandom . .Sh FILES .Bl -tag -width Pa -compact .It Pa /dev/random .It Pa /dev/urandom .El .Sh "SEE ALSO" -.Xr rndcontrol 8 +.Xr rndcontrol 8 , +.Xr srandomdev 3 .Sh HISTORY The .Pa random , diff --git a/usr.sbin/rndcontrol/rndcontrol.8 b/usr.sbin/rndcontrol/rndcontrol.8 index aa51f995bf..fd8bd33884 100644 --- a/usr.sbin/rndcontrol/rndcontrol.8 +++ b/usr.sbin/rndcontrol/rndcontrol.8 @@ -24,7 +24,7 @@ .\" SUCH DAMAGE. .\" .\" $FreeBSD: src/usr.sbin/rndcontrol/rndcontrol.8,v 1.13.2.2 2001/12/21 09:05:32 ru Exp $ -.\" $DragonFly: src/usr.sbin/rndcontrol/rndcontrol.8,v 1.4 2006/03/26 22:56:58 swildner Exp $ +.\" $DragonFly: src/usr.sbin/rndcontrol/rndcontrol.8,v 1.5 2006/07/10 22:52:31 dillon Exp $ .\" .Dd October 20, 1995 .Dt RNDCONTROL 8 @@ -42,10 +42,8 @@ device .Sh DESCRIPTION The .Nm -command is used to set which interrupts are used to help randomise -the -.Dq "pool of entropy" -maintained by the kernel. +command is used to set which interrupts are used to help add entropy +to the CSPRNG maintained by the kernel. The .Pa /dev/random and @@ -71,7 +69,9 @@ This option may be repeated for more than one IRQ. .El .Pp -The default is to have no IRQ's being used. +By default, all IRQs will help develop entropy. The kernel uses a +rate-limited helper thread to add the actual entropy and even fast +interrupts should not detrimentally effect a running system. .Sh FILES .Bl -tag -width ".Pa /dev/urandom" -compact .It Pa /dev/random @@ -80,7 +80,8 @@ secure random device random device .El .Sh SEE ALSO -.Xr random 4 +.Xr random 4 , +.Xr srandomdev 3 .Sh HISTORY The .Nm -- 2.41.0