Wed Jul 15 13:47:40 2020 UTC ()
Pull up following revision(s) (requested by riastradh in ticket #1007):

	share/man/man9/rnd.9: revision 1.26
	share/man/man9/rnd.9: revision 1.27

Update rnd(9) man page to reflect reality since netbsd-7.
- Note rndsource_setcb, RND_FLAG_HASCB, and rnd_add_data_sync.
- Note user's obligation to serialize access to each rndsource.

Simplify macro usage.


(martin)
diff -r1.25 -r1.25.18.1 src/share/man/man9/rnd.9
cvs diff -r1.25 -r1.25.18.1 src/share/man/man9/rnd.9 (expand / switch to unified diff)

--- src/share/man/man9/rnd.9 2015/04/13 22:23:54 1.25
+++ src/share/man/man9/rnd.9 2020/07/15 13:47:40 1.25.18.1
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: rnd.9,v 1.25 2015/04/13 22:23:54 riastradh Exp $ 1.\" $NetBSD: rnd.9,v 1.25.18.1 2020/07/15 13:47:40 martin Exp $
2.\" 2.\"
3.\" Copyright (c) 1997 The NetBSD Foundation, Inc. 3.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This documentation is derived from text contributed to The NetBSD 6.\" This documentation is derived from text contributed to The NetBSD
7.\" Foundation by S.P.Zeidler (aka stargazer). 7.\" Foundation by S.P.Zeidler (aka stargazer).
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -25,59 +25,113 @@ @@ -25,59 +25,113 @@
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd August 10, 2014 30.Dd August 10, 2014
31.Dt RND 9 31.Dt RND 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm RND , 34.Nm RND ,
35.Nm rnd_attach_source , 35.Nm rnd_attach_source ,
36.Nm rnd_detach_source , 36.Nm rnd_detach_source ,
37.Nm rnd_add_data , 37.Nm rnd_add_data ,
 38.Nm rnd_add_data_sync ,
38.Nm rnd_add_uint32 39.Nm rnd_add_uint32
39.Nd functions to make a device available for entropy collection 40.Nd functions to make a device available for entropy collection
40.Sh SYNOPSIS 41.Sh SYNOPSIS
41.In sys/rndsource.h 42.In sys/rndsource.h
42.Ft void 43.Ft void
 44.Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie"
 45.Ft void
43.Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 46.Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
44.Ft void 47.Ft void
45.Fn rnd_detach_source "krndsource_t *rnd_source" 48.Fn rnd_detach_source "krndsource_t *rnd_source"
46.Ft void 49.Ft void
47.Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 50.Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
48.Ft void 51.Ft void
 52.Fn rnd_add_data_sync "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
 53.Ft void
49.Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" 54.Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum"
50.Sh DESCRIPTION 55.Sh DESCRIPTION
51These 56These
52.Nm 57.Nm
53functions make a device available for entropy collection for 58functions make a device available for entropy collection for
54the kernel entropy pool, which provides key material for the 59the kernel entropy pool, which provides key material for the
55.Xr cprng 9 60.Xr cprng 9
56and 61and
57.Xr rnd 4 62.Xr rnd 4
58.Pa ( /dev/random ) 63.Pa ( /dev/random )
59interfaces. 64interfaces.
60.Pp 65.Pp
 66The caller must zero an
 67.Fa rnd_source
 68object before using it.
61Ideally the first argument 69Ideally the first argument
62.Fa rnd_source 70.Fa rnd_source
63of these functions gets included in the devices' entity struct, 71of these functions gets included in the devices' entity struct,
64but any means to permanently (statically) attach one such argument 72but any means to permanently (statically) attach one such argument
65to one incarnation of the device is ok. 73to one incarnation of the device is ok.
66Do not share 74Do not share
67.Fa rnd_source 75.Fa rnd_source
68structures between two devices. 76structures between two devices, and make sure to serialize all access
69.Pp 77to each
 78.Fa rnd_source ,
 79for example with
 80.Xr mutex 9 .
70.Bl -tag -width 8n 81.Bl -tag -width 8n
 82.It Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie"
 83This function sets a callback to be invoked when the kernel entropy
 84pool is hungry.
 85It is optional; if used, it must be used
 86.Em before
 87.Fn rnd_attach_source ,
 88and the caller must pass
 89.Dv RND_FLAG_HASCB
 90to
 91.Fn rnd_attach_source
 92in order for the callback to be used.
 93The callback is invoked as
 94.Fa callback ( Fa nbytes , Fa cookie ) ,
 95where
 96.Fa nbytes
 97is the number of bytes requested for the entropy pool, and
 98.Fa cookie
 99is the cookie that was passed to
 100.Fn rndsource_setcb .
 101The callback normally does one of two things:
 102.Bl -dash
 103.It
 104Sends a request to a hardware device for entropy and returns.
 105The hardware will later return data asynchronously by an interrupt, and
 106the callback will use
 107.Fn rnd_add_data
 108or
 109.Fn rnd_add_uint32
 110to add the data to the pool.
 111.It
 112Synchronously gathers entropy from hardware \(em for example, by a CPU
 113instruction like Intel RDSEED.
 114In this case, in order to add data to the pool
 115.Em before
 116returning, the callback
 117.Em must
 118use
 119.Fn rnd_add_data_sync ,
 120not
 121.Fn rnd_add_data
 122or
 123.Fn rnd_add_uint32 .
 124.El
71.It Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 125.It Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
72This function announces the availability of a device for entropy collection. 126This function announces the availability of a device for entropy collection.
73It must be called before the source struct pointed to by 127It must be called before the source struct pointed to by
74.Fa rnd_source 128.Fa rnd_source
75is used in any of the following functions. 129is used in any of the following functions.
76.Pp 130.Pp
77.Fa devname 131.Fa devname
78is the name of the device. 132is the name of the device.
79It is used to print a message (if the kernel is compiled with 133It is used to print a message (if the kernel is compiled with
80``options RND_VERBOSE'') and also for status information printed with 134``options RND_VERBOSE'') and also for status information printed with
81.Xr rndctl 8 . 135.Xr rndctl 8 .
82.Pp 136.Pp
83.Fa source_type 137.Fa source_type
@@ -99,37 +153,39 @@ is not to be used as a type. @@ -99,37 +153,39 @@ is not to be used as a type.
99It is used internally to the rnd system. 153It is used internally to the rnd system.
100.Pp 154.Pp
101.Fa flags 155.Fa flags
102are the logical OR of 156are the logical OR of
103.Dv RND_FLAG_COLLECT_VALUE 157.Dv RND_FLAG_COLLECT_VALUE
104(mix data provided by this source into the pool) 158(mix data provided by this source into the pool)
105.Dv RND_FLAG_COLLECT_TIME 159.Dv RND_FLAG_COLLECT_TIME
106(mix timestamps from this source into the pool) 160(mix timestamps from this source into the pool)
107.Dv RND_FLAG_ESTIMATE_VALUE 161.Dv RND_FLAG_ESTIMATE_VALUE
108(use a delta estimator to count bits of entropy from this source's data towards 162(use a delta estimator to count bits of entropy from this source's data towards
109the pool estimate) 163the pool estimate)
110.Dv RND_FLAG_ESTIMATE_TIME 164.Dv RND_FLAG_ESTIMATE_TIME
111(use a delta estimator to count bits of entropy from this source's timestamps 165(use a delta estimator to count bits of entropy from this source's timestamps
112towards the pool estimate). 166towards the pool estimate)
 167.Dv RND_FLAG_HASCB
 168(caller specified a callback with
 169.Fn rndsource_setcb ) .
113For many devices, 170For many devices,
114.Dv RND_FLAG_DEFAULT 171.Dv RND_FLAG_DEFAULT
115.Dv ( RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME | RND_FLAG_ESTIMATE_TIME ) 172.Dv ( RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME | RND_FLAG_ESTIMATE_TIME )
116is the best choice. 173is the best choice.
117Note that devices of type 174Note that devices of type
118.Dv RND_TYPE_NET 175.Dv RND_TYPE_NET
119default to 176default to
120.Dv RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME 177.Dv RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME
121(no entropy counted). 178(no entropy counted).
122.Pp 
123.It Fn rnd_detach_source "krndsource_t *rnd_source" 179.It Fn rnd_detach_source "krndsource_t *rnd_source"
124This function disconnects the device from entropy collection. 180This function disconnects the device from entropy collection.
125.It Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" 181.It Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum"
126This function adds the value of 182This function adds the value of
127.Va datum 183.Va datum
128to the entropy pool. 184to the entropy pool.
129No entropy is assumed to be collected from this value, it merely helps 185No entropy is assumed to be collected from this value, it merely helps
130stir the entropy pool. 186stir the entropy pool.
131All entropy is gathered from jitter between the timing of events. 187All entropy is gathered from jitter between the timing of events.
132.Pp 188.Pp
133Note that using a constant for 189Note that using a constant for
134.Va datum 190.Va datum
135does not weaken security, but it does 191does not weaken security, but it does
@@ -145,26 +201,34 @@ the interrupt handler, since on some sys @@ -145,26 +201,34 @@ the interrupt handler, since on some sys
145.Pp 201.Pp
146This function loses nearly all usefulness if it is called from a scheduled 202This function loses nearly all usefulness if it is called from a scheduled
147software interrupt. 203software interrupt.
148If that is the only way to add the device as an entropy source, don't. 204If that is the only way to add the device as an entropy source, don't.
149.Pp 205.Pp
150If it is desired to mix in the 206If it is desired to mix in the
151.Va datum 207.Va datum
152and to add in a timestamp, but not to actually estimate entropy from a source 208and to add in a timestamp, but not to actually estimate entropy from a source
153of randomness, passing 209of randomness, passing
154.Dv NULL 210.Dv NULL
155for 211for
156.Va rnd_source 212.Va rnd_source
157is permitted, and the device does not need to be attached. 213is permitted, and the device does not need to be attached.
 214.Pp
 215.Fn rnd_add_uint32
 216.Em must not
 217be used during a callback as set with
 218.Fn rndsource_setcb ;
 219use
 220.Fn rnd_add_data_sync
 221instead.
158.It Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 222.It Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
159adds (hopefully) random 223adds (hopefully) random
160.Fa data 224.Fa data
161to the entropy pool. 225to the entropy pool.
162.Fa len 226.Fa len
163is the number of bytes in 227is the number of bytes in
164.Fa data 228.Fa data
165and 229and
166.Fa entropy 230.Fa entropy
167is an "entropy quality" measurement. 231is an "entropy quality" measurement.
168If every bit of 232If every bit of
169.Fa data 233.Fa data
170is known to be random, 234is known to be random,
@@ -173,26 +237,34 @@ is the number of bits in @@ -173,26 +237,34 @@ is the number of bits in
173.Fa data . 237.Fa data .
174.Pp 238.Pp
175Timing information is also used to add entropy into the system, using 239Timing information is also used to add entropy into the system, using
176inter-event timings. 240inter-event timings.
177.Pp 241.Pp
178If it is desired to mix in the 242If it is desired to mix in the
179.Va data 243.Va data
180and to add in a timestamp, but not to actually estimate entropy from a source 244and to add in a timestamp, but not to actually estimate entropy from a source
181of randomness, passing 245of randomness, passing
182.Dv NULL 246.Dv NULL
183for 247for
184.Va rnd_source 248.Va rnd_source
185is permitted, and the device does not need to be attached. 249is permitted, and the device does not need to be attached.
 250.Pp
 251.Fn rnd_add_data
 252.Em must not
 253be used during a callback as set with
 254.Fn rndsource_setcb ;
 255use
 256.Fn rnd_add_data_sync
 257instead.
186.El 258.El
187.Sh INTERNAL ENTROPY POOL MANAGEMENT 259.Sh INTERNAL ENTROPY POOL MANAGEMENT
188When a hardware event occurs (such as completion of a hard drive 260When a hardware event occurs (such as completion of a hard drive
189transfer or an interrupt from a network device) a timestamp is 261transfer or an interrupt from a network device) a timestamp is
190generated. 262generated.
191This timestamp is compared to the previous timestamp 263This timestamp is compared to the previous timestamp
192recorded for the device, and the first, second, and third order 264recorded for the device, and the first, second, and third order
193differentials are calculated. 265differentials are calculated.
194.Pp 266.Pp
195If any of these differentials is zero, no entropy is assumed to 267If any of these differentials is zero, no entropy is assumed to
196have been gathered. 268have been gathered.
197If all are non-zero, one bit is assumed. 269If all are non-zero, one bit is assumed.
198Next, data is mixed into the entropy pool using an LFSR (linear 270Next, data is mixed into the entropy pool using an LFSR (linear