.\"	$NetBSD: rnd.9,v 1.25.18.1 2020/07/15 13:47:40 martin Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This documentation is derived from text contributed to The NetBSD
.\" Foundation by S.P.Zeidler (aka stargazer).
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 10, 2014
.Dt RND 9
.Os
.Sh NAME
.Nm RND ,
.Nm rnd_attach_source ,
.Nm rnd_detach_source ,
.Nm rnd_add_data ,
.Nm rnd_add_data_sync ,
.Nm rnd_add_uint32
.Nd functions to make a device available for entropy collection
.Sh SYNOPSIS
.In sys/rndsource.h
.Ft void
.Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie"
.Ft void
.Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
.Ft void
.Fn rnd_detach_source "krndsource_t *rnd_source"
.Ft void
.Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
.Ft void
.Fn rnd_add_data_sync "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
.Ft void
.Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum"
.Sh DESCRIPTION
These
.Nm
functions make a device available for entropy collection for
the kernel entropy pool, which provides key material for the
.Xr cprng 9
and
.Xr rnd 4
.Pa ( /dev/random )
interfaces.
.Pp
The caller must zero an
.Fa rnd_source
object before using it.
Ideally the first argument
.Fa rnd_source
of these functions gets included in the devices' entity struct,
but any means to permanently (statically) attach one such argument
to one incarnation of the device is ok.
Do not share
.Fa rnd_source
structures between two devices, and make sure to serialize all access
to each
.Fa rnd_source ,
for example with
.Xr mutex 9 .
.Bl -tag -width 8n
.It Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie"
This function sets a callback to be invoked when the kernel entropy
pool is hungry.
It is optional; if used, it must be used
.Em before
.Fn rnd_attach_source ,
and the caller must pass
.Dv RND_FLAG_HASCB
to
.Fn rnd_attach_source
in order for the callback to be used.
The callback is invoked as
.Fa callback ( Fa nbytes , Fa cookie ) ,
where
.Fa nbytes
is the number of bytes requested for the entropy pool, and
.Fa cookie
is the cookie that was passed to
.Fn rndsource_setcb .
The callback normally does one of two things:
.Bl -dash
.It
Sends a request to a hardware device for entropy and returns.
The hardware will later return data asynchronously by an interrupt, and
the callback will use
.Fn rnd_add_data
or
.Fn rnd_add_uint32
to add the data to the pool.
.It
Synchronously gathers entropy from hardware \(em for example, by a CPU
instruction like Intel RDSEED.
In this case, in order to add data to the pool
.Em before
returning, the callback
.Em must
use
.Fn rnd_add_data_sync ,
not
.Fn rnd_add_data
or
.Fn rnd_add_uint32 .
.El
.It Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags"
This function announces the availability of a device for entropy collection.
It must be called before the source struct pointed to by
.Fa rnd_source
is used in any of the following functions.
.Pp
.Fa devname
is the name of the device.
It is used to print a message (if the kernel is compiled with
``options RND_VERBOSE'') and also for status information printed with
.Xr rndctl 8 .
.Pp
.Fa source_type
is
.Dv RND_TYPE_NET
for network devices,
.Dv RND_TYPE_DISK
for physical disks,
.Dv RND_TYPE_TAPE
for a tape drive,
.Dv RND_TYPE_TTY
for a tty,
.Dv RND_TYPE_RNG
for a random number generator, and
.Dv RND_TYPE_ENV
for an environment sensor.
.Dv RND_TYPE_UNKNOWN
is not to be used as a type.
It is used internally to the rnd system.
.Pp
.Fa flags
are the logical OR of
.Dv RND_FLAG_COLLECT_VALUE
(mix data provided by this source into the pool)
.Dv RND_FLAG_COLLECT_TIME
(mix timestamps from this source into the pool)
.Dv RND_FLAG_ESTIMATE_VALUE
(use a delta estimator to count bits of entropy from this source's data towards
the pool estimate)
.Dv RND_FLAG_ESTIMATE_TIME
(use a delta estimator to count bits of entropy from this source's timestamps
towards the pool estimate)
.Dv RND_FLAG_HASCB
(caller specified a callback with
.Fn rndsource_setcb ) .
For many devices,
.Dv RND_FLAG_DEFAULT
.Dv ( RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME | RND_FLAG_ESTIMATE_TIME )
is the best choice.
Note that devices of type
.Dv RND_TYPE_NET
default to
.Dv RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME
(no entropy counted).
.It Fn rnd_detach_source "krndsource_t *rnd_source"
This function disconnects the device from entropy collection.
.It Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum"
This function adds the value of
.Va datum
to the entropy pool.
No entropy is assumed to be collected from this value, it merely helps
stir the entropy pool.
All entropy is gathered from jitter between the timing of events.
.Pp
Note that using a constant for
.Va datum
does not weaken security, but it does
not help.
Try to use something that can change, such as an interrupt status register
which might have a bit set for receive ready or transmit ready, or other
device status information.
.Pp
To allow the system to gather the timing information accurately, this call
should be placed within the actual hardware interrupt service routine.
Care must be taken to ensure that the interrupt was actually serviced by
the interrupt handler, since on some systems interrupts can be shared.
.Pp
This function loses nearly all usefulness if it is called from a scheduled
software interrupt.
If that is the only way to add the device as an entropy source, don't.
.Pp
If it is desired to mix in the
.Va datum
and to add in a timestamp, but not to actually estimate entropy from a source
of randomness, passing
.Dv NULL
for
.Va rnd_source
is permitted, and the device does not need to be attached.
.Pp
.Fn rnd_add_uint32
.Em must not
be used during a callback as set with
.Fn rndsource_setcb ;
use
.Fn rnd_add_data_sync
instead.
.It Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy"
adds (hopefully) random
.Fa data
to the entropy pool.
.Fa len
is the number of bytes in
.Fa data
and
.Fa entropy
is an "entropy quality" measurement.
If every bit of
.Fa data
is known to be random,
.Fa entropy
is the number of bits in
.Fa data .
.Pp
Timing information is also used to add entropy into the system, using
inter-event timings.
.Pp
If it is desired to mix in the
.Va data
and to add in a timestamp, but not to actually estimate entropy from a source
of randomness, passing
.Dv NULL
for
.Va rnd_source
is permitted, and the device does not need to be attached.
.Pp
.Fn rnd_add_data
.Em must not
be used during a callback as set with
.Fn rndsource_setcb ;
use
.Fn rnd_add_data_sync
instead.
.El
.Sh INTERNAL ENTROPY POOL MANAGEMENT
When a hardware event occurs (such as completion of a hard drive
transfer or an interrupt from a network device) a timestamp is
generated.
This timestamp is compared to the previous timestamp
recorded for the device, and the first, second, and third order
differentials are calculated.
.Pp
If any of these differentials is zero, no entropy is assumed to
have been gathered.
If all are non-zero, one bit is assumed.
Next, data is mixed into the entropy pool using an LFSR (linear
feedback shift register).
.Pp
To extract data from the entropy pool, a cryptographically strong hash
function is used.
The output of this hash is mixed back into the pool using the LFSR,
and then folded in half before being returned to the caller.
.Pp
Mixing the actual hash into the pool causes the next extraction to
return a different value, even if no timing events were added to the
pool.
Folding the data in half prevents the caller to derive the
actual hash of the pool, preventing some attacks.
.Pp
In the
.Nx
kernel, values should be extracted from the entropy pool
.Em only
via the
.Xr cprng 9
interface.
Direct access to the entropy pool is unsupported and may be dangerous.
There is no supported API for direct access to the output of the entropy pool.
.\" .Sh ERRORS
.Sh FILES
These functions are declared in src/sys/sys/rndsource.h and defined in
src/sys/kern/kern_rndq.c.
.Sh SEE ALSO
.Xr rnd 4 ,
.Xr rndctl 8 ,
.Xr cprng 9
.Sh HISTORY
The random device was introduced in
.Nx 1.3 .
.Sh AUTHORS
This implementation was written by
.An Michael Graff Aq Mt explorer@flame.org
using ideas and algorithms gathered from many sources, including
the driver written by Ted Ts'o.
.Sh BUGS
The only good sources of randomness are quantum mechanical, and most
computers avidly avoid having true sources of randomness included.
Don't expect to surpass "pretty good".