share/man/man9/rnd.9

   1 .\"     $NetBSD: rnd.9,v 1.16 2008/04/30 13:10:58 martin Exp $
   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 .\"
  30 .Dd September 16, 2008
  31 .Dt RND 9
  32 .Os
  33 .Sh NAME
  34 .Nm RND ,
  35 .Nm rnd_attach_source ,
  36 .Nm rnd_detach_source ,
  37 .Nm rnd_add_data ,
  38 .Nm rnd_add_uint32
  39 .Nd functions to make a device available for entropy collection
  40 .Sh SYNOPSIS
  41 .In sys/rnd.h
  42 .Ft void
  43 .Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
  44 .Ft void
  45 .Fn rnd_detach_source "rndsource_element_t *rnd_source"
  46 .Ft void
  47 .Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
  48 .Ft void
  49 .Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "uint32_t datum"
  50 .Sh DESCRIPTION
  51 These
  52 .Nm
  53 functions make a device available for entropy collection for
  54 .Pa /dev/random .
  55 .Pp
  56 Ideally the first argument
  57 .Fa rnd_source
  58 of these functions gets included in the devices' entity struct,
  59 but any means to permanently (static) attach one such argument
  60 to one incarnation of the device is ok.
  61 Do not share
  62 .Fa rnd_source
  63 structures between two devices.
  64 .Pp
  65 .Bl -tag -width 8n
  66 .It Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
  67 This function announces the availability of a device for entropy collection.
  68 It must be called before the source struct pointed to by
  69 .Fa rnd_source
  70 is used in any of the following functions.
  71 .Pp
  72 .Fa devname
  73 is the name of the device.
  74 It is used to print a message (if the kernel is compiled with
  75 ``options RND_VERBOSE'') and also for status information printed with
  76 .Xr rndctl 8 .
  77 .Pp
  78 .Fa source_type
  79 is
  80 .Dv RND_TYPE_NET
  81 for network devices,
  82 .Dv RND_TYPE_DISK
  83 for physical disks,
  84 .Dv RND_TYPE_TAPE
  85 for a tape drive,
  86 .Dv RND_TYPE_TTY
  87 for a tty, and
  88 .Dv RND_TYPE_RNG
  89 for a random number generator.
  90 .Dv RND_TYPE_UNKNOWN
  91 is not to be used as a type.
  92 It is used internally to the rnd system.
  93 .Pp
  94 .Fa flags
  95 are the logical OR of
  96 .Dv RND_FLAG_NO_COLLECT
  97 (don't collect or estimate)
  98 .Dv RND_FLAG_NO_ESTIMATE
  99 (don't estimate)
 100 to control the default setting for collection and estimation.
 101 Note that devices of type
 102 .Dv RND_TYPE_NET
 103 default to
 104 .Dv RND_FLAG_NO_ESTIMATE .
 105 .Pp
 106 .It Fn rnd_detach_source "rndsource_element_t *rnd_source"
 107 This function disconnects the device from entropy collection.
 108 .It Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "uint32_t datum"
 109 This function adds the value of
 110 .Va datum
 111 to the entropy pool.
 112 No entropy is assumed to be collected from this value, it merely helps
 113 stir the entropy pool.
 114 All entropy is gathered from jitter between the timing of events.
 115 .Pp
 116 Note that using a constant for
 117 .Va datum
 118 does not weaken security, but it does
 119 not help.
 120 Try to use something that can change, such as an interrupt status register
 121 which might have a bit set for receive ready or transmit ready, or other
 122 device status information.
 123 .Pp
 124 To allow the system to gather the timing information accurately, this call
 125 should be placed within the actual hardware interrupt service routine.
 126 Care must be taken to ensure that the interrupt was actually serviced by
 127 the interrupt handler, since on some systems interrupts can be shared.
 128 .Pp
 129 This function loses nearly all usefulness if it is called from a scheduled
 130 software interrupt.
 131 If that is the only way to add the device as an entropy source, don't.
 132 .Pp
 133 If it is desired to mix in the
 134 .Va datum
 135 and to add in a timestamp, but not to actually estimate entropy from a source
 136 of randomness, passing
 137 .Dv NULL
 138 for
 139 .Va rnd_source
 140 is permitted, and the device does not need to be attached.
 141 .It Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
 142 adds (hopefully) random
 143 .Fa data
 144 to the entropy pool.
 145 .Fa len
 146 is the number of bytes in
 147 .Fa data
 148 and
 149 .Fa entropy
 150 is an "entropy quality" measurement.
 151 If every bit of
 152 .Fa data
 153 is known to be random,
 154 .Fa entropy
 155 is the number of bits in
 156 .Fa data .
 157 .Pp
 158 Timing information is also used to add entropy into the system, using
 159 inter-event timings.
 160 .Pp
 161 If it is desired to mix in the
 162 .Va data
 163 and to add in a timestamp, but not to actually estimate entropy from a source
 164 of randomness, passing
 165 .Dv NULL
 166 for
 167 .Va rnd_source
 168 is permitted, and the device does not need to be attached.
 169 .El
 170 .\" .Sh ERRORS
 171 .Sh FILES
 172 These functions are declared in src/sys/sys/rnd.h and defined in
 173 src/sys/dev/rnd.c.
 174 .Sh SEE ALSO
 175 .Xr rnd 4 ,
 176 .Xr rndctl 8
 177 .Sh HISTORY
 178 The random device was introduced in
 179 .Nx 1.3 .
 180 .Sh AUTHORS
 181 This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt]
 182 using ideas and algorithms gathered from many sources, including
 183 the driver written by Ted Ts'o.
 184 .Sh BUGS
 185 The only good sources of randomness are quantum mechanical, and most
 186 computers avidly avoid having true sources of randomness included.
 187 Don't expect to surpass "pretty good".