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.