Module Name: src
Committed By: riastradh
Date: Tue Aug 27 11:21:02 UTC 2024
Modified Files:
src/share/man/man4: rnd.4
Log Message:
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
To generate a diff of this commit:
cvs rdiff -u -r1.41 -r1.42 src/share/man/man4/rnd.4
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man4/rnd.4
diff -u src/share/man/man4/rnd.4:1.41 src/share/man/man4/rnd.4:1.42
--- src/share/man/man4/rnd.4:1.41 Mon Aug 7 06:27:37 2023
+++ src/share/man/man4/rnd.4 Tue Aug 27 11:21:02 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: rnd.4,v 1.41 2023/08/07 06:27:37 riastradh Exp $
+.\" $NetBSD: rnd.4,v 1.42 2024/08/27 11:21:02 riastradh Exp $
.\"
.\" Copyright (c) 2014-2020 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -457,18 +457,37 @@ Number of bits of entropy pending in per
This is the amount of entropy that will be contributed to the global
pool at the next consolidation, such as from triggering
.Dv kern.entropy.consolidate .
+.El
+.Pp
+The following read-only
+.Xr sysctl 8
+variables provide information to any users, privileged or unprivileged:
+.Bl -tag -width abcd
.It Dv kern.entropy.epoch Pq Vt unsigned int
-Number of times system has reached full entropy, or entropy has been
-consolidated with
-.Dv kern.entropy.consolidate ,
-as an unsigned 32-bit integer.
-Consulted inside the kernel by subsystems such as
-.Xr cprng 9
+An integer that changes whenever the system determines applications
+should reseed from the system entropy pool.
+This can happen for various reasons:
+.Bl -dash -compact
+.It
+The system has reached full entropy for the first time.
+.It
+A virtual machine clone has been detected
+.Pq e.g., by Xr acpivmgenid 4 .
+.It
+An operator has set
+.Li kern.entropy.consolidate .
+.El
+.Pp
+Consulted by
+.Xr arc4random 3 ,
+and inside the kernel by subsystems such as
+.Xr cprng 9 ,
to decide whether to reseed.
+.Pp
Initially set to 2^32 \- 1
.Pq i.e., Li "(unsigned)\-1"
-meaning the system has never reached full entropy and the entropy has
-never been consolidated; never again set to 2^32 \- 1.
+meaning the system has never reached full entropy; never again set to
+2^32 \- 1.
Never zero, so applications can initialize a cache of the epoch to zero
to ensure they reseed the next time they check whether it is different
from the stored epoch.
@@ -625,6 +644,7 @@ The system has full entropy for the firs
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.Sh SEE ALSO
.Xr arc4random 3 ,
+.Xr acpivmgenid 4 ,
.Xr entropy 7 ,
.Xr rndctl 8 ,
.Xr cprng 9 ,
