CPRNG(9) | Kernel Developer's Manual | CPRNG(9) |
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);
uint32_t
cprng_fast64(void);
#define CPRNG_MAX_LEN 524288
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.
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:
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() may sleep.
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() does not sleep.
cprng_strong64() does not sleep.
cprng_fast() does not sleep.
cprng_fast32() does not sleep.
cprng_fast64() does not sleep.
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.
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.
February 19, 2015 | NetBSD 7.2 |