👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for cprng_fast64 (netbsd section 9)

CPRNG(9)			  BSD Kernel Developer's Manual 			 CPRNG(9)

NAME
     cprng, cprng_strong_create, cprng_strong, cprng_strong32, cprng_strong64,
     cprng_strong_getflags, cprng_strong_setflags, cprng_strong_ready, cprng_strong_destroy,
     cprng_fast, cprng_fast32, cprng_fast64, -- cryptographic pseudo-random number generators

SYNOPSIS
     #include <sys/cprng.h>

     cprng_strong_t
     cprng_strong_create(const char *const name, int ipl, int flags);

     void
     cprng_strong_destroy(cprng_strong_t *cprng);

     size_t
     cprng_strong(cprng_strong_t *const cprng, void *buf, size_t len, int blocking);

     size_t
     cprng_fast(void *buf, size_t len);

     uint32_t
     cprng_strong32(void);

     uint64_t
     cprng_strong64(void);

     uint32_t
     cprng_fast32(void);

     uint32_t
     cprng_fast64(void);

     int
     cprng_strong_getflags(cprng_strong_t *const cprng);

     void
     cprng_strong_setflags(cprng_strong_t *const cprng, int flags);

     #define CPRNG_MAX_LEN   524288

     typedef struct _cprng_strong {
	     kmutex_t	     mtx;
	     kcondvar_t      cv;
	     struct selinfo  selq;
	     NIST_CTR_DRBG   drbg;
	     int	     flags;
	     char	     name[16];
	     int	     reseed_pending;
	     rndsink_t	     reseed;
     } cprng_strong_t;

DESCRIPTION
     The cprng family of functions supply randomness to callers within the NetBSD kernel.  They
     replace the arc4random(9) and rnd_extract_data(9) functions for this purpose.  The cprng
     functions provide stream generators automatically keyed (and if necessary rekeyed) from the
     kernel entropy pool.  The NetBSD kernel no longer supports direct reading from the kernel
     entropy pool; all access is mediated by the cprng functions.

     The ``strong'' family of functions supply cryptographically strong random numbers suitable
     for keying crypto systems and similar purposes.  Calls to rnd_extract_data(9) should be
     replaced with calls to cprng_strong.

     The ``fast'' family of functions supply less strong random numbers, suitable for initializa-
     tion vectors, nonces in certain protocols, and other similar purposes, using a faster but
     less secure stream-cipher generator.  stream-cipher generator.  Calls to arc4random(9)
     should be replaced with calls to cprng_fast32, and calls to arc4randbytes(9) should be
     replaced with calls to cprng_fast.

     A single instance of the cprng_fast generator serves the entire kernel.  A single, well-
     known instance of the cprng_strong generator, kern_cprng, may be used by any in-kernel call-
     er, but new separately-keyed instances of the cprng_strong generator can also be created by
     calling cprng_strong_create.

FUNCTIONS
     cprng_strong_create(name, ipl, flags)

	   Create an instance of the cprng_strong generator.  This generator implements the NIST
	   SP 800-90 CTR_DRBG with AES128 as the block transform.  The name argument is used to
	   "personalize" the CTR_DRBG according to the standard, so that its initial state will
	   depend both on keying 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)).  The
	   flags argument controls the behavior of the generator:

	   CPRNG_INIT_ANY   Perform initial keying of the generator from the entropy pool even if
			    the current estimate of entropy in the pool is less than the required
			    number of key bits for the generator.

	   CPRNG_REKEY_ANY  When rekeying of the generator is required, key the generator from
			    the entropy pool even if the current estimate of entropy in the pool
			    is less than the required number of key bits for the generator.

	   CPRNG_USE_CV     Perform a cv_broadcast(9) operation on the "cv" member of the
			    returned cprng_strong_t each time the generator is successfully
			    rekeyed.  If this flag is set, the generator will sleep when rekeying
			    is needed, and will therefore always return the requested number of
			    bytes.

	   Creation will succeed even if key material for the generator is not available.  In
	   this case, the first request to read from the generator may cause rekeying.

     cprng_strong_destroy(cprng)

	   Destroy an instance of the cprng_strong generator.

     cprng_strong(cprng, buf, len, blocking)

	   Fill memory location buf with len bytes from the generator cprng.  The blocking argu-
	   ment controls the blocking/non-blocking behavior of the generator: if it is set to
	   FNONBLOCK, the generator may return less than len bytes if it requires rekeying.  If
	   the CPRNG_USE_CV flag is set on the generator, the caller can wait on cprng->cv for
	   notification that the generator can again supply bytes.  A maximum of CPRNG_MAX_LEN
	   bytes may be requested at once; this is a restriction of the CTR_DRBG specification.

     cprng_strong32(cprng)

	   Generate 32 bits using cprng_strong generator cprng.

     cprng_strong64(cprng)

	   Generate 64 bits using cprng_strong generator cprng.

     cprng_strong_getflags(cprng)

	   Get the flags currently in use by generator cprng.

     cprng_strong_setflags(cprng, flags)
	   Set the flags on generator cprng to flags.

     cprng_fast(buf, len)
	   Fill memory location buf with len bytes from the fast generator.

     cprng_fast32()
	   Generate 32 bits using the fast generator.

     cprng_fast64()
	   Generate 64 bits using the fast generator.

CODE REFERENCES
     The cprng API is implemented by sys/kern/subr_cprng.c and sys/sys/cprng.h.  The ``strong''
     generator uses the CTR_DRBG implementation in sys/crypto/nist_ctr_drbg.  The ``fast'' gener-
     ator uses the arc4random implementation in sys/lib/libkern/arc4random.c.

SEE ALSO
     condvar(9), rnd(9), spl(9)

     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.

HISTORY
     The cprng family of functions first appeared in NetBSD 6.0.

BSD					December 17, 2011				      BSD


All times are GMT -4. The time now is 01:52 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password