Bump dates on man pages recently updated to mention VM clones.

PR kern/58632: getentropy(2) and arc4random(3) do not reseed on VM
fork

rnd(4): tweak markup a bit, consistently use .Li for sysctl vars

rnd(4): Document kern.entropy.epoch is unprivileged and elaborate.

Cross-reference acpivmgenid(4).

PR kern/58632: getentropy(2) and arc4random(3) do not reseed on VM
fork

branches: 1.41.2;
rnd(4): Document `entropy: best effort' in random(4).

branches: 1.40.2;
entropy(9): Improve entropy warning messages and documentation.

- For the main warning message, use less jargon, say `security', and
cite the entropy(7) man page for further reading. Document this in
rnd(4) and entropy(7).

- For the debug-only warning message, say `entropy' only once and omit
it from the rnd(4) man page -- it's not very important unless you're
debugging the kernel in which case you probably know what you're
doing enough to not need the text explained in the man page.

Remove sentence that has not been true since netbsd-6.

ioctl(RNDADDDATA) is not the only way to raise the entropy estimate;
privileged writes to /dev/random have the same effect.

rnd(4): Consistently call it the `global pool'.

The `ready pool' is a term I used in a draft that I never committed.

rnd(4): Fix formatting of authors paragraph with `.An -nosplit'.

Various entropy integration improvements.

- New /etc/security check for entropy in daily security report.

- New /etc/rc.d/entropy script runs (after random_seed and rndctl) to
check for entropy at boot -- in rc.conf, you can:

. set `entropy=check' to halt multiuser boot and enter single-user
mode if not enough entropy

. set `entropy=wait' to make multiuser boot wait until enough entropy

Default is to always boot without waiting -- and rely on other
channels like security report to alert the operator if there's a
problem.

- New man page entropy(7) discussing the higher-level concepts and
system integration with cross-references.

- New paragraph in afterboot(8) about entropy citing entropy(7) for
more details.

This change addresses many of the issues discussed in security/55659.
This is a first draft; happy to take improvements to the man pages and
scripted messages to improve clarity.

I considered changing motd to include an entropy warning with a
reference to the entropy(7) man page, but it's a little trickier:
- Not sure it's appropriate for all users to see at login rather than
users who have power to affect the entropy estimate (maybe it is,
just haven't decided).
- We only have a mechanism for changing once at boot; the message would
remain until next boot even if an operator adds enough entropy.
- The mechanism isn't really conducive to making a message appear
conditionally from boot to boot.

Update to reflect change to message.

Break line after macro arguments end. Use \- for minus.

Combine some related paragraphs.

Tighten language so it fits in one paragraph again.

This way the first two paragraphs have parallel structure:

- _Applications_ should read from /dev/urandom or sysctl kern.arandom...
- _Systems_ should be engineered to read once from /dev/random...

rnd.4: Bump dates.

rnd.4: Explain why libraries should use kern.arandom over /dev/urandom

Rewrite entropy subsystem.

Primary goals:

1. Use cryptography primitives designed and vetted by cryptographers.
2. Be honest about entropy estimation.
3. Propagate full entropy as soon as possible.
4. Simplify the APIs.
5. Reduce overhead of rnd_add_data and cprng_strong.
6. Reduce side channels of HWRNG data and human input sources.
7. Improve visibility of operation with sysctl and event counters.

Caveat: rngtest is no longer used generically for RND_TYPE_RNG
rndsources. Hardware RNG devices should have hardware-specific
health tests. For example, checking for two repeated 256-bit outputs
works to detect AMD's 2019 RDRAND bug. Not all hardware RNGs are
necessarily designed to produce exactly uniform output.

ENTROPY POOL

- A Keccak sponge, with test vectors, replaces the old LFSR/SHA-1
kludge as the cryptographic primitive.

- `Entropy depletion' is available for testing purposes with a sysctl
knob kern.entropy.depletion; otherwise it is disabled, and once the
system reaches full entropy it is assumed to stay there as far as
modern cryptography is concerned.

- No `entropy estimation' based on sample values. Such `entropy
estimation' is a contradiction in terms, dishonest to users, and a
potential source of side channels. It is the responsibility of the
driver author to study the entropy of the process that generates
the samples.

- Per-CPU gathering pools avoid contention on a global queue.

- Entropy is occasionally consolidated into global pool -- as soon as
it's ready, if we've never reached full entropy, and with a rate
limit afterward. Operators can force consolidation now by running
sysctl -w kern.entropy.consolidate=1.

- rndsink(9) API has been replaced by an epoch counter which changes
whenever entropy is consolidated into the global pool.
. Usage: Cache entropy_epoch() when you seed. If entropy_epoch()
has changed when you're about to use whatever you seeded, reseed.
. Epoch is never zero, so initialize cache to 0 if you want to reseed
on first use.
. Epoch is -1 iff we have never reached full entropy -- in other
words, the old rnd_initial_entropy is (entropy_epoch() != -1) --
but it is better if you check for changes rather than for -1, so
that if the system estimated its own entropy incorrectly, entropy
consolidation has the opportunity to prevent future compromise.

- Sysctls and event counters provide operator visibility into what's
happening:
. kern.entropy.needed - bits of entropy short of full entropy
. kern.entropy.pending - bits known to be pending in per-CPU pools,
can be consolidated with sysctl -w kern.entropy.consolidate=1
. kern.entropy.epoch - number of times consolidation has happened,
never 0, and -1 iff we have never reached full entropy

CPRNG_STRONG

- A cprng_strong instance is now a collection of per-CPU NIST
Hash_DRBGs. There are only two in the system: user_cprng for
/dev/urandom and sysctl kern.?random, and kern_cprng for kernel
users which may need to operate in interrupt context up to IPL_VM.

(Calling cprng_strong in interrupt context does not strike me as a
particularly good idea, so I added an event counter to see whether
anything actually does.)

- Event counters provide operator visibility into when reseeding
happens.

INTEL RDRAND/RDSEED, VIA C3 RNG (CPU_RNG)

- Unwired for now; will be rewired in a subsequent commit.

New sentence, new line. Use \(em.

Update NIST SP800-90A reference.

Replace slightly wrong rant by shorter and slightly less long rant.

(If X and Y in Z/2Z are independent, then so are X and X+Y. What was
I thinking.)

Update man page to reflect switch from CTR_DRBG to Hash_DRBG.

branches: 1.24.4; 1.24.12; 1.24.14;
Fix couple of typos:
s/intractible/intractable
s/contiuously/continuously

branches: 1.23.2; 1.23.4;
Correct rc.conf variable for random seed.

Note that it is enabled by default.

Update header file references in rnd man pages.

Rewrite /dev/random man page.

- Describe application usage up front.
- State the security model.
- Explain entropy.
- Describe current implementation strategy near the bottom.

branches: 1.20.10;
New sentence, new line.
Sort type descriptions.
Bump date for previous.

Address multiple problems with rnd(4)/cprng(9):

1) Add a per-cpu CPRNG to handle short reads from /dev/urandom so that
programs like perl don't drain the entropy pool dry by repeatedly
opening, reading 4 bytes, closing.

2) Really fix the locking around reseeds and destroys.

3) Fix the opportunistic-reseed strategy so it actually works, reseeding
existing RNGs once each (as they are used, so idle RNGs don't get
reseeded) until the pool is half empty or newly full again.

branches: 1.18.2;
New sentence, new line.
Bump date for previous.

Separate /dev/random pseudodevice implemenation from kernel entropy pool
implementation. Rewrite pseudodevice code to use cprng_strong(9).

The new pseudodevice is cloning, so each caller gets bits from a stream
generated with its own key. Users of /dev/urandom get their generators
keyed on a "best effort" basis -- the kernel will rekey generators
whenever the entropy pool hits the high water mark -- while users of
/dev/random get their generators rekeyed every time key-length bits
are output.

The underlying cprng_strong API can use AES-256 or AES-128, but we use
AES-128 because of concerns about related-key attacks on AES-256. This
improves performance (and reduces entropy pool depletion) significantly
for users of /dev/urandom but does cause users of /dev/random to rekey
twice as often.

Also fixes various bugs (including some missing locking and a reseed-counter
overflow in the CTR_DRBG code) found while testing this.

For long reads, this generator is approximately 20 times as fast as the
old generator (dd with bs=64K yields 53MB/sec on 2Ghz Core2 instead of
2.5MB/sec) and also uses a separate mutex per instance so concurrency
is greatly improved. For reads of typical key sizes for modern
cryptosystems (16-32 bytes) performance is about the same as the old
code: a little better for 32 bytes, a little worse for 16 bytes.

branches: 1.16.2; 1.16.8;
Use .In instead of .Aq Pa for header files.

Fix markup.

New sentence, new line.
Remove trailing whitespace.

document the RNDGETPOOLSTAT ioctl.

branches: 1.12.30;
u_intN_t -> uintN_t

Mention RND_TYPE_RNG.

Generate <>& symbolically. I'm avoiding .../dist/... directories for now.

Sort SEE ALSO, and paragraph fixes.

Use standard section headers; uppercase .Sh argument; remove quotes in
.Sh arguments.

Typos and whitespace fixes.

remove extra period in SEE ALL section

More and more of .Os cleanups. .Os is defined in the tmac.doc-common file,
so we shouldn't override it with versions in the manpages. Many more to
come.

Update to slightly altered rnd_attach_source() api

add experimental warning

branches: 1.2.2;
fix permissions

add a man page for user-level code and a little about the random internals