1man(3) librdrand man page man(3)
2
6 librdrand - Library for generating random values by using RdRand on
7 Intel's CPUs.
8
10 #include <librdrand.h>
11 int rdrand_testSupport();
13 int rdrand16_step(uint16_t *x);
15 int rdrand32_step(uint32_t *x);
16 int rdrand64_step(uint64_t *x);
17 int rdrand_get_uint16_retry(uint16_t *dest, int retry_limit);
20 int rdrand_get_uint32_retry(uint32_t *dest, int retry_limit);
21 int rdrand_get_uint64_retry(uint64_t *dest, int retry_limit);
22 unsigned int rdrand_get_uint8_array_retry(uint8_t *dest, const
25 unsigned int count, int retry_limit);
26 unsigned int rdrand_get_uint16_array_retry(uint16_t *dest, const
27 unsigned int count, int retry_limit);
28 unsigned int rdrand_get_uint32_array_retry(uint32_t *dest, const
29 unsigned int count, int retry_limit);
30 unsigned int rdrand_get_uint64_array_retry(uint64_t *dest, const
31 unsigned int count, int retry_limit);
32 size_t rdrand_get_bytes_retry(void *dest, const size_t size, int
34 retry_limit);
35 unsigned int rdrand_get_uint64_array_reseed_delay(uint64_t *dest, const
37 unsigned int count, int retry_limit);
38 unsigned int rdrand_get_uint64_array_reseed_skip(uint64_t *dest, const
39 unsigned int count, int retry_limit);
40 size_t rdrand_fwrite(FILE *f, const size_t count, int retry_limit);
42
46 The rdrand-lib is a library for generating random values on Intel CPUs
47 (Ivy Bridge and newers) using the HW RNG on the CPU. As the HW RNG is
48 only on newer Intel CPUs, the library contain rdrand_testSupport()
49 function for testing the availability. Return values are RDRAND_SUP‐
50 PORTED or RDRAND_UNSUPPORTED.
51 All generating functions saves the random values to the location speci‐
53 fied in *dest/*x pointer, the value is never returned directly.
54 The rdrandXX_step() functions are just a wrappers, shileding the user
56 from the using of ASM instruction. These functions returns RDRAND_SUC‐
57 CESS if the random 16, 32 or 64-bit value was sucessfuly saved into
58 given pointer, or RDRAND_FAILURE if it wasn't. Note, that on current
59 CPUs (this may change in future CPUs), the CPU always take 64-bit value
60 and throw away the unused part.
61 The rdrand_get_uintXX_retry() functions works similar to rdrandXX_step,
63 but uses one aditional parameter retry_limit. Returns RDRAND_SUCCESS
64 or RDRAND_FAILURE.
65 The retry_limit argument, same also for all the following functions,
67 means that the function will try up to the given number to repeat the
68 generating if for some reason the HW RNG will not generate anything
69 (for example because it was sucked dry and needs to refill its inner
70 pool). If a negative value is passed, the function will use default
71 value with which the library was compiled.
72 The set of rdrand_get_uintXX_array_retry() functions fills an array on
74 dest of specified length count of XX-bits values by randomness. Returns
75 number of bytes sucessfuly acquired.
76 rdrand_get_bytes_retry() function is almost the same as
78 rdrand_get_uint8_array_retry(), but with benefit of memory-alignment.
79 That means, in most situations, there is almost no difference between
80 rdrand_get_bytes_retry() and rdrand_get_uintXX_array_retry() functions,
81 but if the filled area is not correctly aligned in memory, the
82 rdrand_get_bytes_retry() offers the best performance.
83 The two reseed functions ( rdrand_get_uint64_array_reseed_delay() and
85 rdrand_get_uint64_array_reseed_skip()) are forcing the reseed of the
86 internal HW RNG so each single generated 64-bit value is guaranteed to
87 be generated with differend seed of Intel RdRand's internal PRNG. The
88 difference between these two functions is in approach:
89 rdrand_get_uint64_array_reseed_skip() is returning just one from each
90 1025 64-bits values (size of the inner pool is 1024 of such).
91 rdrand_get_uint64_array_reseed_delay() is inserting small delays (20
92 microseconds) between each call, long enough so according of Intel, the
93 inner pool should fully regenerate. Unfortunately, because the HW
94 implementation is closed, it is not possible to verify, if these two
95 functions trully works like intended.
96 The last rdrand_fwrite() function directly writes count bytes of ran‐
98 domness to the *f file descriptor.
99
102 /*
103 gcc -Wall -Wextra -mrdrnd -O2 -std=gnu99 -o simple_example simple_exam‐
104 ple.c -lrdrand
105 */
106 #include <stdlib.h>
108 #include <librdrand.h>
109 int main (void) {
111 // count of random numbers
112 const size_t N = 10;
113 unsigned int buf;
114 // test for support
115 if (!rdrand_testSupport()) {
116 fprintf(stderr,"RdRand is not supported on this CPU!\n");
117 return 1;
118 }
119 // generate and print the numbers
120 for(size_t i=0; i<N; i++){
121 // generate the number and save it to the buffer
122 rdrand32_step ( &buf );
123 // print it in hexadecimal form
124 printf("%08X\n",buf);
125 }
126 return 0;
127 }
128
131 rdrand-gen(7) librdrand-aes(3)
132
135 No known bugs.
136
139 Jan Tulak (jan@tulak.me) Jiri Hladky (hladky.jiri@gmail.com)
1401.2 24 April 2014 man(3)