prng

package
v2.0.14+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 17, 2020 License: GPL-3.0 Imports: 13 Imported by: 0

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

View Source
const (
	SEED_LENGTH = 32
)

Variables

This section is empty.

Functions

func Base64String

func Base64String(byteLength int) string

func Bytes

func Bytes(length int) []byte

func ExpFloat64Range

func ExpFloat64Range(min, max, lambda float64) float64

func FlipCoin

func FlipCoin() bool

func FlipWeightedCoin

func FlipWeightedCoin(weight float64) bool

func HexString

func HexString(byteLength int) string

func Int63

func Int63() int64

func Int63n

func Int63n(n int64) int64

func Intn

func Intn(n int) int

func Jitter

func Jitter(n int64, factor float64) int64

func JitterDuration

func JitterDuration(d time.Duration, factor float64) time.Duration

func Padding

func Padding(minLength, maxLength int) []byte

func Period

func Period(min, max time.Duration) time.Duration

func Perm

func Perm(n int) []int

func Range

func Range(min, max int) int

func Read

func Read(b []byte) (int, error)

func Uint64

func Uint64() uint64

Types

type PRNG

type PRNG struct {
	// contains filtered or unexported fields
}

PRNG is a seeded, unbiased PRNG based on chacha20.

func NewPRNG

func NewPRNG() (*PRNG, error)

NewPRNG generates a seed and creates a PRNG with that seed.

func NewPRNGWithSaltedSeed

func NewPRNGWithSaltedSeed(seed *Seed, salt string) (*PRNG, error)

NewPRNGWithSaltedSeed initializes a new PRNG using a seed derived from an existing seed and a salt with NewSaltedSeed.

func NewPRNGWithSeed

func NewPRNGWithSeed(seed *Seed) *PRNG

NewPRNGWithSeed initializes a new PRNG using an existing seed.

func (*PRNG) Base64String

func (p *PRNG) Base64String(byteLength int) string

Base64String returns a base64 encoded random string. byteLength specifies the pre-encoded data length.

func (*PRNG) Bytes

func (p *PRNG) Bytes(length int) []byte

Bytes returns a new slice containing length random bytes.

func (*PRNG) ExpFloat64Range

func (p *PRNG) ExpFloat64Range(min, max, lambda float64) float64

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) FlipCoin

func (p *PRNG) FlipCoin() bool

FlipCoin randomly returns true or false.

func (*PRNG) FlipWeightedCoin

func (p *PRNG) FlipWeightedCoin(weight float64) bool

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

func (p *PRNG) GetSeed() *Seed

GetSeed returns the seed for the PRNG. The returned value must not be mutated.

func (*PRNG) HexString

func (p *PRNG) HexString(byteLength int) string

HexString returns a hex encoded random string. byteLength specifies the pre-encoded data length.

func (*PRNG) Int63

func (p *PRNG) Int63() int64

Int63 is equivilent to math/read.Int63.

func (*PRNG) Int63n

func (p *PRNG) Int63n(n int64) int64

Int63n is equivilent to math/read.Int63n, except it returns 0 if n <= 0 instead of panicking.

func (*PRNG) Intn

func (p *PRNG) Intn(n int) int

Intn is equivilent to math/read.Intn, except it returns 0 if n <= 0 instead of panicking.

func (*PRNG) Jitter

func (p *PRNG) Jitter(n int64, factor float64) int64

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

func (p *PRNG) JitterDuration(d time.Duration, factor float64) time.Duration

JitterDuration invokes Jitter for time.Duration.

func (*PRNG) Padding

func (p *PRNG) Padding(minLength, maxLength int) []byte

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

func (p *PRNG) Period(min, max time.Duration) time.Duration

Period returns a random duration, within a given range. If max <= min, the duration is min.

func (*PRNG) Perm

func (p *PRNG) Perm(n int) []int

Intn is equivilent to math/read.Perm.

func (*PRNG) Range

func (p *PRNG) Range(min, max int) int

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

func (p *PRNG) Read(b []byte) (int, error)

Read reads random bytes from the PRNG stream into b. Read conforms to io.Reader and always returns len(p), nil.

func (*PRNG) Seed

func (p *PRNG) Seed(_ int64)

Seed must exist in order to use a PRNG as a math/rand.Source. This call is not supported and ignored.

func (*PRNG) Uint64

func (p *PRNG) Uint64() uint64

Int63 is equivilent to math/read.Uint64.

type Seed

type Seed [SEED_LENGTH]byte

Seed is a PRNG seed.

func NewSaltedSeed

func NewSaltedSeed(seed *Seed, salt string) (*Seed, error)

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.

func NewSeed

func NewSeed() (*Seed, error)

NewSeed creates a new PRNG seed using crypto/rand.Read.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL