README
¶
rand
Overview
Package rand implements a fast userspace cryptographically secure pseudorandom
number generator (CSPRNG) that is periodically reseeded with entropy obtained
from crypto/rand. The PRNG can be used to obtain random bytes as well as
generating uniformly-distributed integers in a full or limited range. It also
provides additional convenience functions for common related tasks such as
obtaining uniformly-distributed time.Durations and randomizing the order of
all elements in a slice without bias.
The default global PRNG will never panic after package init and is safe for
concurrent access. Additional PRNGs which avoid the locking overhead can be
created by calling NewPRNG.
Statistical Test Quality Assessment Results
The quality of the random number generation provided by this implementation has been verified against statistical tests from the following test suites:
- Dieharder: A Random Number Test Suite
- NIST Statistical Test Suite (STS)
- AIS 31 / BSI suite procedure A (tests T0 and T1-T5)
- NIST Entropy Assessment (EA) Test Suite
Benchmarks
The following results demonstrate the performance of most provided operations. The benchmarks are from a Ryzen 7 5800X3D processor on Linux and are the result of feeding benchstat 10 iterations of each.
| Operation | Time / Op | Allocs / Op |
|---|---|---|
| Read (4b) | 22.0ns ± 1% | 0 |
| Read (8b) | 28.4ns ± 1% | 0 |
| Read (32b) | 68.5ns ± 1% | 0 |
| Read (512b) | 709ns ± 1% | 0 |
| Read (1KiB) | 1.38µs ± 1% | 0 |
| Read (4KiB) | 5.41µs ± 1% | 0 |
| ReadPRNG (4b) | 18.0ns ± 1% | 0 |
| ReadPRNG (8b) | 24.2ns ± 1% | 0 |
| ReadPRNG (32b) | 61.3ns ± 2% | 0 |
| ReadPRNG (512b) | 684ns ± 0% | 0 |
| ReadPRNG (1KiB) | 1.35µs ± 0% | 0 |
| ReadPRNG (4KiB) | 5.39µs ± 1% | 0 |
| Int32N | 32.4ns ± 3% | 0 |
| Uint32N | 32.7ns ± 2% | 0 |
| Int64N | 31.2ns ± 2% | 0 |
| Uint64N | 31.2ns ± 2% | 0 |
| Duration | 33.8ns ±12% | 0 |
| ShuffleSlice | 28.0ns ± 1% | 0 |
Read Performance Comparison Vs Standard Libary
The following benchmark results demonstrate the performance of reading random
bytes as compared to standard library crypto/rand. The benchmarks are from a
Ryzen 7 5800X3D processor on Linux and are the result of feeding benchstat 10
iterations of each.
| Operation | stdlib Time / Op |
dcrd Time / Op |
Delta vs stdlib |
|---|---|---|---|
| Read (4b) | 470ns ± 7% | 22ns ± 1% | -95.32% |
| Read (8b) | 447ns ± 1% | 28ns ± 1% | -93.65% |
| Read (32b) | 447ns ± 1% | 68ns ± 1% | -84.67% |
| Read (512b) | 1.72µs ± 6% | 0.71µs ± 1% | -58.78% |
| Read (1KiB) | 2.89µs ± 1% | 1.38µs ± 1% | -52.09% |
| Read (4KiB) | 10.5µs ± 2% | 5.4µs ± 1% | -48.37% |
Installation and Updating
This package is part of the github.com/decred/dcrd/crypto/rand module. Use
the standard go tooling for working with modules to incorporate it.
License
Package rand is licensed under the copyfree ISC License.
Documentation
¶
Overview ¶
Package rand implements a fast userspace CSPRNG that is periodically reseeded with entropy obtained from crypto/rand. The PRNG can be used to obtain random bytes as well as generating uniformly-distributed integers in a full or limited range.
The default global PRNG will never panic after package init and is safe for concurrent access. Additional PRNGs which avoid the locking overhead can be created by calling NewPRNG.
Index ¶
- func BigInt(max *big.Int) *big.Int
- func Duration(n time.Duration) time.Duration
- func Int() int
- func Int32() int32
- func Int32N(n int32) int32
- func Int64() int64
- func Int64N(n int64) int64
- func IntN(n int) int
- func N[Int intType](n Int) Int
- func Read(b []byte)
- func Reader() io.Reader
- func Shuffle(n int, swap func(i, j int))
- func ShuffleSlice[S ~[]E, E any](s S)
- func Uint32() uint32
- func Uint32N(n uint32) uint32
- func Uint64() uint64
- func Uint64N(n uint64) uint64
- func UintN(n uint) uint
- type PRNG
- func (p *PRNG) BigInt(max *big.Int) *big.Int
- func (p *PRNG) Duration(n time.Duration) time.Duration
- func (p *PRNG) Int() int
- func (p *PRNG) Int32() int32
- func (p *PRNG) Int32N(n int32) int32
- func (p *PRNG) Int64() int64
- func (p *PRNG) Int64N(n int64) int64
- func (p *PRNG) IntN(n int) int
- func (p *PRNG) Read(s []byte) (n int, err error)
- func (p *PRNG) Shuffle(n int, swap func(i, j int))
- func (p *PRNG) Uint32() uint32
- func (p *PRNG) Uint32N(n uint32) uint32
- func (p *PRNG) Uint64() uint64
- func (p *PRNG) Uint64N(n uint64) uint64
- func (p *PRNG) UintN(n uint) uint
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Int32 ¶
func Int32() int32
Int32 returns a random 31-bit non-negative integer as an int32 without modulo bias.
func Int32N ¶
Int32N returns, as an int32, a random 31-bit non-negative integer in [0,n) without modulo bias. Panics if n <= 0.
func Int64 ¶
func Int64() int64
Int64 returns a random 63-bit non-negative integer as an int64 without modulo bias.
func Int64N ¶
Int64N returns, as an int64, a random 63-bit non-negative integer in [0,n) without modulo bias. Panics if n <= 0.
func IntN ¶
IntN returns, as an int, a random non-negative integer in [0,n) without modulo bias. Panics if n <= 0.
func N ¶
func N[Int intType](n Int) Int
N returns a pseudo-random number in the half-open interval [0,n). The type parameter Int can be any integer type. Panics if n <= 0.
func Read ¶
func Read(b []byte)
Read fills b with random bytes obtained from the default userspace PRNG.
func Reader ¶
Reader returns the default cryptographically secure userspace PRNG that is periodically reseeded with entropy obtained from crypto/rand. The returned Reader is safe for concurrent access.
func Shuffle ¶
Shuffle randomizes the order of n elements by swapping the elements at indexes i and j. Panics if n < 0.
func ShuffleSlice ¶
func ShuffleSlice[S ~[]E, E any](s S)
ShuffleSlice randomizes the order of all elements in s.
Types ¶
type PRNG ¶
type PRNG struct {
// contains filtered or unexported fields
}
PRNG is a cryptographically secure pseudorandom number generator capable of generating random bytes and integers. PRNG methods are not safe for concurrent access.
func (*PRNG) Duration ¶
Duration returns a random duration in [0,n) without modulo bias. Panics if n <= 0.
func (*PRNG) Int32 ¶
Int32 returns a random 31-bit non-negative integer as an int32 without modulo bias.
func (*PRNG) Int32N ¶
Int32N returns, as an int32, a random 31-bit non-negative integer in [0,n) without modulo bias. Panics if n <= 0.
func (*PRNG) Int64 ¶
Int64 returns a random 63-bit non-negative integer as an int64 without modulo bias.
func (*PRNG) Int64N ¶
Int64N returns, as an int64, a random 63-bit non-negative integer in [0,n) without modulo bias. Panics if n <= 0.
func (*PRNG) IntN ¶
IntN returns, as an int, a random non-negative integer in [0,n) without modulo bias. Panics if n <= 0.
func (*PRNG) Read ¶
Read fills s with len(s) of cryptographically-secure random bytes. Read never errors.
func (*PRNG) Shuffle ¶
Shuffle randomizes the order of n elements by swapping the elements at indexes i and j. Panics if n < 0.
Source Files