SecurityPkg/RandomNumberGenerator/RngDxe/RdRand.h

   1 /** @file
   2   Header for the RDRAND APIs used by RNG DXE driver.
   3
   4   Support API definitions for RDRAND instruction access, which will leverage
   5   Intel Secure Key technology to provide high-quality random numbers for use
   6   in applications, or entropy for seeding other random number generators.
   7   Refer to http://software.intel.com/en-us/articles/intel-digital-random-number
   8   -generator-drng-software-implementation-guide/ for more information about Intel
   9   Secure Key technology.
  10
  11 Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
  12 This program and the accompanying materials
  13 are licensed and made available under the terms and conditions of the BSD License
  14 which accompanies this distribution.  The full text of the license may be found at
  15 http://opensource.org/licenses/bsd-license.php
  16
  17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  19
  20 **/
  21
  22 #ifndef __RD_RAND_H__
  23 #define __RD_RAND_H__
  24
  25 #include <Library/BaseLib.h>
  26 #include <Library/BaseMemoryLib.h>
  27 #include <Library/UefiBootServicesTableLib.h>
  28 #include <Library/TimerLib.h>
  29 #include <Protocol/Rng.h>
  30
  31 //
  32 // The maximun number of retries to obtain one available random number.
  33 //
  34 #define RETRY_LIMIT    10
  35
  36 /**
  37   Determines whether or not RDRAND instruction is supported by the host hardware.
  38
  39   @retval EFI_SUCCESS          RDRAND instruction supported.
  40   @retval EFI_UNSUPPORTED      RDRAND instruction not supported.
  41
  42 **/
  43 EFI_STATUS
  44 EFIAPI
  45 IsRdRandSupported (
  46   VOID
  47   );
  48
  49 /**
  50   Generates a 16-bit random number through RDRAND instruction.
  51
  52   @param[out]  Rand          Buffer pointer to store the random result.
  53
  54   @retval TRUE               RDRAND call was successful.
  55   @retval FALSE              Failed attempts to call RDRAND.
  56
  57 **/
  58 BOOLEAN
  59 EFIAPI
  60 RdRand16Step (
  61   OUT UINT16       *Rand
  62   );
  63
  64 /**
  65   Generates a 32-bit random number through RDRAND instruction.
  66
  67   @param[out]  Rand          Buffer pointer to store the random result.
  68
  69   @retval TRUE               RDRAND call was successful.
  70   @retval FALSE              Failed attempts to call RDRAND.
  71
  72 **/
  73 BOOLEAN
  74 EFIAPI
  75 RdRand32Step (
  76   OUT UINT32       *Rand
  77   );
  78
  79 /**
  80   Generates a 64-bit random number through RDRAND instruction.
  81
  82   @param[out]  Rand          Buffer pointer to store the random result.
  83
  84   @retval TRUE               RDRAND call was successful.
  85   @retval FALSE              Failed attempts to call RDRAND.
  86
  87 **/
  88 BOOLEAN
  89 EFIAPI
  90 RdRand64Step  (
  91   OUT UINT64   *Rand
  92   );
  93
  94 /**
  95   Calls RDRAND to obtain a 16-bit random number.
  96
  97   @param[out]  Rand          Buffer pointer to store the random result.
  98   @param[in]   NeedRetry     Determine whether or not to loop retry.
  99
 100   @retval EFI_SUCCESS        RDRAND call was successful.
 101   @retval EFI_NOT_READY      Failed attempts to call RDRAND.
 102
 103 **/
 104 EFI_STATUS
 105 EFIAPI
 106 RdRand16 (
 107   OUT UINT16       *Rand,
 108   IN BOOLEAN       NeedRetry
 109   );
 110
 111 /**
 112   Calls RDRAND to obtain a 32-bit random number.
 113
 114   @param[out]  Rand          Buffer pointer to store the random result.
 115   @param[in]   NeedRetry     Determine whether or not to loop retry.
 116
 117   @retval EFI_SUCCESS        RDRAND call was successful.
 118   @retval EFI_NOT_READY      Failed attempts to call RDRAND.
 119
 120 **/
 121 EFI_STATUS
 122 EFIAPI
 123 RdRand32 (
 124   OUT UINT32       *Rand,
 125   IN BOOLEAN       NeedRetry
 126   );
 127
 128 /**
 129   Calls RDRAND to obtain a 64-bit random number.
 130
 131   @param[out]  Rand          Buffer pointer to store the random result.
 132   @param[in]   NeedRetry     Determine whether or not to loop retry.
 133
 134   @retval EFI_SUCCESS        RDRAND call was successful.
 135   @retval EFI_NOT_READY      Failed attempts to call RDRAND.
 136
 137 **/
 138 EFI_STATUS
 139 EFIAPI
 140 RdRand64 (
 141   OUT UINT64       *Rand,
 142   IN BOOLEAN       NeedRetry
 143   );
 144
 145 /**
 146   Calls RDRAND to request a word-length random number.
 147
 148   @param[out]  Rand          Buffer pointer to store the random number.
 149   @param[in]   NeedRetry     Determine whether or not to loop retry.
 150
 151   @retval EFI_SUCCESS        Random word generation succeeded.
 152   @retval EFI_NOT_READY      Failed to request random word.
 153
 154 **/
 155 EFI_STATUS
 156 EFIAPI
 157 RdRandWord (
 158   OUT UINTN        *Rand,
 159   IN BOOLEAN       NeedRetry
 160   );
 161
 162 /**
 163   Calls RDRAND to request multiple word-length random numbers.
 164
 165   @param[in]   Length        Size of the buffer, in words, to fill with.
 166   @param[out]  RandBuffer    Pointer to the buffer to store the random result.
 167
 168   @retval EFI_SUCCESS        Random words generation succeeded.
 169   @retval EFI_NOT_READY      Failed to request random words.
 170
 171 **/
 172 EFI_STATUS
 173 EFIAPI
 174 RdRandGetWords (
 175   IN UINTN         Length,
 176   OUT UINTN        *RandBuffer
 177   );
 178
 179 /**
 180   Calls RDRAND to fill a buffer of arbitrary size with random bytes.
 181
 182   @param[in]   Length        Size of the buffer, in bytes,  to fill with.
 183   @param[out]  RandBuffer    Pointer to the buffer to store the random result.
 184
 185   @retval EFI_SUCCESS        Random bytes generation succeeded.
 186   @retval EFI_NOT_READY      Failed to request random bytes.
 187
 188 **/
 189 EFI_STATUS
 190 EFIAPI
 191 RdRandGetBytes (
 192   IN UINTN         Length,
 193   OUT UINT8        *RandBuffer
 194   );
 195
 196 /**
 197   Generate high-quality entropy source through RDRAND.
 198
 199   @param[in]   Length        Size of the buffer, in bytes, to fill with.
 200   @param[out]  Entropy       Pointer to the buffer to store the entropy data.
 201
 202   @retval EFI_SUCCESS        Entropy generation succeeded.
 203   @retval EFI_NOT_READY      Failed to request random data.
 204
 205 **/
 206 EFI_STATUS
 207 EFIAPI
 208 RdRandGenerateEntropy (
 209   IN UINTN         Length,
 210   OUT UINT8        *Entropy
 211   );
 212
 213 #endif  // __RD_RAND_H__