September 16, 2008 RND 9

### NAME

RND, rnd_attach_source, rnd_detach_source, rnd_add_data, rnd_add_uint32 - functions to make a device available for entropy collection

### SYNOPSIS

```void` rnd_attach_source(```rndsource_element_t *rnd_source``, char *devname``, uint32_t source_type``, uint32_t flags`)
```void` rnd_detach_source(```rndsource_element_t *rnd_source`)
```void` rnd_add_data(```rndsource_element_t *rnd_source``, void *data``, uint32_t len``, uint32_t entropy`)
```void` rnd_add_uint32(```rndsource_element_t *rnd_source``, uint32_t datum`)

### DESCRIPTION

These RND functions make a device available for entropy collection for ```/dev/random`.

Ideally the first argument ```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 ```rnd_source` structures between two devices.

rnd_attach_source(```rndsource_element_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 ```rnd_source` is used in any of the following functions.

  ```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 rndctl(8).

  ```source_type` is ```RND_TYPE_NET` for network devices, ```RND_TYPE_DISK` for physical disks, ```RND_TYPE_TAPE` for a tape drive, ```RND_TYPE_TTY` for a tty, and ```RND_TYPE_RNG` for a random number generator. ```RND_TYPE_UNKNOWN` is not to be used as a type. It is used internally to the rnd system.

  ```flags` are the logical OR of ```RND_FLAG_NO_COLLECT` (don't collect or estimate) ```RND_FLAG_NO_ESTIMATE` (don't estimate) to control the default setting for collection and estimation. Note that devices of type ```RND_TYPE_NET` default to ```RND_FLAG_NO_ESTIMATE`.

rnd_detach_source(```rndsource_element_t *rnd_source`)
  This function disconnects the device from entropy collection.

rnd_add_uint32(```rndsource_element_t *rnd_source``, uint32_t datum`)
  This function adds the value of 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.

  Note that using a constant for 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.

  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.

  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.

  If it is desired to mix in the datum and to add in a timestamp, but not to actually estimate entropy from a source of randomness, passing ```NULL` for rnd_source is permitted, and the device does not need to be attached.

rnd_add_data(```rndsource_element_t *rnd_source``, void *data``, uint32_t len``, uint32_t entropy`)
  adds (hopefully) random ```data` to the entropy pool. ```len` is the number of bytes in ```data` and ```entropy` is an "entropy quality" measurement. If every bit of ```data` is known to be random, ```entropy` is the number of bits in ```data`.

  Timing information is also used to add entropy into the system, using inter-event timings.

  If it is desired to mix in the data and to add in a timestamp, but not to actually estimate entropy from a source of randomness, passing ```NULL` for rnd_source is permitted, and the device does not need to be attached.

### FILES

These functions are declared in src/sys/sys/rnd.h and defined in src/sys/dev/rnd.c.

### SEE ALSO

rnd(4), rndctl(8)

### HISTORY

The random device was introduced in NetBSD1.3.

### AUTHORS

This implementation was written by Michael Graff <explorer@flame.org> using ideas and algorithms gathered from many sources, including the driver written by Ted Ts'o.

### 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".