RdRand Library
Getting Started

For ease of use, this library is distributed with static libraries for Microsoft* Windows* and Microsoft* Visual Studio* 2010 and the Linux Ubuntu* 10.04. The library can also be built from source, and requires the Intel(r) C++ Compiler v12. See the Building section for more details.

Once the static library is compiled, it is simply a matter of linking in the library with your code and including the header in the header search path to use the library. Linking the static library is beyond the scope of this documentation, but for demonstration, a simple Microsoft* Visual Studio* project is included, named test, as well as a simple project with Makefile for Linux. Source for the test is in main.c, and the test project on Linux can uses the top-level Makefile (with target 32_test or test). The rdrand.sln solution includes the test project.

Since rdrand is a new instruction, it is only supported on the Intel(r) microarchitecture codenamed Ivy Bridge processors and beyond. It then makes sense to determine whether or not the new instruction is supported by the CPU--this is done by examining the 40th bit of the ecx register after calling cpuid. To ease use, the library automatically handles this, and stores the results internally and transparently to the end user of the library. This result is stored in global data, and is thread-safe, given that if one thread of execution supports rdrand, they all will.

The API was designed to be as simple and easy-to-use as possible, and consists of only these functions:

int rdrand_16(uint16_t* x, int retry);
int rdrand_32(uint32_t* x, int retry);
int rdrand_64(uint64_t* x, int retry);

int rdrand_get_n_64(unsigned int n, uint64_t* x);
int rdrand_get_n_32(unsigned int n, uint32_t* x);

int rdrand_get_bytes(unsigned int n, unsigned char *buffer);

Each function calls rdrand internally for a specific data-size of random data to return to the caller.

The return of these functions states the hardware was not ready (if non-retry specified), success, or that the host hardware doesn't support "rdrand" at all. Please see the define documentation for details on these defines.

Note that the data size types are exact--these are provided by a new C99 header, stdint.h. This seems to defeat the purpose of a wide-use library, so these are mocked up if C99 support isn't detected. Only Microsoft* Visual Studio* support is provided, but Intel(r) C++ Compiler and GCC 4.4.3 both natively support these C99 data types.

Copyright(C) 2012 Intel Corporation. All rights reserved.

* Other names and brands may be claimed as the property of others