RNDSINK(9)

RNDSINK(9) | Kernel Developer's Manual | RNDSINK(9)

# NAME

`rndsink`, `rndsink_create`, `rndsink_destroy`, `rndsink_request`, `rndsink_schedule`, —
functions to asynchronously request entropy from the system entropy pool

# SYNOPSIS

`#include <sys/rndsink.h>`

struct rndsink *
`rndsink_create`(size_t bytes, void (*callback)(void *, const void *, size_t), void *arg);

void
`rndsink_destroy`(struct rndsink *rndsink);

bool
`rndsink_request`(struct rndsink *rndsink, void *buffer, size_t bytes);

void
`rndsink_schedule`(struct rndsink *rndsink);

# DESCRIPTION

The `rndsink` functions support asynchronous requests for entropy from the system entropy pool. Users must call `rndsink_create`() to create an rndsink which they may then pass to `rndsink_request`() to request data from the system entropy pool. If full entropy is not available, the system will call a callback when entropy is next available. Users can schedule a callback without requesting data now using `rndsink_schedule`(). When users no longer need an rndsink, they must pass it to `rndsink_destroy`().

This API provides direct access to the system entropy pool. Most users should use the cprng(9) API instead, which interposes a cryptographic pseudorandom number generator between the user and the entropy pool.

# FUNCTIONS

`rndsink_create`(bytes, callback, arg)
  Create an rndsink for requests of bytes bytes of entropy, which must be no more than `RNDSINK_MAX_BYTES`. When requested and enough entropy is available, the system will call callback with three arguments:
  - arg, an arbitrary user-supplied pointer;
  - a pointer to a buffer containing the bytes of entropy; and
  - the number of bytes in the buffer, which will always be bytes.

  The callback will be called in soft interrupt context.

  `rndsink_create`() may sleep to allocate memory.

`rndsink_destroy`(rndsink)
  Destroy an rndsink. `rndsink_destroy`() may sleep to wait for pending callbacks to complete and to deallocate memory.
`rndsink_request`(rndsink, buffer, bytes)
  Store bytes bytes derived from the system entropy pool in buffer. If the bytes have full entropy, return true. Otherwise, schedule a callback as if with `rndsink_schedule`() and return false. In either case, `rndsink_request`() will store data in buffer. The argument bytes must be the same as the argument to `rndsink_create`() that was used to create rndsink. May be called at `IPL_VM` or lower. The caller should use explicit_memset(3) to clear buffer once it has used the data stored there.
`rndsink_schedule`(rndsink)
  Schedule a callback when the system entropy pool has enough entropy. If a callback is already scheduled, it remains scheduled. May be called at `IPL_VM` or lower.

# CODE REFERENCES

The rndsink API is implemented in sys/kern/kern_rndsink.c and sys/sys/rndsink.h.

# SEE ALSO

explicit_memset(3), cprng(9), rnd(9)

# HISTORY

The rndsink API first appeared in NetBSD 7.0.

April 10, 2013 | NetBSD 9.5