fastrand

README

fastrand

go get gitlab.com/NebulousLabs/fastrand

fastrand implements a cryptographically secure pseudorandom number generator. The generator is seeded using the system's default entropy source, and thereafter produces random values via repeated hashing. As a result, fastrand can generate randomness much faster than crypto/rand, and generation cannot fail beyond a potential panic during init().

fastrand also scales better than crypto/rand and math/rand when called in parallel. In fact, fastrand can even outperform math/rand when using enough threads.

Benchmarks

// 32 byte reads
BenchmarkRead32                     	10000000	       175 ns/op	 181.86 MB/s
BenchmarkReadCrypto32               	  500000	      2733 ns/op	  11.71 MB/s

// 512 kb reads
BenchmarkRead512kb                   	    1000	   1336217 ns/op	 383.17 MB/s
BenchmarkReadCrypto512kb             	      50	  33423693 ns/op	  15.32 MB/s

// 32 byte reads using 4 threads
BenchmarkRead4Threads32               	 3000000	       392 ns/op	 326.46 MB/s
BenchmarkReadCrypto4Threads32       	  200000	      7579 ns/op	  16.89 MB/s

// 512 kb reads using 4 threads
BenchmarkRead4Threads512kb           	    1000	   1899048 ns/op	1078.43 MB/s
BenchmarkReadCrypto4Threads512kb    	      20	  97423380 ns/op	  21.02 MB/s

Security

fastrand uses an algorithm similar to Fortuna, which is the basis for the /dev/random device in FreeBSD. However, although the techniques used by fastrand are known to be secure, the specific implementation has not been reviewed by a security professional. Use with caution.

The general strategy is to use crypto/rand at init to get 32 bytes of strong entropy. From there, the entropy is concatenated to a counter and hashed repeatedly, providing 64 bytes of random output each time the counter is incremented. The counter is 16 bytes, which provides strong guarantees that a cycle will not be seen throughout the lifetime of the program.

The sync/atomic package is used to ensure that multiple threads calling fastrand concurrently are always guaranteed to end up with unique counters.

Documentation

Overview

Package fastrand implements a cryptographically secure pseudorandom number generator. The generator is seeded using the system's default entropy source, and thereafter produces random values via repeated hashing. As a result, fastrand can generate randomness much faster than crypto/rand, and generation cannot fail beyond a potential panic at init.

The method used in this package is similar to the Fortuna algorithm, which is used in used in FreeBSD for /dev/urandom. This package uses techniques that are known to be secure, however the exact implementation has not been heavily reviewed by cryptographers.

Index

• Variables
• func BigIntn(n *big.Int) *big.Int
• func Bytes(n int) []byte
• func Intn(n int) int
• func Perm(n int) []int
• func Read(b []byte)
• func Shuffle(n int, swap func(i, j int))
• func Uint64n(n uint64) uint64

Variables

var Reader *randReader

Reader is a global, shared instance of a cryptographically strong pseudo- random generator. It uses blake2b as its hashing function. Reader is safe for concurrent use by multiple goroutines.

Functions

func BigIntn

func BigIntn(n *big.Int) *big.Int

BigIntn returns a uniform random *big.Int in [0,n). It panics if n <= 0.

func Bytes

func Bytes(n int) []byte

Bytes is a helper function that returns n bytes of random data.

func Intn

func Intn(n int) int

Intn returns a uniform random int in [0,n). It panics if n <= 0.

func Perm

func Perm(n int) []int

Perm returns a random permutation of the integers [0,n).

func Read

func Read(b []byte)

Read is a helper function that calls Reader.Read on b. It always fills b completely.

func Shuffle

func Shuffle(n int, swap func(i, j int))

Shuffle randomizes the order of elements. n is the number of elements. It panics if n < 0. swap swaps the elements with indexes i and j.

func Uint64n

func Uint64n(n uint64) uint64

Uint64n returns a uniform random uint64 in [0,n). It panics if n == 0.