share/man/man9/random_harvest.9

   1 .\"
   2 .\" Copyright (c) 2002-2015 Mark R V Murray
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  19 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  20 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  21 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  22 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd July 13, 2015
  29 .Dt RANDOM_HARVEST 9
  30 .Os
  31 .Sh NAME
  32 .Nm random_harvest
  33 .Nd gather entropy from the kernel for the entropy device
  34 .Sh SYNOPSIS
  35 .In sys/types.h
  36 .In sys/random.h
  37 .Ft void
  38 .Fo random_harvest_direct
  39 .Fa "void *entropy"
  40 .Fa "u_int size"
  41 .Fa "u_int bits"
  42 .Fa "enum esource source"
  43 .Fc
  44 .Ft void
  45 .Fo random_harvest_fast
  46 .Fa "void *entropy"
  47 .Fa "u_int size"
  48 .Fa "u_int bits"
  49 .Fa "enum esource source"
  50 .Fc
  51 .Ft void
  52 .Fo random_harvest_queue
  53 .Fa "void *entropy"
  54 .Fa "u_int size"
  55 .Fa "u_int bits"
  56 .Fa "enum esource source"
  57 .Fc
  58 .Sh DESCRIPTION
  59 The
  60 .Fn random_harvest_*
  61 functions are used by device drivers
  62 and other kernel processes to pass data
  63 that is considered (at least partially) stochastic
  64 to the entropy device.
  65 .Pp
  66 The caller should pass
  67 a pointer pointing to the
  68 .Dq random
  69 data in
  70 .Fa entropy .
  71 The argument
  72 .Fa size
  73 contains the number of bytes pointed to.
  74 The
  75 .Fa source
  76 is chosen from one of
  77 the values enumerated in
  78 .Pa sys/dev/random.h .
  79 and is used to indicate the source of the entropy.
  80 .Pp
  81 The
  82 .Fo random_harvest_direct
  83 .Fc
  84 variant is used
  85 for early harvesting
  86 before any multitasking
  87 is enabled.
  88 .Pp
  89 The
  90 .Fn random_harvest_fast
  91 variant is used
  92 by sources that
  93 should not take
  94 a performance hit
  95 from harvesting,
  96 as they are high-rate
  97 sources.
  98 Some entropy is sacrificed,
  99 but the high rate of supply
 100 will compensate for this.
 101 .Pp
 102 The
 103 .Fn random_harvest_queue
 104 variant is used
 105 for general harvesting
 106 and is the default
 107 choice for most entropy sources
 108 such as interrupts
 109 or console events.
 110 .Pp
 111 The
 112 .Fa bits
 113 argument is only used
 114 by the deprecated Yarrow algorithm.
 115 For compatibility,
 116 the caller should
 117 .Em "very conservatively"
 118 estimate the number of random bits
 119 in the sample,
 120 and pass this in
 121 .Fa bits .
 122 .Pp
 123 Interrupt harvesting has been
 124 in part simplified
 125 for the kernel programmer.
 126 If a device driver registers an interrupt handler
 127 with
 128 .Xr BUS_SETUP_INTR 9
 129 or
 130 .Xr bus_setup_intr 9 ,
 131 then it is only necessary to
 132 include the
 133 .Dv INTR_ENTROPY
 134 bit in the
 135 .Fa flags
 136 argument to have that interrupt source
 137 be used for entropy harvesting.
 138 This should be done wherever practicable.
 139 .Sh SEE ALSO
 140 .Xr random 4 ,
 141 .Xr BUS_SETUP_INTR 9
 142 .Sh AUTHORS
 143 The
 144 .Fx
 145 .Xr random 4
 146 entropy device and supporting documentation was written by
 147 .An Mark R V Murray .