| 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_ANYcprng_strong_create(), only partial entropy
          for the generator is available from the entropy pool.CPRNG_REKEY_ANYcprng_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_CVcprng_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_HARDCreation 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.4 |