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 August 26, 2018
  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 "enum esource source"
  42 .Fc
  43 .Ft void
  44 .Fo random_harvest_fast
  45 .Fa "void *entropy"
  46 .Fa "u_int size"
  47 .Fa "enum esource source"
  48 .Fc
  49 .Ft void
  50 .Fo random_harvest_queue
  51 .Fa "void *entropy"
  52 .Fa "u_int size"
  53 .Fa "enum esource source"
  54 .Fc
  55 .Sh DESCRIPTION
  56 The
  57 .Fn random_harvest_*
  58 functions are used by device drivers
  59 and other kernel processes to pass data
  60 that is considered (at least partially) stochastic
  61 to the entropy device.
  62 .Pp
  63 The caller should pass
  64 a pointer pointing to the
  65 .Dq random
  66 data in
  67 .Fa entropy .
  68 The argument
  69 .Fa size
  70 contains the number of bytes pointed to.
  71 The
  72 .Fa source
  73 is chosen from one of
  74 the values enumerated in
  75 .Pa sys/dev/random.h .
  76 and is used to indicate the source of the entropy.
  77 .Pp
  78 The
  79 .Fo random_harvest_direct
  80 .Fc
  81 variant is used
  82 for early harvesting
  83 before any multitasking
  84 is enabled.
  85 .Pp
  86 The
  87 .Fn random_harvest_fast
  88 variant is used
  89 by sources that
  90 should not take
  91 a performance hit
  92 from harvesting,
  93 as they are high-rate
  94 sources.
  95 Some entropy is sacrificed,
  96 but the high rate of supply
  97 will compensate for this.
  98 .Pp
  99 The
 100 .Fn random_harvest_queue
 101 variant is used
 102 for general harvesting
 103 and is the default
 104 choice for most entropy sources
 105 such as interrupts
 106 or console events.
 107 .Pp
 108 Interrupt harvesting has been
 109 in part simplified
 110 for the kernel programmer.
 111 If a device driver registers an interrupt handler
 112 with
 113 .Xr BUS_SETUP_INTR 9
 114 or
 115 .Xr bus_setup_intr 9 ,
 116 then it is only necessary to
 117 include the
 118 .Dv INTR_ENTROPY
 119 bit in the
 120 .Fa flags
 121 argument to have that interrupt source
 122 be used for entropy harvesting.
 123 This should be done wherever practicable.
 124 .Sh SEE ALSO
 125 .Xr random 4 ,
 126 .Xr BUS_SETUP_INTR 9
 127 .Sh AUTHORS
 128 The
 129 .Fx
 130 .Xr random 4
 131 entropy device and supporting documentation was written by
 132 .An Mark R V Murray .