[src/trunk]: src/sys/kern entropy(9): Improve entropy warning messages and do...

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/b123ae47e4d3
branches:  trunk
changeset: 364395:b123ae47e4d3
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sun Mar 20 18:19:57 2022 +0000

description:
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.

diffstat:

 share/man/man4/rnd.4     |  20 ++++----------------
 share/man/man7/entropy.7 |  33 ++++++++++++++++++++++++++++-----
 sys/kern/kern_entropy.c  |  15 ++++++++-------
 3 files changed, 40 insertions(+), 28 deletions(-)

diffs (142 lines):

diff -r e2f60964c2f1 -r b123ae47e4d3 share/man/man4/rnd.4
--- a/share/man/man4/rnd.4      Sun Mar 20 18:04:52 2022 +0000
+++ b/share/man/man4/rnd.4      Sun Mar 20 18:19:57 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: rnd.4,v 1.39 2021/04/06 22:12:16 riastradh Exp $
+.\"    $NetBSD: rnd.4,v 1.40 2022/03/20 18:19:57 riastradh Exp $
 .\"
 .\" Copyright (c) 2014-2020 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -567,9 +567,9 @@
 subsystem may print the following warnings to the console likely
 indicating security issues:
 .Bl -diag -offset indent
-.It entropy: WARNING: extracting entropy too early
-Something requested extraction of entropy from the pool before it
-has ever reached full entropy in the system's estimation.
+.It WARNING: system needs entropy for security; see entropy(7)
+A process tried to draw from the entropy pool before enough inputs from
+reliable entropy sources have been entered.
 .Pp
 The entropy may be low enough that an adversary who sees the output
 could guess the state of the pool by brute force, so in this event the
@@ -579,18 +579,6 @@
 minute, so if you want to make sure it is gone you should consult
 .Dv kern.entropy.needed
 to confirm it is zero.
-.It entropy: WARNING: consolidating less than full entropy
-The operator triggered consolidation of entropy pending in per-CPU
-pools into the global pool when the system's estimate of the amount of
-entropy was still below the 256-bit threshold.
-.Pp
-This message can be safely ignored if the operator knows something the
-system doesn't, e.g. if the operator has flipped a coin 256 times and
-written the outcomes to
-.Pa /dev/random .
-.Pp
-This message is rate-limited to happen no more often than once per
-minute.
 .El
 .Pp
 The
diff -r e2f60964c2f1 -r b123ae47e4d3 share/man/man7/entropy.7
--- a/share/man/man7/entropy.7  Sun Mar 20 18:04:52 2022 +0000
+++ b/share/man/man7/entropy.7  Sun Mar 20 18:19:57 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: entropy.7,v 1.3 2021/01/15 15:17:09 riastradh Exp $
+.\"    $NetBSD: entropy.7,v 1.4 2022/03/20 18:19:58 riastradh Exp $
 .\"
 .\" Copyright (c) 2021 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -169,14 +169,15 @@
 tool.
 For example, you might use
 .Dl rndctl -S seed
-to save a seed from one machine, transfer it over a medium where you
-are confident there are no eavesdroppers to another machine, and load
-it with
+to save a seed from one machine, transfer it \(em over a medium where
+you are confident there are no eavesdroppers \(em to another machine,
+and load it with
 .Dl rndctl -L seed
 on the target machine; then run
 .Dl /etc/rc.d/random_seed stop
 on the target machine to ensure that the entropy will be saved for next
-boot, even if the system crashes or otherwise shuts down uncleanly.
+boot, even if the system later crashes or otherwise shuts down
+uncleanly.
 .Ic rndctl -S
 records the number of bits of entropy in the seed so that
 .Ic rndctl -L
@@ -215,6 +216,28 @@
 create new ones before allowing anyone to log in via
 .Xr ssh 1 .
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.Sh DIAGNOSTICS
+.Nx
+may print the following warnings to the console:
+.Bl -diag -offset indent
+.It WARNING: system needs entropy for security; see entropy(7)
+Some process tried to draw use entropy from
+.Nx ,
+e.g. to generate a key for cryptography, before enough inputs from
+reliable entropy sources have been obtained.
+The entropy may be low enough that an adversary could guess keys by
+brute force.
+.Pp
+This message is rate-limited, so if you have added entropy and want to
+verify that the problem is resolved, you should consult the
+.Dv kern.entropy.needed
+.Xr sysctl 7
+variable to confirm it is zero, rather than just look for the absence
+of this message; see
+.Xr rnd 4
+for details.
+.El
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .Sh SEE ALSO
 .Xr getrandom 2 ,
 .Xr arc4random 3 ,
diff -r e2f60964c2f1 -r b123ae47e4d3 sys/kern/kern_entropy.c
--- a/sys/kern/kern_entropy.c   Sun Mar 20 18:04:52 2022 +0000
+++ b/sys/kern/kern_entropy.c   Sun Mar 20 18:19:57 2022 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: kern_entropy.c,v 1.49 2022/03/20 14:30:56 riastradh Exp $      */
+/*     $NetBSD: kern_entropy.c,v 1.50 2022/03/20 18:19:58 riastradh Exp $      */
 
 /*-
  * Copyright (c) 2019 The NetBSD Foundation, Inc.
@@ -75,7 +75,7 @@
  */
 
 #include <sys/cdefs.h>
-__KERNEL_RCSID(0, "$NetBSD: kern_entropy.c,v 1.49 2022/03/20 14:30:56 riastradh Exp $");
+__KERNEL_RCSID(0, "$NetBSD: kern_entropy.c,v 1.50 2022/03/20 18:19:58 riastradh Exp $");
 
 #include <sys/param.h>
 #include <sys/types.h>
@@ -1112,9 +1112,9 @@
        atomic_store_relaxed(&E->needed, E->needed - diff);
        E->pending -= diff;
        if (__predict_false(E->needed > 0)) {
-               if (ratecheck(&lasttime, &interval) &&
-                   (boothowto & AB_DEBUG) != 0) {
-                       printf("entropy: WARNING:"
+               if ((boothowto & AB_DEBUG) != 0 &&
+                   ratecheck(&lasttime, &interval)) {
+                       printf("WARNING:"
                            " consolidating less than full entropy\n");
                }
        }
@@ -1408,8 +1408,9 @@
         */
        if (__predict_false(E->epoch == (unsigned)-1)) {
                if (ratecheck(&lasttime, &interval))
-                       printf("entropy: WARNING:"
-                           " extracting entropy too early\n");
+                       printf("WARNING:"
+                           " system needs entropy for security;"
+                           " see entropy(7)\n");
                atomic_store_relaxed(&E->needed, ENTROPY_CAPACITY*NBBY);
        }