Documentation for the rdrand python module

What is rdrand?

RdRand is a Python module that provides an easily used interface to the random number generator provided by Intel (and some Amd) processors. The rdrand and rdseed assembly instructions are used to generated random numbers, which are then fed into a subclass of the standard Random class of the random module. This provides a cryptograpically strong random number generator with a familiar interface. Code that uses random.Random can be easily replace with a much stronger random number generator.

RdRandom

rdrand.RdRandom is a class that works exactly like random.Random See Python2_Random or Python3_Random for a description of random.Random

import rdrand

r = rdrand.RdRandom()

r.randint(10) …

RdRandom uses the rdrand assembly instruction as the basis for its random numbers.

The only differences between RdRandom and Random are the following functions:

seed() and jumpahead()
always returns None
getstate() and setstate()
raises an exception
getrandbytes(num_bytes)
Returns a string/bytes byte_count long of random bytes.

RdSeedom

RdSeedom work just like RdRandom, but uses the rdseed instruction.

Special Methods and Variables

rdrand.HAS_RAND
This variable is 1 if the CPU supports the rdrand instruction, 0 if it doesn’t.
rdrand.HAS_SEED
This variable is 1 if the CPU supports the rdseed instruction, 0 if it doesn’t.
rdrand.rdrand_get_bits(bit_count)
Returns a long with bit_count bits of randomness. Uses the rdrand instruction.
rdrand.rdrand_get_bytes(byte_count)
Returns a string/bytes byte_count long of random bytes. Uses the rdseed instruction.
rdrand.rdseed_get_bits(bit_count)
Returns a long with bit_count bits of randomness. Uses the rdseed instruction.
rdrand.rdseed_get_bytes(byte_count)
Returns a string/bytes byte_count long of random bytes. Uses the rdseed instruction.

Cryptographic Use

For general use and keys with a relatively short lifetime, RdRandom or rdrand.rdrand_get_byte() will provide a decent amount of entropy.

import rdrand

r = rdrand.RdRandom()

key = r.getrandbytes(16)

This will generate a 128 bit key.

For longer keys that may need to last longer (years, decades), you can use RdSeedom

import rdrand

s = rdrand.RdSeedom()

key = s.getrandbytes(32)

This will produce a 256 bit key, which should be completely unrelated to any previous or future keys.

Warnings

I am not a cryptographer.

RdRand can be subverted by an attacker who controls a machine.

Use at your own risk.

Also, RdRand is not as fast as default random number generator. It is faster than other cryptographically secure random number generators, but if you don’t need cryptographically secure random numbers it’s probably overkill.

Indices and tables