Documentation
¶
Overview ¶
Package prng implements a seeded, unbiased PRNG that is suitable for use cases including obfuscation, network jitter, load balancing.
Seeding is based on crypto/rand.Read and the PRNG stream is provided by chacha20. As such, this PRNG is suitable for high volume cases such as generating random bytes per IP packet as it avoids the syscall overhead (context switch/spinlock) of crypto/rand.Read.
This PRNG also supports replay use cases, where its intended to reproduce the same traffic shape or protocol attributes there were previously produced.
This PRNG is _not_ for security use cases including production cryptographic key generation.
Limitations: there is a cycle in the PRNG stream, after roughly 2^64 * 2^38-64 bytes; and the global instance initialized in init() ignores seeding errors.
It is safe to make concurrent calls to a PRNG instance, including the global instance, but the caller is responsible for serializing multiple calls as required for replay.
PRNG conforms to io.Reader and math/rand.Source, with additional helper functions.
Index ¶
- Constants
- func Base64String(byteLength int) string
- func Bytes(length int) []byte
- func ExpFloat64Range(min, max, lambda float64) float64
- func FlipCoin() bool
- func FlipWeightedCoin(weight float64) bool
- func HexString(byteLength int) string
- func Int63() int64
- func Int63n(n int64) int64
- func Intn(n int) int
- func Jitter(n int64, factor float64) int64
- func JitterDuration(d time.Duration, factor float64) time.Duration
- func Padding(minLength, maxLength int) []byte
- func Period(min, max time.Duration) time.Duration
- func Perm(n int) []int
- func Range(min, max int) int
- func Read(b []byte) (int, error)
- func Uint64() uint64
- type PRNG
- func (p *PRNG) Base64String(byteLength int) string
- func (p *PRNG) Bytes(length int) []byte
- func (p *PRNG) ExpFloat64Range(min, max, lambda float64) float64
- func (p *PRNG) FlipCoin() bool
- func (p *PRNG) FlipWeightedCoin(weight float64) bool
- func (p *PRNG) GetSeed() *Seed
- func (p *PRNG) HexString(byteLength int) string
- func (p *PRNG) Int63() int64
- func (p *PRNG) Int63n(n int64) int64
- func (p *PRNG) Intn(n int) int
- func (p *PRNG) Jitter(n int64, factor float64) int64
- func (p *PRNG) JitterDuration(d time.Duration, factor float64) time.Duration
- func (p *PRNG) Padding(minLength, maxLength int) []byte
- func (p *PRNG) Period(min, max time.Duration) time.Duration
- func (p *PRNG) Perm(n int) []int
- func (p *PRNG) Range(min, max int) int
- func (p *PRNG) Read(b []byte) (int, error)
- func (p *PRNG) Seed(_ int64)
- func (p *PRNG) Uint64() uint64
- type Seed
Constants ¶
const (
SEED_LENGTH = 32
)
Variables ¶
This section is empty.
Functions ¶
func Base64String ¶
func ExpFloat64Range ¶
func FlipWeightedCoin ¶
Types ¶
type PRNG ¶
type PRNG struct {
// contains filtered or unexported fields
}
PRNG is a seeded, unbiased PRNG based on chacha20.
func DefaultPRNG ¶
func DefaultPRNG() *PRNG
func NewPRNGWithSaltedSeed ¶
NewPRNGWithSaltedSeed initializes a new PRNG using a seed derived from an existing seed and a salt with NewSaltedSeed.
func NewPRNGWithSeed ¶
NewPRNGWithSeed initializes a new PRNG using an existing seed.
func (*PRNG) Base64String ¶
Base64String returns a base64 encoded random string. byteLength specifies the pre-encoded data length.
func (*PRNG) ExpFloat64Range ¶
ExpFloat64Range returns a pseudo-exponentially distributed float64 in the range [min, max] with the specified lambda. Numbers are selected using math/rand.ExpFloat64 and discarding values that exceed max.
If max < min or lambda is <= 0, min is returned.
func (*PRNG) FlipWeightedCoin ¶
FlipWeightedCoin returns the result of a weighted random coin flip. If the weight is 0.5, the outcome is equally likely to be true or false. If the weight is 1.0, the outcome is always true, and if the weight is 0.0, the outcome is always false.
Input weights > 1.0 are treated as 1.0.
func (*PRNG) GetSeed ¶
GetSeed returns the seed for the PRNG. The returned value must not be mutated.
func (*PRNG) HexString ¶
HexString returns a hex encoded random string. byteLength specifies the pre-encoded data length.
func (*PRNG) Int63n ¶
Int63n is equivilent to math/rand.Int63n, except it returns 0 if n <= 0 instead of panicking.
func (*PRNG) Intn ¶
Intn is equivilent to math/rand.Intn, except it returns 0 if n <= 0 instead of panicking.
func (*PRNG) Jitter ¶
Jitter returns n +/- the given factor. For example, for n = 100 and factor = 0.1, the return value will be in the range [90, 110].
func (*PRNG) JitterDuration ¶
JitterDuration invokes Jitter for time.Duration.
func (*PRNG) Padding ¶
Padding selects a random padding length in the indicated range and returns a random byte slice of the selected length. If maxLength <= minLength, the padding is minLength.
func (*PRNG) Period ¶
Period returns a random duration, within a given range. If max <= min, the duration is min.
func (*PRNG) Range ¶
Range selects a random integer in [min, max]. If min < 0, min is set to 0. If max < min, min is returned.
func (*PRNG) Read ¶
Read reads random bytes from the PRNG stream into b. Read conforms to io.Reader and always returns len(p), nil.
type Seed ¶
type Seed [SEED_LENGTH]byte
Seed is a PRNG seed.
func NewSaltedSeed ¶
NewSaltedSeed creates a new seed derived from an existing seed and a salt. A HKDF is applied to the seed and salt.
NewSaltedSeed is intended for use cases where a single seed needs to be used in distinct contexts to produce independent random streams.
Source Files