Annotation of src/share/man/man9/rnd.9, Revision 1.22.2.1
1.22.2.1! tls 1: .\" $NetBSD$
1.1 explorer 2: .\"
3: .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
4: .\" All rights reserved.
5: .\"
6: .\" This documentation is derived from text contributed to The NetBSD
7: .\" Foundation by S.P.Zeidler (aka stargazer).
8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\"
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
20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
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
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
28: .\" POSSIBILITY OF SUCH DAMAGE.
29: .\"
1.22.2.1! tls 30: .Dd August 10, 2014
1.1 explorer 31: .Dt RND 9
1.6 garbled 32: .Os
1.1 explorer 33: .Sh NAME
1.2 mrg 34: .Nm RND ,
35: .Nm rnd_attach_source ,
36: .Nm rnd_detach_source ,
37: .Nm rnd_add_data ,
38: .Nm rnd_add_uint32
1.1 explorer 39: .Nd functions to make a device available for entropy collection
40: .Sh SYNOPSIS
1.14 wiz 41: .In sys/rnd.h
1.1 explorer 42: .Ft void
1.22 pgoyette 43: .Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
1.1 explorer 44: .Ft void
1.22 pgoyette 45: .Fn rnd_detach_source "krndsource_t *rnd_source"
1.1 explorer 46: .Ft void
1.22 pgoyette 47: .Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
1.1 explorer 48: .Ft void
1.22 pgoyette 49: .Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum"
1.1 explorer 50: .Sh DESCRIPTION
51: These
1.7 lukem 52: .Nm
53: functions make a device available for entropy collection for
1.19 tls 54: the kernel entropy pool, which provides key material for the
55: .Xr cprng 9
56: and
57: .Xr rnd 4
1.20 wiz 58: .Pa ( /dev/random )
59: interfaces.
1.7 lukem 60: .Pp
1.1 explorer 61: Ideally the first argument
62: .Fa rnd_source
1.8 wiz 63: of these functions gets included in the devices' entity struct,
1.19 tls 64: but any means to permanently (statically) attach one such argument
1.13 wiz 65: to one incarnation of the device is ok.
66: Do not share
1.8 wiz 67: .Fa rnd_source
1.1 explorer 68: structures between two devices.
1.7 lukem 69: .Pp
70: .Bl -tag -width 8n
1.22 pgoyette 71: .It Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
1.1 explorer 72: This function announces the availability of a device for entropy collection.
73: It must be called before the source struct pointed to by
74: .Fa rnd_source
75: is used in any of the following functions.
1.7 lukem 76: .Pp
1.8 wiz 77: .Fa devname
1.13 wiz 78: is the name of the device.
79: It is used to print a message (if the kernel is compiled with
80: ``options RND_VERBOSE'') and also for status information printed with
1.1 explorer 81: .Xr rndctl 8 .
1.7 lukem 82: .Pp
1.4 explorer 83: .Fa source_type
1.8 wiz 84: is
85: .Dv RND_TYPE_NET
86: for network devices,
87: .Dv RND_TYPE_DISK
1.1 explorer 88: for physical disks,
1.8 wiz 89: .Dv RND_TYPE_TAPE
1.17 jmcneill 90: for a tape drive,
1.8 wiz 91: .Dv RND_TYPE_TTY
1.22 pgoyette 92: for a tty,
1.17 jmcneill 93: .Dv RND_TYPE_RNG
1.22 pgoyette 94: for a random number generator, and
95: .Dv RND_TYPE_ENV
96: for an environment sensor.
1.8 wiz 97: .Dv RND_TYPE_UNKNOWN
1.13 wiz 98: is not to be used as a type.
99: It is used internally to the rnd system.
1.7 lukem 100: .Pp
1.4 explorer 101: .Fa flags
102: are the logical OR of
1.22.2.1! tls 103: .Dv RND_FLAG_COLLECT_VALUE
! 104: (mix data provided by this source into the pool)
! 105: .Dv RND_FLAG_COLLECT_TIME
! 106: (mix timestamps from this source into the pool)
! 107: .Dv RND_FLAG_ESTIMATE_VALUE
! 108: (use a delta estimator to count bits of entropy from this source's data towards
! 109: the pool estimate)
! 110: .Dv RND_FLAG_ESTIMATE_TIME
! 111: (use a delta estimator to count bits of entropy from this source's timestamps
! 112: towards the pool estimate).
! 113: For many devices,
! 114: .Dv RND_FLAG_DEFAULT
! 115: .Dv ( RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME | RND_FLAG_ESTIMATE_TIME )
! 116: is the best choice.
1.13 wiz 117: Note that devices of type
1.4 explorer 118: .Dv RND_TYPE_NET
119: default to
1.22.2.1! tls 120: .Dv RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME
! 121: (no entropy counted).
1.7 lukem 122: .Pp
1.22 pgoyette 123: .It Fn rnd_detach_source "krndsource_t *rnd_source"
1.1 explorer 124: This function disconnects the device from entropy collection.
1.22 pgoyette 125: .It Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum"
1.1 explorer 126: This function adds the value of
127: .Va datum
1.13 wiz 128: to the entropy pool.
129: No entropy is assumed to be collected from this value, it merely helps
130: stir the entropy pool.
131: All entropy is gathered from jitter between the timing of events.
1.7 lukem 132: .Pp
1.1 explorer 133: Note that using a constant for
134: .Va datum
135: does not weaken security, but it does
1.13 wiz 136: not help.
137: Try to use something that can change, such as an interrupt status register
138: which might have a bit set for receive ready or transmit ready, or other
139: device status information.
1.7 lukem 140: .Pp
1.1 explorer 141: To allow the system to gather the timing information accurately, this call
1.13 wiz 142: should be placed within the actual hardware interrupt service routine.
143: Care must be taken to ensure that the interrupt was actually serviced by
144: the interrupt handler, since on some systems interrupts can be shared.
1.7 lukem 145: .Pp
1.1 explorer 146: This function loses nearly all usefulness if it is called from a scheduled
1.13 wiz 147: software interrupt.
148: If that is the only way to add the device as an entropy source, don't.
1.7 lukem 149: .Pp
1.1 explorer 150: If it is desired to mix in the
151: .Va datum
152: and to add in a timestamp, but not to actually estimate entropy from a source
1.8 wiz 153: of randomness, passing
154: .Dv NULL
1.1 explorer 155: for
156: .Va rnd_source
157: is permitted, and the device does not need to be attached.
1.22 pgoyette 158: .It Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
1.8 wiz 159: adds (hopefully) random
160: .Fa data
1.1 explorer 161: to the entropy pool.
162: .Fa len
163: is the number of bytes in
164: .Fa data
165: and
166: .Fa entropy
1.5 mycroft 167: is an "entropy quality" measurement.
1.8 wiz 168: If every bit of
1.1 explorer 169: .Fa data
170: is known to be random,
171: .Fa entropy
172: is the number of bits in
173: .Fa data .
1.7 lukem 174: .Pp
1.1 explorer 175: Timing information is also used to add entropy into the system, using
176: inter-event timings.
1.7 lukem 177: .Pp
1.1 explorer 178: If it is desired to mix in the
179: .Va data
180: and to add in a timestamp, but not to actually estimate entropy from a source
1.8 wiz 181: of randomness, passing
182: .Dv NULL
1.1 explorer 183: for
184: .Va rnd_source
185: is permitted, and the device does not need to be attached.
186: .El
1.19 tls 187: .Sh INTERNAL ENTROPY POOL MANAGEMENT
188: When a hardware event occurs (such as completion of a hard drive
189: transfer or an interrupt from a network device) a timestamp is
190: generated.
191: This timestamp is compared to the previous timestamp
192: recorded for the device, and the first, second, and third order
193: differentials are calculated.
194: .Pp
195: If any of these differentials is zero, no entropy is assumed to
196: have been gathered.
197: If all are non-zero, one bit is assumed.
198: Next, data is mixed into the entropy pool using an LFSR (linear
199: feedback shift register).
200: .Pp
201: To extract data from the entropy pool, a cryptographically strong hash
202: function is used.
203: The output of this hash is mixed back into the pool using the LFSR,
204: and then folded in half before being returned to the caller.
205: .Pp
206: Mixing the actual hash into the pool causes the next extraction to
207: return a different value, even if no timing events were added to the
208: pool.
209: Folding the data in half prevents the caller to derive the
210: actual hash of the pool, preventing some attacks.
211: .Pp
1.20 wiz 212: In the
213: .Nx
214: kernel, values should be extracted from the entropy pool
1.19 tls 215: .Em only
216: via the
217: .Xr cprng 9
1.20 wiz 218: interface.
219: Direct access to the entropy pool is unsupported and may be dangerous.
220: There is no supported API for direct access to the output of the entropy pool.
1.1 explorer 221: .\" .Sh ERRORS
1.10 wiz 222: .Sh FILES
223: These functions are declared in src/sys/sys/rnd.h and defined in
1.21 pgoyette 224: src/sys/kern/kern_rndq.c.
1.10 wiz 225: .Sh SEE ALSO
226: .Xr rnd 4 ,
1.18 tls 227: .Xr rndctl 8 ,
228: .Xr cprng 9
1.1 explorer 229: .Sh HISTORY
1.4 explorer 230: The random device was introduced in
1.1 explorer 231: .Nx 1.3 .
1.9 wiz 232: .Sh AUTHORS
1.22.2.1! tls 233: This implementation was written by
! 234: .An Michael Graff Aq Mt explorer@flame.org
1.1 explorer 235: using ideas and algorithms gathered from many sources, including
236: the driver written by Ted Ts'o.
237: .Sh BUGS
238: The only good sources of randomness are quantum mechanical, and most
239: computers avidly avoid having true sources of randomness included.
240: Don't expect to surpass "pretty good".
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to rnd.9 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / share / man / man9