Sat Dec 17 21:25:12 2011 UTC ()
New sentence, new line. Fix some markup. Bump date for previous.


(wiz)
diff -r1.19 -r1.20 src/share/man/man9/rnd.9
cvs diff -r1.19 -r1.20 src/share/man/man9/rnd.9 (expand / switch to unified diff)

--- src/share/man/man9/rnd.9 2011/12/17 20:05:38 1.19
+++ src/share/man/man9/rnd.9 2011/12/17 21:25:12 1.20
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: rnd.9,v 1.19 2011/12/17 20:05:38 tls Exp $ 1.\" $NetBSD: rnd.9,v 1.20 2011/12/17 21:25:12 wiz 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
@@ -17,27 +17,27 @@ @@ -17,27 +17,27 @@
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
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 September 16, 2008 30.Dd December 17, 2011
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_uint32 38.Nm rnd_add_uint32
39.Nd functions to make a device available for entropy collection 39.Nd functions to make a device available for entropy collection
40.Sh SYNOPSIS 40.Sh SYNOPSIS
41.In sys/rnd.h 41.In sys/rnd.h
42.Ft void 42.Ft void
43.Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 43.Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
@@ -45,27 +45,28 @@ @@ -45,27 +45,28 @@
45.Fn rnd_detach_source "rndsource_element_t *rnd_source" 45.Fn rnd_detach_source "rndsource_element_t *rnd_source"
46.Ft void 46.Ft void
47.Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" 47.Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
48.Ft void 48.Ft void
49.Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "uint32_t datum" 49.Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "uint32_t datum"
50.Sh DESCRIPTION 50.Sh DESCRIPTION
51These 51These
52.Nm 52.Nm
53functions make a device available for entropy collection for 53functions make a device available for entropy collection for
54the kernel entropy pool, which provides key material for the 54the kernel entropy pool, which provides key material for the
55.Xr cprng 9 55.Xr cprng 9
56and 56and
57.Xr rnd 4 57.Xr rnd 4
58.Pa (/dev/random) interfaces. 58.Pa ( /dev/random )
 59interfaces.
59.Pp 60.Pp
60Ideally the first argument 61Ideally the first argument
61.Fa rnd_source 62.Fa rnd_source
62of these functions gets included in the devices' entity struct, 63of these functions gets included in the devices' entity struct,
63but any means to permanently (statically) attach one such argument 64but any means to permanently (statically) attach one such argument
64to one incarnation of the device is ok. 65to one incarnation of the device is ok.
65Do not share 66Do not share
66.Fa rnd_source 67.Fa rnd_source
67structures between two devices. 68structures between two devices.
68.Pp 69.Pp
69.Bl -tag -width 8n 70.Bl -tag -width 8n
70.It Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" 71.It Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
71This function announces the availability of a device for entropy collection. 72This function announces the availability of a device for entropy collection.
@@ -186,36 +187,35 @@ Next, data is mixed into the entropy poo @@ -186,36 +187,35 @@ Next, data is mixed into the entropy poo
186feedback shift register). 187feedback shift register).
187.Pp 188.Pp
188To extract data from the entropy pool, a cryptographically strong hash 189To extract data from the entropy pool, a cryptographically strong hash
189function is used. 190function is used.
190The output of this hash is mixed back into the pool using the LFSR, 191The output of this hash is mixed back into the pool using the LFSR,
191and then folded in half before being returned to the caller. 192and then folded in half before being returned to the caller.
192.Pp 193.Pp
193Mixing the actual hash into the pool causes the next extraction to 194Mixing the actual hash into the pool causes the next extraction to
194return a different value, even if no timing events were added to the 195return a different value, even if no timing events were added to the
195pool. 196pool.
196Folding the data in half prevents the caller to derive the 197Folding the data in half prevents the caller to derive the
197actual hash of the pool, preventing some attacks. 198actual hash of the pool, preventing some attacks.
198.Pp 199.Pp
199.Pp 200In the
200In the NetBSD kernel, values should be extracted from the entropy 201.Nx
201pool 202kernel, values should be extracted from the entropy pool
202.Em only 203.Em only
203via the 204via the
204.Xr cprng 9 205.Xr cprng 9
205interface. Direct access to the entropy pool is unsupported and 206interface.
206may be dangerous. There is no supported API for direct access to 207Direct access to the entropy pool is unsupported and may be dangerous.
207the output of the entropy pool. 208There is no supported API for direct access to the output of the entropy pool.
208.Pp 
209.\" .Sh ERRORS 209.\" .Sh ERRORS
210.Sh FILES 210.Sh FILES
211These functions are declared in src/sys/sys/rnd.h and defined in 211These functions are declared in src/sys/sys/rnd.h and defined in
212src/sys/dev/rnd.c. 212src/sys/dev/rnd.c.
213.Sh SEE ALSO 213.Sh SEE ALSO
214.Xr rnd 4 , 214.Xr rnd 4 ,
215.Xr rndctl 8 , 215.Xr rndctl 8 ,
216.Xr cprng 9 216.Xr cprng 9
217.Sh HISTORY 217.Sh HISTORY
218The random device was introduced in 218The random device was introduced in
219.Nx 1.3 . 219.Nx 1.3 .
220.Sh AUTHORS 220.Sh AUTHORS
221This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt] 221This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt]