History log of /src/share/man/man7/entropy.7
Revision (<<< Hide revision tags) (Show revision tags >>>) Date Author Comments
Revision tags: perseant-exfatfs-base-20250801 netbsd-11-base perseant-exfatfs-base-20240630 perseant-exfatfs-base
# 1.10 20-Jul-2023 gutteridge

entropy.7: add a missing word to a sentence

While here, bump the date to reflect when substantive changes were last
made.


# 1.9 30-Jun-2023 riastradh

entropy(9): Reintroduce netbsd<=9 time-delta estimator for unblocking.

The system will (in a subsequent change) by default block for this
condition before almost all of userland is running (including
/etc/rc.d/sshd key generation). That way, a never-blocking
getentropy(3) API will never return any data without at least
best-effort entropy like netbsd<=9 did to applications except in
single-user mode (where you have to be careful about everything
anyway) or in the few processes that run before a seed can even be
loaded (where blocking indefinitely, e.g. when generating a stack
protector cookie in libc, could pose a severe availability problem
that can't be configured away, but where the security impact is low).

However, (in another subsequent change) we will continue to use
_only_ HWRNG driver estimates and seed estimates, and _not_
time-delta estimator, for _warning_ about security in motd, daily
security report, etc. And if HWRNG/seed provides enough entropy
before time-delta estimator does, that will unblock /dev/random too.

The result is:

- Machines with HWRNG or seed won't warn about entropy and will
essentially never block -- even on first boot without a seed, it
will take only as long as the fastest HWRNG to unblock.

- Machines with neither HWRNG nor seed:
. will warn about entropy, giving feedback about security;
and
. will avoid returning anything more predictable than netbsd<=9;
but
. won't block (much) longer than netbsd<=9 would (and won't block
again after blocking once, except with kern.entropy.depletion=1 for
testing).

(The threshold for unblocking is now somewhat higher than before:
512 samples that pass the time-delta estimator, rather than 80 as
it used to be.)

And, of course, adding a seed (or HWRNG) will prevent both warnings
and blocking.

The mechanism is:

1. /dev/random will block until _either_

(a) enough bits of entropy (256) from reliable sources have been
added to the pool, _or_

(b) enough samples have been added from any sources (512), passing
the old time-delta entropy estimator, that the possible
security benefit doesn't justify holding up availability any
longer (`best effort'), except on systems with higher security
requirements like securelevel=2 which can disable non-HWRNG,
non-seed sources with rndctl_flags in rc.conf(5).

2. dmesg will report `entropy: ready' when 1(a) is satisfied, but if
1(b) is satisfied first, it will report `entropy: best effort', so
the concise log messages will reflect the timing and whether in
any period of time any of the system might be relying on best
effort entropy.

3. The sysctl knob kern.entropy.needed (and the ioctl RNDGETPOOLSTAT
variable rndpoolstat_t::added) still reflects the number of bits
of entropy from reliable sources, so we can still use this to
suggest regenerating ssh keys.

This matters on platforms that can only be reached, after flashing
an installation image, by sshing in over a (private) network, like
small network appliances or remote virtual machines without
(interactive) serial consoles. If we blocked indefinitely at boot
when generating ssh keys, such platforms would be unusable. This
way, platforms are usable, but operators can still be advised at
login time to regenerate keys as soon as they can actually load
entropy onto the system, e.g. with rndctl(8) on a seed file copied
from a local machine over the (private) network.

4. On machines without HWRNG, using a seed file still suppresses
warnings for users who need more confident security. But it is no
longer necessary for availability.

This is a compromise between availability and security:

- The security mechanism of blocking indefinitely on machines without
HWRNG hurts availability too much, as painful experience over the
multiple years since I made the mistake of introducing it have
shown. (Sorry!)

- The other main alternative, not having a blocking path at all (as I
pushed for, and as OpenBSD has done for a long time) could
potentially reduce security vs netbsd<=9, and would run against the
expectations set by many popular operating systems to the severe
detriment of public perception of NetBSD security.

Even though we can't _confidently_ assess enough entropy from, e.g.,
sampling interrupt timings, this is the traditional behaviour that
most operating systems provide -- and the result here is a net
nondecrease in security over netbsd<=9, because all paths from the
entropy pool to userland now have at least as high a standard before
returning data as they did in netbsd<=9.

PR kern/55641
PR pkg/55847
PR kern/57185
https://mail-index.netbsd.org/current-users/2020/09/02/msg039470.html
https://mail-index.netbsd.org/current-users/2020/11/21/msg039931.html
https://mail-index.netbsd.org/current-users/2020/12/05/msg040019.html

XXX pullup-10


# 1.8 23-Mar-2023 uwe

entropy(7): don't use .Nx inside .Ss

These macros don't adapt to context style, so in PostScript output the
.Nx inside .Ss is suddenly in a different font.


# 1.7 23-Mar-2023 uwe

entropy(7): use .Ql instead of .Sc Li


# 1.6 23-Mar-2023 uwe

entropy(7): don't try to cram things into one-liners


# 1.5 23-Mar-2023 riastradh

entropy(7): Omit needless offset for diagnostic listing.


Revision tags: netbsd-10-base
# 1.4 20-Mar-2022 riastradh

branches: 1.4.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.


Revision tags: cjep_sun2x-base1 cjep_sun2x-base cjep_staticlib_x-base1 cjep_staticlib_x-base
# 1.3 15-Jan-2021 riastradh

Clarify that `entropy' may be left unset in rc.conf.


# 1.2 13-Jan-2021 riastradh

entropy(7): Add missing URL to reference.


# 1.1 10-Jan-2021 riastradh

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.