RANDOM(4)

✨ NAME ✨

random — the entropy device 🎲💫

(and yes bestie, we're in section 4, the kernel interfaces manual — sit down, it's giving ✨kernel lore✨)

---

🌸 SYNOPSIS 🌸

device random
options RANDOM_LOADABLE
options RANDOM_ENABLE_UMA

---

🦋 DESCRIPTION 🦋

okay so, random is THE device. you read from it and it just keeps handing you random bytes, endlessly, no cap. infinite. it also accepts and reads data just like any ordinary file, so don't overthink it 💅

here's the tea though: the generator starts in an unseeded state, and it will block reads until it gets seeded for the very first time. and that's lowkey a problem — at system boot, when keys and stuff are being generated from random, that blocking can cause trouble. so like, steps should be taken to make sure seeding happens as soon as possible. fr fr. 🙈

you can also pull random bytes using the KERN_ARND sysctl. on the command line that looks like:

sysctl -x -B 16 kern.arandom

⚠️ but bestie — this sysctl will not return random bytes unless the random device is seeded. no seed, no bytes, periodt.

so this whole initial seeding thing is a bootstrapping problem and it needs very careful attention. in some cases it may be difficult to find enough randomness to seed a random number generator until a system is fully operational — but the system needs random numbers to become fully operational. 😭 it's (or more accurately should be) critically important that the random device is seeded before the first time it's used. and if a dummy or "blocking-only" device is what's being used, then it's the responsibility of the system architect to make sure no blocking reads hold up critical processes. that's on them, not on you 🫶

wanna see the current settings of the software random device? run:

sysctl kern.random

and you'll get something like:

kern.random.fortuna.minpoolsize: 64
kern.random.harvest.mask_symbolic: [HIGH_PERFORMANCE], ... ,CACHED
kern.random.harvest.mask_bin: 00111111111
kern.random.harvest.mask: 511
kern.random.random_sources: 'Intel Secure Key RNG'

other than

kern.random.fortuna.minpoolsize

and

kern.random.harvest.mask

all settings are read-only. so don't get any ideas 💀

• kern.random.fortuna.minpoolsize — this is the one that sets the seed threshold. a smaller number gives a faster seed, but a less secure one. in practice, values between 64 and 256 are acceptable ✨
• kern.random.harvest.mask — this bitmask picks the possible entropy sources. a 0 (zero) value means that corresponding source is not considered an entropy source. set the bit to 1 (one) if you want to use that source. and the kern.random.harvest.mask_bin and kern.random.harvest.mask_symbolic sysctls can be used to confirm the choices are correct 👑 note that disabled items in the latter one are listed in square brackets [like this]. see random_harvest(9) for more on the harvesting of entropy 🌾

okay now the compile-time options, because there are two and they matter:

• options RANDOM_LOADABLE — when this is used, the /dev/random device is not created until an "algorithm module" is loaded. the only module built by default is random_fortuna. the random_yarrow module was removed in FreeBSD 12. and heads up: this loadable module is slightly less efficient than its compiled-in equivalent, because some functions must be locked against load and unload events, and they also have to be indirect calls to allow for removal. tiny tax, big vibes 🧚
• options RANDOM_ENABLE_UMA — when this is used, the /dev/random device will obtain entropy from the zone allocator. this is potentially a very high rate, and if that's the case it will be of questionable use. if that is the case, use of this option is not recommended. determining whether that's the case is not trivial, so you'll need to experiment and measure using tools such as dtrace(1) 🔬

---

🌈 RANDOMNESS 🌈

okay so using randomness in computing is a rather subtle issue, because "random" means different things to different people. think about it: generating a password randomly, simulating a coin toss, choosing a random back-off period when a server doesn't respond — each one of those needs random numbers, but each one has different requirements. it's giving "everybody wants randomness, nobody agrees on what it is" 💅

• cryptographic randomness — passwords, session keys and the like need this. a cryptographic random number generator should be designed so its output is difficult to guess, even if a lot of auxiliary info is known (like when it was seeded, subsequent or previous output, and so on). on FreeBSD, seeding for cryptographic random number generators is provided by the random device, which provides real randomness ✨ the arc4random(3) library call provides a pseudo-random sequence that's generally reckoned to be suitable for simple cryptographic use. the OpenSSL library also has functions for managing randomness via things like RAND_bytes(3) and RAND_add(3) — note that OpenSSL uses the random device for seeding automatically, so it's handled, bestie 🫶
• randomness for simulation — needed in engineering or scientific software and games. first requirement: the random numbers produced conform to some well-known, usually uniform, distribution. the sequence of numbers should also appear numerically uncorrelated, since simulation often assumes independence of its random inputs. and often you want to reproduce the results of a simulation exactly, so that if the generator is seeded the same way, it produces the same results. a peripheral concern for simulation is just the speed of the random number generator 🏃♀️

another issue in simulation is the size of the state associated with the generator, and how frequently it repeats itself. for example, a program which shuffles a pack of cards should have 52! possible outputs, which requires the random number generator to have 52! starting states. that means the seed should have at least log_2(52!) ~ 226 bits of state if the program is to stand a chance of outputting all possible sequences, and the program needs some unbiased way of generating these bits. again, the random device could be used for seeding here, but in practice, smaller seeds are usually considered acceptable 🌸

FreeBSD provides two families of functions considered suitable for simulation. the random(3) family gives a random integer between 0 to (2**31)−1. the functions srandom(3), initstate(3) and setstate(3) are provided for deterministically setting the state of the generator, and srandomdev(3) is provided for setting the state via the random device. the drand48(3) family is also provided, and it gives random floating point numbers in various ranges 🎀

• randomness for collision avoidance — like in certain network protocols. slightly different semantics again. usually you expect the numbers to be uniform, since that produces the lowest chances of collision. and here again, seeding the generator is very important, because different instances of the generator are required to produce independent sequences. but the guessability or reproducibility of the sequence is unimportant, unlike the previous cases 😌
• rand(3) — FreeBSD does also provide this traditional library call, for compatibility purposes. however, it is known to be poor for simulation and absolutely unsuitable for cryptographic purposes, so its use is discouraged. bestie. i'm begging you. don't. 🙈

---

🎀 FILES 🎀

• /dev/random

---

⭐ SEE ALSO ⭐

• arc4random(3)
• drand48(3)
• rand(3)
• RAND_add(3)
• RAND_bytes(3)
• random(3)
• sysctl(8)
• random(9)

Ferguson, Schneier, and Kohno, Cryptography Engineering, Wiley, ISBN 978-0-470-47424-2. 📚

---

👑 HISTORY 👑

a random device appeared in FreeBSD 2.2. the current software implementation, introduced in FreeBSD 10.0, is by Mark R V Murray, and it's an implementation of the Fortuna algorithm by Ferguson et al. it replaces the previous Yarrow implementation, which was introduced in FreeBSD 5.0. the Yarrow algorithm is no longer supported by its authors, and is therefore no longer available. rip yarrow, you served 🫡💀

---

okay that's the whole page, you ate it, you're literally a kernel cryptographer now 💖 this one came from Debian, dated August 26, 2018, and it lives at RANDOM(4) — go seed something responsibly, bestie ✨🎲🌸