librdrand - Man Page

#include <librdrand.h>

int rdrand_testSupport();

int rdrand16_step(uint16_t *x);
int rdrand32_step(uint32_t *x);
int rdrand64_step(uint64_t *x);

int rdrand_get_uint16_retry(uint16_t *dest, int retry_limit);
int rdrand_get_uint32_retry(uint32_t *dest, int retry_limit);
int rdrand_get_uint64_retry(uint64_t *dest, int retry_limit);

unsigned int rdrand_get_uint8_array_retry(uint8_t *dest,  const unsigned int count, int retry_limit);
unsigned int rdrand_get_uint16_array_retry(uint16_t *dest, const unsigned int count, int retry_limit);
unsigned int rdrand_get_uint32_array_retry(uint32_t *dest, const unsigned int count, int retry_limit);
unsigned int rdrand_get_uint64_array_retry(uint64_t *dest, const unsigned int count, int retry_limit);

size_t rdrand_get_bytes_retry(void *dest, const size_t size, int retry_limit);

unsigned int rdrand_get_uint64_array_reseed_delay(uint64_t *dest, const unsigned int count, int retry_limit);
unsigned int rdrand_get_uint64_array_reseed_skip(uint64_t *dest, const unsigned int count, int retry_limit);

size_t rdrand_fwrite(FILE *f, const size_t count, int retry_limit);

The rdrand-lib is a library for generating random values on Intel CPUs (Ivy Bridge and newers) using the HW RNG on the CPU. As the HW RNG is only on newer Intel CPUs, the library contain rdrand_testSupport() function for testing the availability. Return values are RDRAND_SUPPORTED or RDRAND_UNSUPPORTED.

All generating functions saves the random values to the location specified in *dest/*x pointer, the value is never returned directly.

The rdrandXX_step() functions are just a wrappers, shileding the user from the using of ASM instruction. These functions returns RDRAND_SUCCESS if the random 16, 32 or 64-bit value was sucessfuly saved into given pointer, or RDRAND_FAILURE if it wasn't. Note, that on current CPUs (this may change in future CPUs), the CPU always take 64-bit value and throw away the unused part.

The rdrand_get_uintXX_retry() functions works similar to rdrandXX_step, but uses one aditional parameter retry_limit. Returns RDRAND_SUCCESS or RDRAND_FAILURE.

The retry_limit argument, same also for all the following functions, means that the function will try up to the given number to repeat the generating if for some reason the HW RNG will not generate anything (for example because it was sucked dry and needs to refill its inner pool). If a negative value is passed, the function will use default value with which the library was compiled.

The set of rdrand_get_uintXX_array_retry() functions fills an array on dest of specified length count of XX-bits values by randomness. Returns number of bytes sucessfuly acquired.

rdrand_get_bytes_retry() function is almost the same as rdrand_get_uint8_array_retry(), but with benefit of memory-alignment. That means, in most situations, there is almost no difference between rdrand_get_bytes_retry() and rdrand_get_uintXX_array_retry() functions, but if the filled area is not correctly aligned in memory, the rdrand_get_bytes_retry() offers the best performance.

The two reseed functions ( rdrand_get_uint64_array_reseed_delay() and rdrand_get_uint64_array_reseed_skip()) are forcing the reseed of the internal HW RNG so each single generated 64-bit value is guaranteed to be generated with differend seed of Intel RdRand's internal PRNG. The difference between these two functions is in approach: rdrand_get_uint64_array_reseed_skip() is returning just one from each 1025 64-bits values (size of the inner pool is 1024 of such). rdrand_get_uint64_array_reseed_delay() is inserting small delays (20 microseconds) between each call, long enough so according of Intel, the inner pool should fully regenerate. Unfortunately, because the HW implementation is closed, it is not possible to verify, if these two functions trully works like intended.

The last rdrand_fwrite() function directly writes count bytes of randomness to the *f file descriptor.

/*
gcc -Wall -Wextra -mrdrnd -O2 -std=gnu99 -o simple_example simple_example.c -lrdrand
*/

#include <stdlib.h>
#include <librdrand.h>

int main (void) {
  // count of random numbers
  const size_t N = 10;
  unsigned int buf;
  // test for support
  if (!rdrand_testSupport()) {
    fprintf(stderr,"RdRand is not supported on this CPU!\n");
    return 1;
  }
  // generate and print the numbers
  for(size_t i=0; i<N; i++){
     // generate the number and save it to the buffer
     rdrand32_step ( &buf );
     // print it in hexadecimal form
     printf("%08X\n",buf);
  }
  return 0;
}

rdrand-gen(7) librdrand-aes(3)

No known bugs.

Jan Tulak (jan@tulak.me) Jiri Hladky (hladky.jiri@gmail.com)

rdrand-gen(7).