CPRNG(9) | Kernel Developer's Manual | CPRNG(9) |
cprng
, cprng_strong_create
,
cprng_strong_destroy
,
cprng_strong
, cprng_strong32
,
cprng_strong64
, cprng_fast
,
cprng_fast32
, cprng_fast64
,
—
#include <sys/cprng.h>
cprng_strong_t *
cprng_strong_create
(const
char *name, int
ipl, int
flags);
void
cprng_strong_destroy
(cprng_strong_t
*cprng);
size_t
cprng_strong
(cprng_strong_t
*cprng, void *buf,
size_t len,
int flags);
uint32_t
cprng_strong32
(void);
uint64_t
cprng_strong64
(void);
size_t
cprng_fast
(void
*buf, size_t
len);
uint32_t
cprng_fast32
(void);
uint64_t
cprng_fast64
(void);
#define CPRNG_MAX_LEN 524288
cprng
family of functions provide cryptographic
pseudorandom number generators automatically seeded from the kernel entropy
pool. All applications in the kernel requiring random data or random choices
should use the cprng_strong
family of functions,
unless performance constraints demand otherwise.
The cprng_fast
family of functions may be
used in applications that can tolerate exposure of past random data, such as
initialization vectors or transaction ids that are sent over the internet
anyway, if the applications require higher throughput or lower per-request
latency than the cprng_strong
family of functions
provide. If in doubt, choose cprng_strong
.
A single instance of the fast generator serves the entire kernel.
A well-known instance of the strong generator,
kern_cprng
, may be used by any in-kernel caller, but
separately seeded instances of the strong generator can also be created by
calling cprng_strong_create
().
The cprng
functions may be used at
interrupt priority level IPL_VM
or below, except for
cprng_strong_create
() and
cprng_strong_destroy
() which are allowed only at
IPL_NONE
; see
spl(9).
The cprng
functions replace the legacy
arc4random(9) and
rnd_extract_data(9)
functions.
cprng_strong_create
(name,
ipl, flags)The name argument is used to “personalize” the CTR_DRBG according to the standard, so that its initial state will depend both on seed material from the entropy pool and also on the personalization string (name).
The ipl argument specifies the interrupt
priority level for the mutex which will serialize access to the new
instance of the generator (see
spl(9)), and must be no
higher than IPL_VM
.
The flags argument controls the behavior of the generator:
CPRNG_INIT_ANY
cprng_strong_create
(), only partial entropy
for the generator is available from the entropy pool.CPRNG_REKEY_ANY
cprng_strong
() after the generator has been
exhausted and must be reseeded, only partial entropy for the generator
is available from the entropy pool.CPRNG_USE_CV
cprng_strong
() sleep if the generator has
not been seeded with full entropy until full entropy is available.
Otherwise, cprng_strong
() will never sleep
when passed this generator.CPRNG_HARD
Creation will succeed even if full entropy for the generator is not available. In this case, the first request to read from the generator may cause reseeding.
cprng_strong_create
() may sleep to
allocate memory.
cprng_strong_destroy
(cprng)cprng_strong_destroy
() may sleep.
cprng_strong
(cprng,
buf, len,
flags)CPRNG_MAX_LEN
.
If cprng was created with the
CPRNG_USE_CV
flag and has been exhausted, then
cprng_strong
() may sleep until full entropy can
be obtained from the entropy pool to reseed it. However, if
flags includes the
FNONBLOCK
flag, then
cprng_strong
() will immediately return zero in
this case instead.
If cprng was created with the
CPRNG_HARD
flag, then
cprng_strong
() will return at most as many bytes
as are left from its seed size since the last reseeding.
If cprng was created with neither the
CPRNG_USE_CV
flag nor the
CPRNG_HARD
flag, then
cprng_strong
() is guaranteed to return as many
bytes as requested, up to CPRNG_MAX_LEN
, without
sleeping.
cprng_strong32
()kern_cprng
strong
generator.
cprng_strong32
() does not sleep.
cprng_strong64
()kern_cprng
strong
generator.
cprng_strong64
() does not sleep.
cprng_fast
(buf,
len)cprng_fast
() does not sleep.
cprng_fast32
()cprng_fast32
() does not sleep.
cprng_fast64
()cprng_fast64
() does not sleep.
cprng
family of functions provide the following
security properties:
cprng
functions cannot predict past or future
unseen outputs.cprng_strong
functions. However, such an
attacker may be able to predict past outputs of the
cprng_fast
functions.The second property is sometimes called “backtracking
resistance”, “forward secrecy”, or “key
erasure” in the cryptography literature. The
cprng_strong
functions provide backtracking
resistance; the cprng_fast
functions do not.
cprng_strong
functions are implemented in
sys/kern/subr_cprng.c, and use the NIST SP 800-90A
CTR_DRBG implementation in sys/crypto/nist_ctr_drbg.
The cprng_fast
functions are implemented in
sys/crypto/cprng_fast/cprng_fast.c, and use the
ChaCha8 stream cipher.
Elaine Barker and John Kelsey, Recommendation for Random Number Generation Using Deterministic Random Bit Generators (Revised), National Institute of Standards and Technology, 2011, NIST Special Publication 800-90A, Rev 1.
Daniel J. Bernstein, ChaCha, a variant of Salsa20, http://cr.yp.to/papers.html#chacha, 2008-01-28, Document ID: 4027b5256e17b9796842e6d0f68b0b5e.
March 24, 2020 | NetBSD 9.2 |