I would appreciate any donations. Wishlist or send e-mail type donations to maekawa AT daemon-systems.org.

Thank you.


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.

NetBSD 7.1.2                    April 10, 2013                    NetBSD 7.1.2