1/** @file
2  Random number generator services that uses RdRand instruction access
3  to provide high-quality random numbers.
4
5Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
6This program and the accompanying materials
7are licensed and made available under the terms and conditions of the BSD License
8which accompanies this distribution.  The full text of the license may be found at
9http://opensource.org/licenses/bsd-license.php
10
11THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12WITHOUT 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**/
42RETURN_STATUS
43EFIAPI
44BaseRngLibConstructor (
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**/
71BOOLEAN
72EFIAPI
73GetRandomNumber16 (
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**/
104BOOLEAN
105EFIAPI
106GetRandomNumber32 (
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**/
137BOOLEAN
138EFIAPI
139GetRandomNumber64 (
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**/
170BOOLEAN
171EFIAPI
172GetRandomNumber128 (
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