Pseudo-Random Number Generators (PRNGs)

Overview

>>> from tomcrypt import prng

This module contains a PRNG class which contains all state required for a PRNG, and a convenience function for every PRNG provided:

>>> myrng = prng.PRNG('yarrow')
>>> # OR
>>> myrng = prng.yarrow()

The module also contains a list of the names of all PRNGs provided:

>>> sorted(prng.names)
['fortuna', 'rc4', 'sober128', 'sprng', 'yarrow']

You can add entropy via the PRNG.add_entropy() method:

>>> myrng = prng.yarrow()
>>> myrng.add_entropy('hello')
>>> myrng.read(8).encode('hex')
b'f34a113448ead699'

You can use the system PRNG (eg. /dev/urandom) to auto-seed your PRNG, either at construction or any time afterwards:

>>> # Seed with 1024 bytes from system PRNG.
>>> myrng = prng.yarrow(1024)
>>> myrng.read(8).encode('hex')
<will always be different>
>>> # Add another 1024 bytes from system PRNG.
>>> myrng.auto_seed(1024)
>>> myrng.read(8).encode('hex')
<will always be different>

The system PRNG is also directly available via the same API as the "sprng" object.

PRNG API

class tomcrypt.prng.PRNG

A pseudo-random number generator.

Generates streams of pseudo-random bytes. Must be seeded, but can be auto-seeded from the operating system (e.g. /dev/urandom on *nix).

See tomcrypt.prng.names for a list of availible PRNG names.

>>> list(sorted(names))
['fortuna', 'rc4', 'sober128', 'sprng', 'yarrow']

>>> # Manual seeding:
>>> myprng = PRNG('yarrow') # or yarrow()
>>> myprng.add_entropy(b'from a random oracle')
>>> len(myprng.read(8))
8

>>> # Auto-seeding (with 1KB of data from the system PRNG):
>>> myprng = PRNG('yarrow', 1024)
>>> len(myprng.read(8))
8

add_entropy()

Stir in some bytes to the entropy pool.

Some PRNGs have length restrictions on entropy. “fortuna”, for instance will only accept 32 bytes.

>>> myrng = yarrow()
>>> myrng.add_entropy(b'from a random oracle')
>>> myrng.read(8)
b'\xa5\x0f\xc3\x84\xd9\xb1LK'

auto_seed()

Seed this PRNG from the system PRNG.

>>> myrng = yarrow()
>>> myrng.auto_seed(1024) # 1KB of random data.

export_size

The size of the output of the PRNG.get_state() method.

>>> yarrow().export_size
64

get_state()

Get the internal entropy pool, restored with PRNG.set_state(...).

Note that when restored, the PRNG will not read out the same bits as it would have before. It only maintains the amount of entropy in the pool.

Two PRNGs set to the same state should, however, produce the same data.

>>> a = yarrow()
>>> a.add_entropy(b'from a random oracle')
>>> state = a.get_state()
>>> b = yarrow()
>>> b.set_state(state)
>>> len(b.read(8))
8

name

The name of the PRNG.

>>> yarrow().name
'yarrow'
>>> fortuna().name
'fortuna'
>>> sprng().name
'sprng'

read()

Retrieve binary data from the PRNG.

set_state()

Seed from an old entropy pool.

See PRNG.get_state() for an example.

tomcrypt.prng.test_library()

Run internal libtomcrypt prng tests.

>>> test_library()
True