Control utility for the /dev/random device. This allows root to select

which interrupts are to be used in randomess gathering. Man page for
the random device is included.

4 files changed, 389 insertions, 0 deletions

diff --git a/usr.sbin/rndcontrol/Makefile b/usr.sbin/rndcontrol/Makefile
new file mode 100644
index 0000000..e6418eb
--- /dev/null
+++ b/usr.sbin/rndcontrol/Makefile
@@ -0,0 +1,8 @@
+#	$id$
+
+PROG=		rndcontrol
+CFLAGS+=	-Wall
+MAN4=		random.4
+MAN8=		rndcontrol.8
+
+.include <bsd.prog.mk>
diff --git a/usr.sbin/rndcontrol/random.4 b/usr.sbin/rndcontrol/random.4
new file mode 100644
index 0000000..1f823fa
--- /dev/null
+++ b/usr.sbin/rndcontrol/random.4
@@ -0,0 +1,178 @@
+.\"
+.\" random.c -- A strong random number generator
+.\"
+.\" Version 0.92, last modified 21-Sep-95
+.\" 
+.\" Copyright Theodore Ts'o, 1994, 1995.  All rights reserved.
+.\"
+.\" 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, and the entire permission notice in its entirety,
+.\"    including the disclaimer of warranties.
+.\" 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. The name of the author may not be used to endorse or promote
+.\"    products derived from this software without specific prior
+.\"    written permission.
+.\" 
+.\" ALTERNATIVELY, this product may be distributed under the terms of
+.\" the GNU Public License, in which case the provisions of the GPL are
+.\" required INSTEAD OF the above restrictions.  (This clause is
+.\" necessary due to a potential bad interaction between the GPL and
+.\" the restrictions contained in a BSD-style copyright.)
+.\" 
+.\" THIS SOFTWARE IS PROVIDED ``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 AUTHOR 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.
+.\"
+.\" $Id$
+.\"
+.Dd October 21, 1995
+.Dt RANDOM 4 i386
+.Os
+.Sh NAME
+.Nm random ,
+.Nm urandom
+.Nd random number devices
+.Sh DESCRIPTION
+This device gathers environmental noise from device drivers, etc.,
+and returns good random numbers, suitable for cryptographic use.
+Besides the obvious cryptographic uses, these numbers are also good
+for seeding TCP sequence numbers, and other places where it is
+desireable to have numbers which are not only random, but hard to
+predict by an attacker.
+.Ss Theory of operation
+Computers are very predictable devices.  Hence it is extremely hard
+to produce truly random numbers on a computer \(em as opposed to
+pseudo-random numbers, which can easily generated by using a
+algorithm.  Unfortunately, it is very easy for attackers to guess
+the sequence of pseudo-random number generators, and for some
+applications this is not acceptable.  So instead, we must try to
+gather "environmental noise" from the computer's environment, which
+must be hard for outside attackers to observe, and use that to
+generate random numbers.  In a Unix environment, this is best done
+from inside the kernel.
+.Pp
+Sources of randomness from the environment include inter-keyboard
+timings, inter-interrupt timings from some interrupts, and other
+events which are both (a) non-deterministic and (b) hard for an
+outside observer to measure.  Randomness from these sources are
+added to an "entropy pool", which is periodically mixed using the
+MD5 compression function in CBC mode.  As random bytes are mixed
+into the entropy pool, the routines keep an
+.Em estimate
+of how many bits of randomness have been stored into the random number
+generator's internal state.
+.Pp
+When random bytes are desired, they are obtained by taking the MD5
+hash of a counter plus the contents of the "entropy pool".  The
+reason for the MD5 hash is so that we can avoid exposing the
+internal state of random number generator.  Although the MD5 hash
+does protect the pool, as each random byte which is generated from
+the pool reveals some information which was derived from the
+internal state, and thus increasing the amount of information an
+outside attacker has available to try to make some guesses about
+the random number generator's internal state.  For this reason,
+the routine decreases its internal estimate of how many bits of
+"true randomness" are contained in the entropy pool as it outputs
+random numbers.
+.Pp
+If this estimate goes to zero, the routine can still generate random
+numbers; however it may now be possible for an attacker to analyze
+the output of the random number generator, and the MD5 algorithm,
+and thus have some success in guessing the output of the routine.
+Phil Karn (who devised this mechanism of using MD5 plus a counter
+to extract random numbers from an entropy pool) calls this
+"practical randomness", since in the worse case this is equivalent
+to hashing MD5 with a counter and an undisclosed secret.  If MD5 is
+a strong cryptographic hash, this should be fairly resistant to attack.
+.Ss Exported interfaces \(em output
+There are three exported interfaces; the first is one designed to
+be used from within the kernel:
+.Pp
+.Bl -tag -width Pa -compact
+.It Pa void get_random_bytes(void *buf, int nbytes);
+.El
+.Pp
+This interface will return the requested number of random bytes,
+and place it in the requested buffer.
+.Pp
+The two other interfaces are two character devices
+.Nm /dev/random
+and
+.Nm /dev/urandom . /dev/random
+is suitable for use when very high quality randomness is desired
+(for example, for key generation.), as it will only return a maximum
+of the number of bits of randomness (as estimated by the random number
+generator) contained in the entropy pool.
+.Pp
+The
+.Nm /dev/urandom
+device does not have this limit, and will return as many bytes as are
+requested.  As more and more random bytes are requested without giving
+time for the entropy pool to recharge, this will result in lower quality
+random numbers.  For many applications, however, this is acceptable.
+.Ss Exported interfaces \(em input
+The two current exported interfaces for gathering environmental
+noise from the devices are:
+.Pp
+.Bl -tag -width Pa -compact
+.It Pa void add_keyboard_randomness(unsigned char scancode);
+.It Pa void add_interrupt_randomness(int irq);
+.El
+.Pp
+The first function uses the inter-keypress timing, as well as the
+scancode as random inputs into the "entropy pool".
+.Pp
+The second function uses the inter-interrupt timing as random
+inputs to the entropy pool.  Note that not all interrupts are good
+sources of randomness!  For example, the timer interrupts is not a
+good choice, because the periodicity of the interrupts is to
+regular, and hence predictable to an attacker.  Disk interrupts are
+a better measure, since the timing of the disk interrupts are more
+unpredictable.  The routines try to estimate how many bits of
+randomness a particular interrupt channel offers, by keeping track
+of the first and second order deltas in the interrupt timings.
+.Sh ACKNOWLEDGEMENTS
+The original core code was written by Theodore Ts'o, and was intended
+for the Linux platform. This was ported to FreeBSD by Mark Murray,
+who also wrote the rndcontrol utility.
+.Pp
+Ideas for constructing this random number generator were derived
+from the Pretty Good Privacy's random number generator, and from
+private discussions with Phil Karn.  This design has been further
+modified by myself, so any flaws are solely my responsibility, and
+should not be attributed to the authors of PGP or to Phil.
+.Pp
+The code for MD5 transform was taken from Colin Plumb's
+implementation, which has been placed in the public domain.  The
+MD5 cryptographic checksum was devised by Ronald Rivest, and is
+documented in RFC 1321, "The MD5 Message Digest Algorithm".
+.Pp
+Further background information on this topic may be obtained from
+RFC 1750, "Randomness Recommendations for Security", by Donald
+Eastlake, Steve Crocker, and Jeff Schiller.
+.Sh "SEE ALSO"
+.Xr rndcontrol 8
+.Sh FILES
+.Bl -tag -width Pa -compact
+.It Pa /dev/random
+.It Pa /dev/urandom
+.El
+.Sh HISTORY
+The
+.Nm random ,
+.Nm urandom
+files appeared in
+FreeBSD v2.2 .
diff --git a/usr.sbin/rndcontrol/rndcontrol.8 b/usr.sbin/rndcontrol/rndcontrol.8
new file mode 100644
index 0000000..f653cde
--- /dev/null
+++ b/usr.sbin/rndcontrol/rndcontrol.8
@@ -0,0 +1,89 @@
+.\"
+.\" Copyright (c) 1995
+.\"	Mark Murray.  All rights reserved.
+.\"
+.\" 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 Mark Murray
+.\"	and Theodore Ts'o
+.\" 4. Neither the name of the author nor the names of any co-contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY MARK MURRAY 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 MARK MURRAY 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.
+.\"
+.\" $Id$
+.\"
+.Dd October 20, 1995
+.Dt RNDCONTROL 8
+.Os FreeBSD 2
+.Sh NAME
+.Nm \&rndcontrol 
+.Nd a utility for manipulating the /dev/random device.
+.Sh SYNOPSIS
+.Nm \&rndcontrol
+.Op Fl q
+.Op Fl s Ar irq_no
+.Op Fl c Ar irq_no
+.Sh DESCRIPTION
+The
+.Nm rndcontrol
+command is used to set which interrupts are used to help randomise
+the ``pool of entropy'' maintained by the kernel. The 
+.Em 0 /dev/random
+and
+.Em 0 /dev/urandom
+devices are the user interface to this source of randomness.
+Any changes take effect immediately.
+.Sh OPTIONS
+.TP
+The following command line options are supported:
+.Bl -tag -width indent 
+.It Fl q
+Turns off all output except errors.
+.It Fl s  Ar n
+Allows IRQ
+.Em n
+to be$ used as a source of randomness. This option may be repeated for
+more than one IRQ.
+.It Fl c  Ar n
+Stops IRQ
+.Em n
+from being used as a source of randomness. This option may be repeated for
+more than one IRQ.
+.Pp
+The default is to have no IRQ's being used.
+.Pp
+.Sh FILES
+.Bl -tag -width indent -compact
+.It Pa /dev/random  - Secure random device
+.It Pa /dev/urandom - Random device
+.El
+.Sh BUGS
+Sure to be some.
+.Sh "SEE ALSO"
+.Xr random 4 
+.Sh AUTHOR
+Theodore Ts'o wrote the core code. Mark Murray ported this code to
+FreeBSD and wrote the support routines and constructed the man pages.
+.Sh HISTORY
+.Nm rndcontrol
+first appeared in FreeBSD 2.2
diff --git a/usr.sbin/rndcontrol/rndcontrol.c b/usr.sbin/rndcontrol/rndcontrol.c
new file mode 100644
index 0000000..8f9dfa8
--- /dev/null
+++ b/usr.sbin/rndcontrol/rndcontrol.c
@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) 1995
+ *	Mark Murray.  All rights reserved.
+ *
+ * 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 Mark Murray
+ *	and Theodore Ts'o
+ * 4. Neither the name of the author nor the names of any co-contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY MARK MURRAY 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 MARK MURRAY 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.
+ *
+ */
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <fcntl.h>
+#include <sys/errno.h>
+#include <machine/random.h>
+
+void usage(char *myname)
+{
+	fprintf(stderr, "usage: %s [ [-q | -v] [-s N | -c M]... ]\n", myname);
+}
+
+int
+main(int argc, char *argv[])
+{
+	int verbose, ch, fd, result, i;
+	u_int16_t irq;
+
+	verbose = 1;
+
+	fd = open("/dev/random", O_RDONLY, 0);
+	if (fd == -1) {
+		perror(argv[0]);
+		return (1);
+	}
+	else {
+		while ((ch = getopt(argc, argv, "qs:c:")) != EOF)
+			switch (ch) {
+			case 'q':
+				verbose = 0;
+				break;
+			case 's':
+				irq = (u_int16_t)atoi(optarg);
+				if (verbose)
+					printf("%s: setting irq %d\n", argv[0], irq);
+				result = ioctl(fd, MEM_SETIRQ, (char *)&irq);
+				if (result == -1) {
+					perror(argv[0]);
+					return (1);
+				}
+				break;
+			case 'c':
+				irq = (u_int16_t)atoi(optarg);
+				if (verbose)
+					printf("%s: clearing irq %d\n", argv[0], irq);
+				result = ioctl(fd, MEM_CLEARIRQ, (char *)&irq);
+				if (result == -1) {
+					perror(argv[0]);
+					return (1);
+				}
+				break;
+			case '?':
+			default:
+				usage(argv[0]);
+				return (1);
+			}
+		}
+		if (verbose) {
+			result = ioctl(fd, MEM_RETURNIRQ, (char *)&irq);
+			if (result == -1) {
+				perror(argv[0]);
+				return (1);
+			}
+			printf("%s: Interrupts in use:", argv[0]);
+			for (i = 0; i < 16; i++)
+				if (irq & (1 << i))
+					printf(" %d", i);
+			printf("\n");
+		}
+		argc -= optind;
+		argv += optind;
+
+		if (argc) {
+			fprintf(stderr, "%s: Unknown argument(s):", argv[-optind]);
+			for (i = 0; i < argc; i++)
+				fprintf(stderr, " %s", argv[i]);
+			fprintf(stderr, "\n");
+		}
+
+	return 0;
+}