gopherng

README

gopherng

Seeded pseudorandom Reader and rand.Source

Note

This package was implemented for the purposes of the CubeDance game and may not be applicable for your purposes. It has not been independently audited for security.

Read random bytes from PseudorandomReader

This package includes a pseudorandom Reader. It initializes, based on a provided seed, an XChaCha20 stream cipher which is used to encrypt 0s in order to generate random bytes.

Internally the seed is hashed to produce a key and nonce to initialize the XChaCha20 cipher. This is not a substitute for using a sufficiently high-entropy seed or sufficiently stretching a lower-entropy seed.

// Create PseudorandomReader with a high-entropy seed.
r := gopherng.NewReader([]byte{1, 2, 3, /* ... use a high-entropy seed */})

p := make([]byte, 256)
_, err := r.Read(p)
if err != nil {
    /* ... */
}

fmt.Println(p)
// => [43 98 21 80 122 33 48 91 135 248 242 ... ]

Generate random values with PseudorandomSource

This package also includes a pseudorandom rand.Source which can be used to initialize a rand.Rand (from math/rand) like so:

// Create PseudorandomSource with a high-entropy seed.
s := gopherng.NewSource([]byte{1, 2, 3, /* ... use a high-entropy seed */})

// Create a rand.Rand from the Source.
r := rand.New(s)

fmt.Println(r.Float64())
// => 0.7124063346129034

Documentation

Index

• type PseudorandomReader
  • func NewReader(seed []byte) *PseudorandomReader
  • func (p *PseudorandomReader) Read(b []byte) (int, error)
• type PseudorandomSource
  • func NewSource(seed []byte) *PseudorandomSource
  • func (s *PseudorandomSource) Int63() int64
  • func (s *PseudorandomSource) Seed(seed int64)
  • func (s *PseudorandomSource) Uint64() uint64

Examples

• PseudorandomSource

Types

type PseudorandomReader

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

PseudorandomReader is a Reader providing seeded pseudorandom output from the keystream of an internal stream cipher.

It is not safe for concurrent use.

func NewReader

func NewReader(seed []byte) *PseudorandomReader

NewReader initializes a PseudorandomReader by initializing its internal stream cipher.

func (*PseudorandomReader) Read

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

Read reads pseudorandom bytes by calling XORKeyStream with 0s in order to produce the keystream output.

type PseudorandomSource

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

PseudorandomSource is a pseudorandom source implementing both rand.Source and rand.Source64, and can be used to initialize a rand.Rand.

Example

// Create PseudorandomSource with a seed. Use a high entropy seed in most
// real use cases.
s := gopherng.NewSource([]byte{1, 2, 3, 4, 5})

// Create a rand.Rand from the Source.
r := rand.New(s)

fmt.Println(r.Float64())
// => 0.7124063346129034

func NewSource

func NewSource(seed []byte) *PseudorandomSource

NewSource returns a new Source for the given seed. See NewReader() for seeding details.

func (*PseudorandomSource) Int63

func (s *PseudorandomSource) Int63() int64

Int63 returns an int64 from the internal PseudorandomReader.

func (*PseudorandomSource) Seed

func (s *PseudorandomSource) Seed(seed int64)

Seed exists to be compatible with rand.Source, but is not implemented and will panic if called. It should not be needed for use with rand.Rand methods.

func (*PseudorandomSource) Uint64

func (s *PseudorandomSource) Uint64() uint64

Uint64 returns a uint64 from the internal PseudorandomReader.