Documentation ¶
Overview ¶
package fortuna implements the Fortuna PRNG designed by Niels Ferguson, Bruce Schneier, and Yadayoshi Kohno. The PRNG is described in the book _Cryptography Engineering_, by the same authors (see pages 142-160). This implementation uses AES-256 and as the underlying PRF and SHA-256 as the underlying PRG.
The Fortuna type provided by this package contains the actual PRNG; clients should use one of the provided sources (or write their own) in order to add entropy to the PRNG.
The book describes an alternative implementation in which a separate accumulator thread performs the hashing; this implementation takes the standard approach.
The documentation for AddRandomEvent contains notes for writing new sources of random events to feed the PRNG.
The book also recommends that the PRNG's seed file be updated regularly; at the very least, at shutdown with an update every ten minutes recommended.
Index ¶
- Constants
- Variables
- type Fortuna
- func (rng *Fortuna) AddRandomEvent(s byte, i int, e []byte) error
- func (rng *Fortuna) AutoUpdate(filename string, shutdown chan interface{}, fsError chan error)
- func (rng *Fortuna) Initialised() bool
- func (rng *Fortuna) Read(p []byte) (int, error)
- func (rng *Fortuna) ReadSeed(p []byte) error
- func (rng *Fortuna) Seed() ([]byte, error)
- func (rng *Fortuna) UpdateSeed(filename string) error
- func (rng *Fortuna) WriteSeed(filename string) error
- type Generator
- type SourceChannel
- type SourceWriter
Constants ¶
const MaxEventSize = 32
MaxEventSize is the limit to the amount of data that can be sent in an event.
const MaxRead int = 1048576
const PoolSize = 32
PoolSize contains the number of pools used by the PRNG.
const SeedFileLength = 64
SeedFileLength is the number of bytes that should be present in the seed file.
Variables ¶
var ( MinPoolSize int64 = 48 ReseedDelay = 100 * time.Millisecond )
MinPoolSize stores the number of bytes that will trigger a reseed. The ReseedDelay prevents reseed events from occuring too quickly.
var ( ErrNotSeeded = errors.New("fortuna: PRNG not seeded yet") ErrInvalidEvent = errors.New("fortuna: invalid random event") ErrInvalidSeed = errors.New("fortuna: invalid seed") ErrNotInitialised = errors.New("fortuna: PRNG not initialised") )
var ErrReadTooLarge = errors.New("fortuna: can't provide requested number of bytes")
Functions ¶
This section is empty.
Types ¶
type Fortuna ¶
type Fortuna struct {
// contains filtered or unexported fields
}
func FromBytesSeed ¶
FromBytesSeed creates a new PRNG instance from the seed. This can be used to start an RNG on start up.
func FromSeed ¶
FromSeed creates a new PRNG instance from the seed file. This can be used to start an RNG on start up.
func New ¶
func New() *Fortuna
New sets up a new Fortuna PRNG; it is required for ensuring that the PRNG is properly initialised.
func (*Fortuna) AddRandomEvent ¶
AddRandomEvent should be called by sources to add random events to the PRNG; it takes a source identifier, a pool number, and a random event. Sources should cycle through pools, evenly distributing events over the entire set of pools; the Fortuna designers specify that this should be done "in a round-robin fashion." The choice of a source identifier is up to the host application.
func (*Fortuna) AutoUpdate ¶
AutoUpdate runs in the background, updating the PRNG's seed file every ten minutes. The shutdown channel should be closed when the PRNG is to shut down; it will automatically shutdown the PRNG and prevent any state changes. The fsError channel should be used to report errors (typically file system errors). This should never be closed by any other other means.
func (*Fortuna) Initialised ¶
Initialised returns true if the rng is initialised.
func (*Fortuna) ReadSeed ¶
ReadSeed reseeds the PRNG with a seed that is expected to have been read from a seed file.
func (*Fortuna) Seed ¶
Seed dumps a byte slice containing a seed that may be used to restore the PRNG's state.
func (*Fortuna) UpdateSeed ¶
UpdateSeed reads a seed from a file and updates the seed file with new random data.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator represents the underlying PRG used by the Fortuna PRNG.
func NewGenerator ¶
func NewGenerator() *Generator
New initialises a new Fortuna generator context. This is required to properly initialise a new generator instance.
func (*Generator) Read ¶
Read presents the generator as an io.Reader, and is used to read random data from the generator.
type SourceChannel ¶
type SourceChannel struct { In chan []byte // In receives incoming random events. Out chan error // Out sends outgoing errors. // contains filtered or unexported fields }
SourceChannel provides an interface to a PRNG that reads random events from a channel and adds them to the PRNG for entropy. The source number s should be used by the application to identify this particular source.
func NewSourceChannel ¶
func NewSourceChannel(rng *Fortuna, source byte) *SourceChannel
NewSourceChannel initialises a new channel source. This is required to properly initialise one. The source parameter should contain the source number. The rng must already be initialised, and the channel source must be started before it can be used.
func (*SourceChannel) Start ¶
func (cs *SourceChannel) Start(buf int)
Start the channel source, setting up the channel sender and receiver.
func (*SourceChannel) Stop ¶
func (cs *SourceChannel) Stop()
Stop halts the channel source, closing the channels.
type SourceWriter ¶
type SourceWriter struct {
// contains filtered or unexported fields
}
SourceWriter provides an io.Writer source for adding events to the PRNG.
func NewSourceWriter ¶
func NewSourceWriter(rng *Fortuna, source byte) *SourceWriter
NewSourceWriter intialises a new io.Writer source. This is required to properly intialise the source. The PRNG provided must already be initialised; the source parameter is used to identify the source to the host system.