package drbg

Import Path
	crypto/internal/fips140/drbg (on go.dev)

Dependency Relation
	imports 13 packages, and imported by 10 packages

Involved Source Files

	    cast.go
	    ctrdrbg.go
	    entropy_fips140.go
	  d rand.go
		Package drbg provides cryptographically secure random bytes
		usable by FIPS code. In FIPS mode it uses an SP 800-90A Rev. 1
		Deterministic Random Bit Generator (DRBG). Otherwise,
		it uses the operating system's random number generator.
Package-Level Type Names (total 2, both are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Counter (struct)
		Counter is an SP 800-90A Rev. 1 CTR_DRBG instantiated with AES-256.
		
		Per Table 3, it has a security strength of 256 bits, a seed size of 384 bits,
		a counter length of 128 bits, a reseed interval of 2^48 requests, and a
		maximum request size of 2^19 bits (2^16 bytes, 64 KiB).
		
		We support a narrow range of parameters that fit the needs of our RNG:
		AES-256, no derivation function, no personalization string, no prediction
		resistance, and 384-bit additional input.
		
		WARNING: this type provides tightly scoped support for the DRBG
		functionality we need for FIPS 140-3 _only_. This type _should not_ be used
		outside of the FIPS 140-3 module for any other use.
		
		In particular, as documented, Counter does not support the derivation
		function, or personalization strings which are necessary for safely using
		this DRBG for generic purposes without leaking sensitive values.

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			c aes.CTR
				c is instantiated with K as the key and V as the counter.

			reseedCounter uint64
		Methods (total 3, in which 2 are exported)
			(*Counter) Generate(out []byte, additionalInput *[48]byte) (reseedRequired bool)
				Generate produces at most maxRequestSize bytes of random data in out.

			(*Counter) Reseed(entropy, additionalInput *[48]byte)
			/* one unexported ... *//* one unexported: */
			(*Counter) update(seed *[48]byte)
		As Outputs Of (at least one exported)
			func NewCounter(entropy *[48]byte) *Counter

	 type DefaultReader (interface)
		DefaultReader is a sentinel type, embedded in the default
		[crypto/rand.Reader], used to recognize it when passed to
		APIs that accept a rand io.Reader.
		
		Any Reader that implements this interface is assumed to
		call [Read] as its Read method.

		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			( DefaultReader) defaultReader()
		Implemented By (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			 crypto/internal/rand.reader


Package-Level Functions (total 8, in which 4 are exported)

	 func NewCounter(entropy *[48]byte) *Counter
	 func Read(b []byte)
		Read fills b with cryptographically secure random bytes. In FIPS mode, it
		uses an SP 800-90A Rev. 1 Deterministic Random Bit Generator (DRBG).
		Otherwise, it uses the operating system's random number generator.

	 func ReadWithReader(r io.Reader, b []byte) error
		ReadWithReader uses Reader to fill b with cryptographically secure random
		bytes. It is intended for use in APIs that expose a rand io.Reader.

	 func SetTestingReader(r io.Reader)
		SetTestingReader sets a global, deterministic cryptographic randomness source
		for testing purposes. Its Read method must never return an error, it must
		never return short, and it must be safe for concurrent use.
		
		This is only intended to be used by the testing/cryptotest package.

	/* 4 unexporteds ... *//* 4 unexporteds: */
	 func getEntropy() *[48]byte
	 func increment(v *[16]byte)
	 func init()
	 func readFromEntropy(b []byte)
Package-Level Variables (total 4, none are exported)

	/* 4 unexporteds ... *//* 4 unexporteds: */
	  var drbgInstance atomic.Pointer[Counter]
		getEntropy is very slow (~500µs), so we don't want it on the hot path.
		We keep both a persistent DRBG instance and a pool of additional instances.
		Occasional uses will use drbgInstance, even if the pool was emptied since the
		last use. Frequent concurrent uses will fill the pool and use it.

	  var drbgPool sync.Pool
	  var memory entropy.ScratchBuffer
		memory is a scratch buffer that is accessed between samples by the entropy
		source to expose it to memory access timings.
		
		We reuse it and share it between Seed calls to avoid the significant (~500µs)
		cost of zeroing a new allocation every time. The entropy source accesses it
		using atomics (and doesn't care about its contents).
		
		It should end up in the .noptrbss section, and become backed by physical pages
		at first use. This ensures that programs that do not use the FIPS 140-3 module
		do not incur any memory use or initialization penalties.

	  var testingReader io.Reader
Package-Level Constants (total 4, in which 1 is exported)

	const SeedSize = 48
	/* 3 unexporteds ... *//* 3 unexporteds: */
	const keySize = 32
	const maxRequestSize = 65536
	const reseedInterval = 281474976710656

The pages are generated with Golds v0.8.4. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.