drbg

Documentation

Overview

Package drbg implements several DRBGs as recommended by NIST SP-800-90A (see http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf).

The hash, HMAC and block cipher mode DRBGs are implemented.

DRBG instances are automatically reseeded once the current seed period expires.

All DRBGs are instantiated with the maximum security strength associated with the requested configuration. The security strength cannot be specified via the API.

DRBGs are instantiated by default using the platform's default entropy source (via the crypto/rand package). This entropy source can be overridden, but it must provide truly random data in order to achieve the selected security strength.

Note that prediction resistance is not implemented. Prediction resistance requires that the supplied entropy source is non-deterministic.

Index

• Variables
• type DRBG
  • func NewCTR(keyLen int, personalization []byte, entropySource io.Reader) (*DRBG, error)
  • func NewCTRWithExternalEntropy(keyLen int, entropyInput, nonce, personalization []byte, ...) (*DRBG, error)
  • func NewHMAC(h crypto.Hash, personalization []byte, entropySource io.Reader) (*DRBG, error)
  • func NewHMACWithExternalEntropy(h crypto.Hash, entropyInput, nonce, personalization []byte, ...) (*DRBG, error)
  • func NewHash(h crypto.Hash, personalization []byte, entropySource io.Reader) (*DRBG, error)
  • func NewHashWithExternalEntropy(h crypto.Hash, entropyInput, nonce, personalization []byte, ...) (*DRBG, error)
  • func (d *DRBG) Generate(additionalInput, data []byte) error
  • func (d *DRBG) Read(data []byte) (int, error)
  • func (d *DRBG) Reseed(additionalInput []byte) error
  • func (d *DRBG) ReseedWithExternalEntropy(entropyInput, additionalInput []byte) error

Variables

var ErrReseedRequired = errors.New("the DRGB must be reseeded")

ErrReseedRequired indicates that the DRBG must be reseeded before it can generate random bytes.

Types

type DRBG

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

DRBG corresponds to an instantiated DRBG based on one of the mechanisms specified in SP-800-90A.

func NewCTR

func NewCTR(keyLen int, personalization []byte, entropySource io.Reader) (*DRBG, error)

NewCTR creates a new block cipher based DRBG as specified in section 10.2 of SP-800-90A. The DRBG uses the AES block cipher.

The optional personalization argument is combined with entropy input to derive the initial seed. This argument can be used to differentiate this instantiation from others.

The optional entropySource argument allows the default entropy source (rand.Reader from the crypto/rand package) to be overridden. The supplied entropy source must be truly random.

func NewCTRWithExternalEntropy

func NewCTRWithExternalEntropy(keyLen int, entropyInput, nonce, personalization []byte, entropySource io.Reader) (*DRBG, error)

NewCTRWithExternalEntropy creates a new block cipher based DRBG as specified in section 10.2 of SP-800-90A. The DRBG uses the AES block cipher. The entropyInput and nonce arguments provide the initial entropy to seed the created DRBG.

The optional personalization argument is combined with entropy input to derive the initial seed. This argument can be used to differentiate this instantiation from others.

The optional entropySource argument provides the entropy source for future reseeding. If it is not supplied, then the DRBG can only be reseeded with externally supplied entropy. The supplied entropy source must be truly random.

func NewHMAC

func NewHMAC(h crypto.Hash, personalization []byte, entropySource io.Reader) (*DRBG, error)

NewHMAC creates a new HMAC based DRBG as specified in section 10.1.2 of SP-800-90A. The DRBG uses the supplied hash algorithm.

The optional personalization argument is combined with entropy input to derive the initial seed. This argument can be used to differentiate this instantiation from others.

The optional entropySource argument allows the default entropy source (rand.Reader from the crypto/rand package) to be overridden. The supplied entropy source must be truly random.

func NewHMACWithExternalEntropy

func NewHMACWithExternalEntropy(h crypto.Hash, entropyInput, nonce, personalization []byte, entropySource io.Reader) (*DRBG, error)

NewHMACWithExternalEntropy creates a new hash based DRBG as specified in section 10.1.2 of SP-800-90A. The DRBG uses the supplied hash algorithm. The entropyInput and nonce arguments provide the initial entropy to seed the created DRBG.

The optional personalization argument is combined with entropy input to derive the initial seed. This argument can be used to differentiate this instantiation from others.

The optional entropySource argument provides the entropy source for future reseeding. If it is not supplied, then the DRBG can only be reseeded with externally supplied entropy. The supplied entropy source must be truly random.

func NewHash

func NewHash(h crypto.Hash, personalization []byte, entropySource io.Reader) (*DRBG, error)

NewHash creates a new hash based DRBG as specified in section 10.1.1 of SP-800-90A. The DRBG uses the supplied hash algorithm.

The optional personalization argument is combined with entropy input to derive the initial seed. This argument can be used to differentiate this instantiation from others.

The optional entropySource argument allows the default entropy source (rand.Reader from the crypto/rand package) to be overridden. The supplied entropy source must be truly random.

func NewHashWithExternalEntropy

func NewHashWithExternalEntropy(h crypto.Hash, entropyInput, nonce, personalization []byte, entropySource io.Reader) (*DRBG, error)

NewHashWithExternalEntropy creates a new hash based DRBG as specified in section 10.1.1 of SP-800-90A. The DRBG uses the supplied hash algorithm. The entropyInput and nonce arguments provide the initial entropy to seed the created DRBG.

The optional personalization argument is combined with entropy input to derive the initial seed. This argument can be used to differentiate this instantiation from others.

The optional entropySource argument provides the entropy source for future reseeding. If it is not supplied, then the DRBG can only be reseeded with externally supplied entropy. The supplied entropy source must be truly random.

func (*DRBG) Generate

func (d *DRBG) Generate(additionalInput, data []byte) error

Generate will fill the supplied data buffer with random bytes.

If the DRBG needs to be reseeded before it can generate random bytes and it has been initialized with a source of entropy, the reseed operation will be performed automatically. If the DRBG hasn't been initialized with a source of entropy and it needs to be reseeded, ErrNeedsReseed will be returned.

If the length of data is greater than 65536 bytes, an error will be returned.

func (*DRBG) Read

func (d *DRBG) Read(data []byte) (int, error)

Read will read len(data) random bytes in to data.

If the DRBG needs to be reseeded in order to generate all of the random bytes and it has been initialized with a source of entropy, the reseed operation will be performed automatically. If the DRBG hasn't been initialized with a source of entropy and it needs to be reseeded, ErrNeedsReseed will be returned.

func (*DRBG) Reseed

func (d *DRBG) Reseed(additionalInput []byte) error

Reseed will reseed the DRBG with additional entropy using the entropy source it was initialized with.

func (*DRBG) ReseedWithExternalEntropy

func (d *DRBG) ReseedWithExternalEntropy(entropyInput, additionalInput []byte) error

ReseedWithExternalEntropy will reseed the DRBG with the supplied entropy.