random

Documentation

Index

• Constants
• func BasicDistributionTest(t *testing.T, n uint64, classWidth uint64, randf func() (uint64, error))
• func EncodePermutation(perm []int) int
• func EvaluateDistributionUniformity(t *testing.T, distribution []float64)
• func NewChacha20PRG(seed []byte, customizer []byte) (*chachaPRG, error)
• func RestoreChacha20PRG(stateBytes []byte) (*chachaPRG, error)
• type Rand

Constants

const (

	// Chacha20SeedLen is the seed length of the Chacha based PRG, it is fixed to 32 bytes.
	Chacha20SeedLen = keySize
	// Chacha20CustomizerMaxLen is the maximum length of the nonce used as a PRG customizer, it is fixed to 24 bytes.
	// Shorter customizers are padded by zeros to 24 bytes.
	Chacha20CustomizerMaxLen = nonceSize
)

Functions

func BasicDistributionTest

func BasicDistributionTest(t *testing.T, n uint64, classWidth uint64, randf func() (uint64, error))

BasicDistributionTest is a test function to run a basic statistic test on `randf` output. `randf` is a function that outputs random integers. It partitions all outputs into `n` continuous classes and computes the distribution over the partition. Each class has a width of `classWidth`: first class is [0..classWidth-1], second class is [classWidth..2*classWidth-1], etc.. It computes the frequency of outputs in the `n` classes and computes the standard deviation of frequencies. A small standard deviation is a necessary condition for a uniform distribution of `randf` (but is not a guarantee of uniformity)

func EncodePermutation

func EncodePermutation(perm []int) int

computes a bijection from the set of all permutations into the the set [0, n!-1] (where `n` is the size of input `perm`). input `perm` is assumed to be a correct permutation of the set [0,n-1] (not checked in this function).

func EvaluateDistributionUniformity

func EvaluateDistributionUniformity(t *testing.T, distribution []float64)

EvaluateDistributionUniformity evaluates if the input distribution is close to uniform through a basic quick test. The test computes the standard deviation and checks it is small enough compared to the distribution mean.

func NewChacha20PRG

func NewChacha20PRG(seed []byte, customizer []byte) (*chachaPRG, error)

NewChacha20PRG returns a new Chacha20-based PRG, seeded with the input seed (32 bytes) and a customizer (up to 12 bytes).

It is recommended to sample the seed uniformly at random. The function errors if the seed is different than 32 bytes, or if the customizer is larger than 12 bytes. Shorter customizers than 12 bytes are padded by zero bytes.

func RestoreChacha20PRG

func RestoreChacha20PRG(stateBytes []byte) (*chachaPRG, error)

RestoreChacha20PRG creates a chacha20 base PRG based on a previously stored state. The created PRG is restored at the same state where the previous PRG was stored.

Types

type Rand

type Rand interface {
	// Read fills the input slice with random bytes.
	Read([]byte)

	// UintN returns a random number between 0 and N (exclusive)
	UintN(uint64) uint64

	// Permutation returns a permutation of the set [0,n-1]
	// the theoretical output space grows very fast with (!n) so that input (n) should be chosen carefully
	// to make sure the function output space covers a big chunk of the theoretical outputs.
	// The function errors if the parameter is a negative integer.
	Permutation(n int) ([]int, error)

	// SubPermutation returns the m first elements of a permutation of [0,n-1]
	// the theoretical output space can be large (n!/(n-m)!) so that the inputs should be chosen carefully
	// to make sure the function output space covers a big chunk of the theoretical outputs.
	// The function errors if the parameter is a negative integer.
	SubPermutation(n int, m int) ([]int, error)

	// Shuffle permutes an ordered data structure of an arbitrary type in place. The main use-case is
	// permuting slice or array elements. (n) is the size of the data structure.
	// the theoretical output space grows very fast with the slice size (n!) so that input (n) should be chosen carefully
	// to make sure the function output space covers a big chunk of the theoretical outputs.
	// The function errors if any of the parameters is a negative integer.
	Shuffle(n int, swap func(i, j int)) error

	// Samples picks (m) random ordered elements of a data structure of an arbitrary type of total size (n). The (m) elements are placed
	// in the indices 0 to (m-1) with in place swapping. The data structure ends up being a permutation of the initial (n) elements.
	// While the sampling of the (m) elements is pseudo-uniformly random, there is no guarantee about the uniformity of the permutation of
	// the (n) elements. The function Shuffle should be used in case the entire (n) elements need to be shuffled.
	// The main use-case of the data structure is a slice or array.
	// The theoretical output space grows very fast with the slice size (n!/(n-m)!) so that inputs should be chosen carefully
	// to make sure the function output space covers a big chunk of the theoretical outputs.
	// The function errors if any of the parameters is a negative integer.
	Samples(n int, m int, swap func(i, j int)) error

	// Store returns the internal state of the random generator.
	// The internal state can be used as a seed input for the function
	// Restore to restore an identical PRG (with the same internal state)
	Store() []byte
}

Rand is a pseudo random number generator All methods update the internal state of the PRG which makes the PRGs implementing this interface non concurrent-safe.