.\"	$NetBSD: rnd.9,v 1.11 2002/02/13 08:18:50 ross 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" 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 October 20, 1997
.Dt RND 9
.Os
.Sh NAME
.Nm RND ,
.Nm rnd_attach_source ,
.Nm rnd_detach_source ,
.Nm rnd_add_data ,
.Nm rnd_add_uint32
.Nd functions to make a device available for entropy collection
.Sh SYNOPSIS
.Fd #include \*[Lt]sys/rnd.h\*[Gt]
.Ft void
.Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "u_int32_t source_type" "u_int32_t flags"
.Ft void
.Fn rnd_detach_source "rndsource_element_t *rnd_source"
.Ft void
.Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "u_int32_t len" "u_int32_t entropy"
.Ft void
.Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "u_int32_t datum"
.Sh DESCRIPTION
These
.Nm
functions make a device available for entropy collection for
.Pa /dev/random .
.Pp
Ideally the first argument
.Fa rnd_source
of these functions gets included in the devices' entity struct,
but any means to permanently (static) attach one such argument
to one incarnation of the device is ok.  Do not share
.Fa rnd_source
structures between two devices.
.Pp
.Bl -tag -width 8n
.It Fn rnd_attach_source "rndsource_element_t *rnd_source" "char *devname" "u_int32_t source_type" "u_int32_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, and
.Dv RND_TYPE_TTY
for a tty.
.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_FLAGS_NO_COLLECT (don't collect or estimate)
.Dv RND_FLAGS_NO_ESTIMATE (don't estimate)
to control the default setting for collection and estimation.  Note that
devices of type
.Dv RND_TYPE_NET
default to
.Dv RND_FLAGS_NO_ESTIMATE .
.Pp
.It Fn rnd_detach_source "rndsource_element_t *rnd_source"
This function disconnects the device from entropy collection.
.It Fn rnd_add_uint32 "rndsource_element_t *rnd_source" "u_int32_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.
.It Fn rnd_add_data "rndsource_element_t *rnd_source" "void *data" "u_int32_t len" "u_int32_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.
.El
.\" .Sh ERRORS
.Sh FILES
These functions are declared in src/sys/sys/rnd.h and defined in
src/sys/dev/rnd.c.
.Sh SEE ALSO
.Xr rnd 4 ,
.Xr rndctl 8
.Sh HISTORY
The random device was introduced in
.Nx 1.3 .
.Sh AUTHORS
This implementation was written by Michael Graff \*[Lt]explorer@flame.org\*[Gt]
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".