random

README

random

Interface for random number generators.

Overview

Provides an interface for all random number generators used by lemma. Allows random number generation to be done in one place as well as faking random numbers when predictable output is required (like in tests).

The cryptographically secure pseudo-random number generator (CSPRNG) used is /dev/urandom.

Examples

Generate a n-bit random number

import (
    "fmt"

    "github.com/mailgun/lemma/random"
)

outputSize = 16 // 128 bit = 16 byte

csprng := random.CSPRNG{}

// hex-encoded random bytes
randomHexDigest, err := csprng.HexDigest(outputSize)
fmt.Printf("Random Hex Digest: %v, err: %v\n", randomHexDigest, err)

// raw bytes
randomBytes, err := csprng.Bytes(outputSize)
fmt.Printf("Random Bytes: %# x, err: %v\n", randomBytes, err)

Will print out something like the following to the console:

Random Hex Digest: 45eb93fdf5afe149ee3e61412c97e9bc, err: <nil>
Random Bytes: 0xee 0x52 0x5b 0x50 0xb9 0x10 0x3c 0x14 0x75 0x9a 0xa5 0xb9 0xa3 0xc4 0x6e 0x50, err: <nil>

Generate a fake n-bit random number

import (
    "fmt"

    "github.com/mailgun/lemma/random"
)

outputSize = 16 // 128 bit = 16 byte

fakerng := random.FakeRNG{}

// (fake) hex-encoded random bytes
fakeRandomHexDigest := fakerng.HexDigest(outputSize)
fmt.Printf("(Fake) Random Hex Digest: %v\n", fakeHexDigest)

// (fake) raw bytes
fakeRandomBytes := fakerng.Bytes(outputSize)
fmt.Printf("(Fake) Random Bytes: %# x\n", fakeRandomBytes)

Will print out the following to the console:

(Fake) Random Hex Digest: 0102030405060708090A0B0C0E0F1011
(Fake) Random Bytes: 0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f

Documentation

Index

• type CSPRNG
  • func (c *CSPRNG) Bytes(bytes int) ([]byte, error)
  • func (c *CSPRNG) HexDigest(bytes int) (string, error)
• type FakeRNG
  • func (f *FakeRNG) Bytes(bytes int) ([]byte, error)
  • func (f *FakeRNG) HexDigest(bytes int) (string, error)
• type RandomProvider
• type SeededRNG
  • func (r *SeededRNG) Bytes(bytes int) ([]byte, error)
  • func (r *SeededRNG) HexDigest(bytes int) (string, error)

Types

type CSPRNG

type CSPRNG struct{}

Real random values, used in production

func (*CSPRNG) Bytes

func (c *CSPRNG) Bytes(bytes int) ([]byte, error)

Return n-bytes of random values from the CSPRNG.

func (*CSPRNG) HexDigest

func (c *CSPRNG) HexDigest(bytes int) (string, error)

Return n-bytes of random values from the CSPRNG but as a hex-encoded (base16) string.

type FakeRNG

type FakeRNG struct{}

Fake random, used in tests. never use this in production!

func (*FakeRNG) Bytes

func (f *FakeRNG) Bytes(bytes int) ([]byte, error)

Fake random number generator, never use in production. Always returns a predictable sequence of bytes that looks like: 0x00, 0x01, 0x02, 0x03, ...

func (*FakeRNG) HexDigest

func (f *FakeRNG) HexDigest(bytes int) (string, error)

Fake random number generator, never use in production. Always returns a predictable hex-encoded (base16) string that looks like "00010203..."

type RandomProvider

type RandomProvider interface {
	Bytes(bytes int) ([]byte, error)
	HexDigest(bytes int) (string, error)
}

Interface for our random number generator. We need this to fake random values in tests.

type SeededRNG

type SeededRNG struct {
	Seed int64
	// contains filtered or unexported fields
}

SeededRNG returns bytes generated in a predictable sequence by package math/rand. Not cryptographically secure, not thread safe. Changes to Seed after the first call to Bytes or HexDigest will have no effect. The zero value of SeededRNG is ready to use, and will use a seed of 0.

func (*SeededRNG) Bytes

func (r *SeededRNG) Bytes(bytes int) ([]byte, error)

Bytes conforms to the RandomProvider interface. Returns bytes generated by a math/rand.Rand.

func (*SeededRNG) HexDigest

func (r *SeededRNG) HexDigest(bytes int) (string, error)

HexDigest conforms to the RandomProvider interface. Returns a hex encoding of bytes generated by a math/rand.Rand.