193 lines
6.6 KiB
Groff
193 lines
6.6 KiB
Groff
.\" $NetBSD: rnd.9,v 1.14 2003/04/16 13:35:33 wiz 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
|
|
.In sys/rnd.h
|
|
.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_FLAG_NO_COLLECT
|
|
(don't collect or estimate)
|
|
.Dv RND_FLAG_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_FLAG_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".
|