fastrand

package module
v0.0.0-...-603482d Latest Latest
Warning

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

Go to latest
Published: Nov 26, 2018 License: MIT Imports: 8 Imported by: 236

README

fastrand

GoDoc Go Report Card

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

Constants

This section is empty.

Variables

View Source
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.

Types

This section is empty.

Jump to

Keyboard shortcuts

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