Document entropy device bits.

3 files changed, 238 insertions, 0 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 760899c..277a598 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -54,6 +54,7 @@ MAN=	BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
 	physio.9 posix4.9 printf.9 pseudofs.9 psignal.9 \
 	random.9 resettodr.9 resource_int_value.9 resource_query_string.9 \
 	rtalloc.9 rtentry.9 runqueue.9 \
+	random_harvest.9 rijndael.9 \
 	sbuf.9 scheduler.9 sema.9 sleep.9 sleepqueue.9 spl.9 store.9 \
 	style.9 suser.9 swi.9 sx.9 sysctl_add_oid.9 sysctl_ctx_init.9 \
 	taskqueue.9 time.9 timeout.9 tvtohz.9 \
diff --git a/share/man/man9/random_harvest.9 b/share/man/man9/random_harvest.9
new file mode 100644
index 0000000..eba4245
--- /dev/null
+++ b/share/man/man9/random_harvest.9
@@ -0,0 +1,102 @@
+.\"
+.\" Copyright (c) 2002 Mark R V 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd February 6, 2002
+.Dt RANDOM_HARVEST 9
+.Os FreeBSD
+.Sh NAME
+.Nm random_harvest
+.Nd gather entropy from the kernel for the entropy device
+.Sh SYNOPSIS
+.Fd #include <sys/random.h>
+.Ft void
+.Fn random_harvest "void *entropy" "u_int size" "u_int bits" "u_int frac" "enum esource source"
+.Sh DESCRIPTION
+The
+.Nm
+function is used by device drivers
+and other kernel processes to pass data
+that is considered (at least partially) stochastic
+to the entropy device.
+.Pp
+The caller should pass a pointer (to no more than 16 bytes) of
+the ``random'' data in
+.Ar entropy.
+The argument
+.Ar size
+contains the number of bytes pointed to.
+The caller should
+.Em very conservatively
+estimate the number of random bits
+in the sample,
+and pass this in
+.Ar bits
+or
+.Ar frac .
+If the estimated number of bits per sample is an integer, then
+.Ar bits
+is used, and
+.Ar frac is 0.
+Otherwise,
+for low-entropy samples,
+``fractional'' entropy can be supplied in
+.Ar frac
+(This is considered to be
+.Ar frac /
+1024 bits of entropy).
+The
+.Ar source
+is chosen from
+.Dv RANDOM_WRITE ,
+.Dv RANDOM_KEYBOARD ,
+.Dv RANDOM_MOUSE ,
+.Dv RANDOM_NET
+and
+.Dv RANDOM_INTERRUPT
+and is used to indicate the source of the entropy.
+.Pp
+Interrupt harvesting has been simplified
+for the kernel programmer.
+If a device driver registers an interrupt handler
+with
+.Fn BUS_SETUP_INTR
+or
+.Fn bus_setup_intr ,
+then it is only necessary to
+include the INTR_ENTROPY bit in the
+.Ar flags
+argument to have that interrupt source
+be used for entropy harvesting.
+.Sh SEE ALSO
+.Xr random 4 ,
+.Xr BUS_SETUP_INTR 9
+.Sh AUTHOR
+The
+.Fx
+.Pa /dev/random
+entropy device and supporting documentation was written by
+.An Mark R V Murray .
diff --git a/share/man/man9/rijndael.9 b/share/man/man9/rijndael.9
new file mode 100644
index 0000000..2429ad9
--- /dev/null
+++ b/share/man/man9/rijndael.9
@@ -0,0 +1,135 @@
+.\"
+.\" Copyright (c) 2002
+.\"	Mark R V Murray.  All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``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 DEVELOPERS 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.
+.\"
+.\" $FreeBSD$
+.\" "
+.Dd February 6, 2002
+.Os
+.Dt RIJNDAEL 9
+.Sh NAME
+.Nm rijndael_makeKey ,
+.Nm rijndael_cipherInit ,
+.Nm rijndael_blockEncrypt ,
+.Nm rijndael_padEncrypt ,
+.Nm rijndael_blockDecrypt ,
+.Nm rijndael_padDecrypt
+.Nd AES encryption.
+.Sh SYNOPSIS
+.Fd #include <crypto/rijndael/rijndael.h>
+.Ft int
+.Fo rijndael_makeKey
+.Fa "keyInstance *key"
+.Fa "u_int8_t direction"
+.Fa "int keyLen"
+.Fa "char *keyMaterial"
+.Fc
+.Ft int
+.Fo rijndael_cipherInit
+.Fa "cipherInstance *cipher"
+.Fa "u_int8_t mode"
+.Fa "char *IV"
+.Fc
+.Ft int
+.Fo rijndael_blockEncrypt
+.Fa "cipherInstance *cipher"
+.Fa "keyInstance *key"
+.Fa "u_int8_t *input"
+.Fa "int inputLen"
+.Fa "u_int8_t *outBuffer"
+.Fc
+.Ft int
+.Fo rijndael_padEncrypt
+.Fa "cipherInstance *cipher"
+.Fa "keyInstance *key"
+.Fa "u_int8_t *input"
+.Fa "int inputOctets"
+.Fa "u_int8_t *outBuffer"
+.Fc
+.Ft int
+.Fo rijndael_blockDecrypt
+.Fa "cipherInstance *cipher"
+.Fa "keyInstance *key"
+.Fa "u_int8_t *input"
+.Fa "int inputLen"
+.Fa "u_int8_t *outBuffer"
+.Fc
+.Ft int
+.Fo rijndael_padDecrypt
+.Fa "cipherInstance *cipher"
+.Fa "keyInstance *key"
+.Fa "u_int8_t *input"
+.Fa "int inputOctets"
+.Fa "u_int8_t *outBuffer"
+.Fc
+.Sh DESCRIPTION
+The
+.Nm rijndael_makeKey
+function is used to set up the key schedule in
+.Ar key .
+The
+.Ar direction
+(which may be
+.Dv DIR_ENCRYPT
+or
+.Dv DIR_DECRYPT )
+specifies the intended use of the key.
+The length of the key (in bits) is given in
+.Ar keyLen ,
+and must be 128, 192 or 256.
+The actual key is supplied in the buffer pointed to by
+.Ar keyMaterial .
+This material may be raw binary data,
+or an ascii string containing a hexadecimal rendition
+of the raw binary data,
+dependant on a compile-time option in the
+.Nm
+sources -
+.Dv BINARY_KEY_MATERIAL .
+.Pp
+.Sh RETURN VALUES
+The
+.Nm rijndael_makeKey
+function will return
+.Dv BAD_KEY_INSTANCE
+if a null
+.Ar key
+is passed,
+.Dv BAD_KEY_DIR
+if
+.Ar direction
+is not
+.Dv DIR_ENCRYPT
+or
+.Dv DIR_DECRYPT ,
+.Dv BAD_KEY_MAT
+if the key materials are not a hexadecimal string
+(and binary keys are not set),
+and
+.Dv TRUE
+otherwise.
+.Pp
+.Sh AUTHOR
+.An Mark R V Murray .