1 /** @file
2 Random number generator services that uses RdRand instruction access
3 to provide high-quality random numbers.
4
5 Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
10
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14 **/
15
16 #include <Library/BaseLib.h>
17 #include <Library/DebugLib.h>
18
19 //
20 // Bit mask used to determine if RdRand instruction is supported.
21 //
22 #define RDRAND_MASK BIT30
23
24 //
25 // Limited retry number when valid random data is returned.
26 // Uses the recommended value defined in Section 7.3.17 of "Intel 64 and IA-32
27 // Architectures Software Developer's Mannual".
28 //
29 #define RDRAND_RETRY_LIMIT 10
30
31 /**
32 The constructor function checks whether or not RDRAND instruction is supported
33 by the host hardware.
34
35 The constructor function checks whether or not RDRAND instruction is supported.
36 It will ASSERT() if RDRAND instruction is not supported.
37 It will always return RETURN_SUCCESS.
38
39 @retval RETURN_SUCCESS The constructor always returns EFI_SUCCESS.
40
41 **/
42 RETURN_STATUS
43 EFIAPI
BaseRngLibConstructor(VOID)44 BaseRngLibConstructor (
45 VOID
46 )
47 {
48 UINT32 RegEcx;
49
50 //
51 // Determine RDRAND support by examining bit 30 of the ECX register returned by
52 // CPUID. A value of 1 indicates that processor support RDRAND instruction.
53 //
54 AsmCpuid (1, 0, 0, &RegEcx, 0);
55 ASSERT ((RegEcx & RDRAND_MASK) == RDRAND_MASK);
56
57 return RETURN_SUCCESS;
58 }
59
60 /**
61 Generates a 16-bit random number.
62
63 if Rand is NULL, then ASSERT().
64
65 @param[out] Rand Buffer pointer to store the 16-bit random value.
66
67 @retval TRUE Random number generated successfully.
68 @retval FALSE Failed to generate the random number.
69
70 **/
71 BOOLEAN
72 EFIAPI
GetRandomNumber16(OUT UINT16 * Rand)73 GetRandomNumber16 (
74 OUT UINT16 *Rand
75 )
76 {
77 UINT32 Index;
78
79 ASSERT (Rand != NULL);
80
81 //
82 // A loop to fetch a 16 bit random value with a retry count limit.
83 //
84 for (Index = 0; Index < RDRAND_RETRY_LIMIT; Index++) {
85 if (AsmRdRand16 (Rand)) {
86 return TRUE;
87 }
88 }
89
90 return FALSE;
91 }
92
93 /**
94 Generates a 32-bit random number.
95
96 if Rand is NULL, then ASSERT().
97
98 @param[out] Rand Buffer pointer to store the 32-bit random value.
99
100 @retval TRUE Random number generated successfully.
101 @retval FALSE Failed to generate the random number.
102
103 **/
104 BOOLEAN
105 EFIAPI
GetRandomNumber32(OUT UINT32 * Rand)106 GetRandomNumber32 (
107 OUT UINT32 *Rand
108 )
109 {
110 UINT32 Index;
111
112 ASSERT (Rand != NULL);
113
114 //
115 // A loop to fetch a 32 bit random value with a retry count limit.
116 //
117 for (Index = 0; Index < RDRAND_RETRY_LIMIT; Index++) {
118 if (AsmRdRand32 (Rand)) {
119 return TRUE;
120 }
121 }
122
123 return FALSE;
124 }
125
126 /**
127 Generates a 64-bit random number.
128
129 if Rand is NULL, then ASSERT().
130
131 @param[out] Rand Buffer pointer to store the 64-bit random value.
132
133 @retval TRUE Random number generated successfully.
134 @retval FALSE Failed to generate the random number.
135
136 **/
137 BOOLEAN
138 EFIAPI
GetRandomNumber64(OUT UINT64 * Rand)139 GetRandomNumber64 (
140 OUT UINT64 *Rand
141 )
142 {
143 UINT32 Index;
144
145 ASSERT (Rand != NULL);
146
147 //
148 // A loop to fetch a 64 bit random value with a retry count limit.
149 //
150 for (Index = 0; Index < RDRAND_RETRY_LIMIT; Index++) {
151 if (AsmRdRand64 (Rand)) {
152 return TRUE;
153 }
154 }
155
156 return FALSE;
157 }
158
159 /**
160 Generates a 128-bit random number.
161
162 if Rand is NULL, then ASSERT().
163
164 @param[out] Rand Buffer pointer to store the 128-bit random value.
165
166 @retval TRUE Random number generated successfully.
167 @retval FALSE Failed to generate the random number.
168
169 **/
170 BOOLEAN
171 EFIAPI
GetRandomNumber128(OUT UINT64 * Rand)172 GetRandomNumber128 (
173 OUT UINT64 *Rand
174 )
175 {
176 ASSERT (Rand != NULL);
177
178 //
179 // Read first 64 bits
180 //
181 if (!GetRandomNumber64 (Rand)) {
182 return FALSE;
183 }
184
185 //
186 // Read second 64 bits
187 //
188 return GetRandomNumber64 (++Rand);
189 }
190