diff options
| author | martin <martin@NetBSD.org> | 2020-07-15 13:47:40 +0000 |
|---|---|---|
| committer | martin <martin@NetBSD.org> | 2020-07-15 13:47:40 +0000 |
| commit | 7998e8aa10584f00bd2d2474963733ba3bdc1c33 (patch) | |
| tree | dd7d0f5df6c85436ec655e99a0a5de17e685f972 /share | |
| parent | 66a77467f18bab228a07c690a385419570a1f77f (diff) | |
Pull up following revision(s) (requested by riastradh in ticket #1007):
share/man/man9/rnd.9: revision 1.26
share/man/man9/rnd.9: revision 1.27
Update rnd(9) man page to reflect reality since netbsd-7.
- Note rndsource_setcb, RND_FLAG_HASCB, and rnd_add_data_sync.
- Note user's obligation to serialize access to each rndsource.
Simplify macro usage.
Diffstat (limited to 'share')
| -rw-r--r-- | share/man/man9/rnd.9 | 82 |
1 files changed, 77 insertions, 5 deletions
diff --git a/share/man/man9/rnd.9 b/share/man/man9/rnd.9 index f55c49eb7ad..69ff85daf04 100644 --- a/share/man/man9/rnd.9 +++ b/share/man/man9/rnd.9 @@ -1,4 +1,4 @@ -.\" $NetBSD: rnd.9,v 1.25 2015/04/13 22:23:54 riastradh Exp $ +.\" $NetBSD: rnd.9,v 1.25.18.1 2020/07/15 13:47:40 martin Exp $ .\" .\" Copyright (c) 1997 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -35,17 +35,22 @@ .Nm rnd_attach_source , .Nm rnd_detach_source , .Nm rnd_add_data , +.Nm rnd_add_data_sync , .Nm rnd_add_uint32 .Nd functions to make a device available for entropy collection .Sh SYNOPSIS .In sys/rndsource.h .Ft void +.Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie" +.Ft void .Fn rnd_attach_source "krndsource_t *rnd_source" "char *devname" "uint32_t source_type" "uint32_t flags" .Ft void .Fn rnd_detach_source "krndsource_t *rnd_source" .Ft void .Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" .Ft void +.Fn rnd_add_data_sync "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" +.Ft void .Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" .Sh DESCRIPTION These @@ -58,6 +63,9 @@ and .Pa ( /dev/random ) interfaces. .Pp +The caller must zero an +.Fa rnd_source +object before using it. Ideally the first argument .Fa rnd_source of these functions gets included in the devices' entity struct, @@ -65,9 +73,55 @@ but any means to permanently (statically) attach one such argument to one incarnation of the device is ok. Do not share .Fa rnd_source -structures between two devices. -.Pp +structures between two devices, and make sure to serialize all access +to each +.Fa rnd_source , +for example with +.Xr mutex 9 . .Bl -tag -width 8n +.It Fn rndsource_setcb "krndsource_t *rnd_source" "void (*callback)(size_t, void *)" "void *cookie" +This function sets a callback to be invoked when the kernel entropy +pool is hungry. +It is optional; if used, it must be used +.Em before +.Fn rnd_attach_source , +and the caller must pass +.Dv RND_FLAG_HASCB +to +.Fn rnd_attach_source +in order for the callback to be used. +The callback is invoked as +.Fa callback ( Fa nbytes , Fa cookie ) , +where +.Fa nbytes +is the number of bytes requested for the entropy pool, and +.Fa cookie +is the cookie that was passed to +.Fn rndsource_setcb . +The callback normally does one of two things: +.Bl -dash +.It +Sends a request to a hardware device for entropy and returns. +The hardware will later return data asynchronously by an interrupt, and +the callback will use +.Fn rnd_add_data +or +.Fn rnd_add_uint32 +to add the data to the pool. +.It +Synchronously gathers entropy from hardware \(em for example, by a CPU +instruction like Intel RDSEED. +In this case, in order to add data to the pool +.Em before +returning, the callback +.Em must +use +.Fn rnd_add_data_sync , +not +.Fn rnd_add_data +or +.Fn rnd_add_uint32 . +.El .It Fn rnd_attach_source "krndsource_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 @@ -109,7 +163,10 @@ are the logical OR of the pool estimate) .Dv RND_FLAG_ESTIMATE_TIME (use a delta estimator to count bits of entropy from this source's timestamps -towards the pool estimate). +towards the pool estimate) +.Dv RND_FLAG_HASCB +(caller specified a callback with +.Fn rndsource_setcb ) . For many devices, .Dv RND_FLAG_DEFAULT .Dv ( RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME | RND_FLAG_ESTIMATE_TIME ) @@ -119,7 +176,6 @@ Note that devices of type default to .Dv RND_FLAG_COLLECT_VALUE | RND_FLAG_COLLECT_TIME (no entropy counted). -.Pp .It Fn rnd_detach_source "krndsource_t *rnd_source" This function disconnects the device from entropy collection. .It Fn rnd_add_uint32 "krndsource_t *rnd_source" "uint32_t datum" @@ -155,6 +211,14 @@ of randomness, passing for .Va rnd_source is permitted, and the device does not need to be attached. +.Pp +.Fn rnd_add_uint32 +.Em must not +be used during a callback as set with +.Fn rndsource_setcb ; +use +.Fn rnd_add_data_sync +instead. .It Fn rnd_add_data "krndsource_t *rnd_source" "void *data" "uint32_t len" "uint32_t entropy" adds (hopefully) random .Fa data @@ -183,6 +247,14 @@ of randomness, passing for .Va rnd_source is permitted, and the device does not need to be attached. +.Pp +.Fn rnd_add_data +.Em must not +be used during a callback as set with +.Fn rndsource_setcb ; +use +.Fn rnd_add_data_sync +instead. .El .Sh INTERNAL ENTROPY POOL MANAGEMENT When a hardware event occurs (such as completion of a hard drive |
