[src/trunk]: src/sys/kern entropy(9): Note rules about how to use entropy_ext...

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

details:   https://anonhg.NetBSD.org/src/rev/ca6e21f9b343
branches:  trunk
changeset: 366065:ca6e21f9b343
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Fri May 13 09:39:52 2022 +0000

description:
entropy(9): Note rules about how to use entropy_extract output.

diffstat:

 sys/kern/kern_entropy.c |  14 ++++++++++++--
 1 files changed, 12 insertions(+), 2 deletions(-)

diffs (35 lines):

diff -r eda232efa87e -r ca6e21f9b343 sys/kern/kern_entropy.c
--- a/sys/kern/kern_entropy.c   Fri May 13 09:39:40 2022 +0000
+++ b/sys/kern/kern_entropy.c   Fri May 13 09:39:52 2022 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: kern_entropy.c,v 1.54 2022/03/24 12:58:56 riastradh Exp $      */
+/*     $NetBSD: kern_entropy.c,v 1.55 2022/05/13 09:39:52 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.54 2022/03/24 12:58:56 riastradh Exp $");
+__KERNEL_RCSID(0, "$NetBSD: kern_entropy.c,v 1.55 2022/05/13 09:39:52 riastradh Exp $");
 
 #include <sys/param.h>
 #include <sys/types.h>
@@ -1341,6 +1341,16 @@
  *
  *     Extract len bytes from the global entropy pool into buf.
  *
+ *     Caller MUST NOT expose these bytes directly -- must use them
+ *     ONLY to seed a cryptographic pseudorandom number generator
+ *     (`CPRNG'), a.k.a. deterministic random bit generator (`DRBG'),
+ *     and then erase them.  entropy_extract does not, on its own,
+ *     provide backtracking resistance -- it must be combined with a
+ *     PRNG/DRBG that does.
+ *
+ *     You generally shouldn't use this directly -- use cprng(9)
+ *     instead.
+ *
  *     Flags may have:
  *
  *             ENTROPY_WAIT    Wait for entropy if not available yet.