SecurityPkg/RandomNumberGenerator/RngDxe/RngDxe.c

   1 /** @file
   2   RNG Driver to produce the UEFI Random Number Generator protocol.
   3
   4   The driver will use the new RDRAND instruction to produce high-quality, high-performance
   5   entropy and random number.
   6
   7   RNG Algoritnms defined in UEFI 2.4:
   8    - EFI_RNG_ALGORITHM_SP800_90_CTR_256_GUID  - Supported
   9      (RDRAND implements a hardware NIST SP800-90 AES-CTR-256 based DRBG)
  10    - EFI_RNG_ALGORITHM_RAW                    - Supported
  11      (Structuring RDRAND invocation can be guaranteed as high-quality entropy source)
  12    - EFI_RNG_ALGORITHM_SP800_90_HMAC_256_GUID - Unsupported
  13    - EFI_RNG_ALGORITHM_SP800_90_HASH_256_GUID - Unsupported
  14    - EFI_RNG_ALGORITHM_X9_31_3DES_GUID        - Unsupported
  15    - EFI_RNG_ALGORITHM_X9_31_AES_GUID         - Unsupported
  16
  17 Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
  18 This program and the accompanying materials
  19 are licensed and made available under the terms and conditions of the BSD License
  20 which accompanies this distribution.  The full text of the license may be found at
  21 http://opensource.org/licenses/bsd-license.php
  22
  23 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  24 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  25
  26 **/
  27
  28 #include "RdRand.h"
  29
  30 //
  31 // Supported RNG Algorithms list by this driver.
  32 //
  33 EFI_RNG_ALGORITHM mSupportedRngAlgorithms[] = {
  34   EFI_RNG_ALGORITHM_SP800_90_CTR_256_GUID,
  35   EFI_RNG_ALGORITHM_RAW
  36 };
  37
  38 /**
  39   Returns information about the random number generation implementation.
  40
  41   @param[in]     This                 A pointer to the EFI_RNG_PROTOCOL instance.
  42   @param[in,out] RNGAlgorithmListSize On input, the size in bytes of RNGAlgorithmList.
  43                                       On output with a return code of EFI_SUCCESS, the size
  44                                       in bytes of the data returned in RNGAlgorithmList. On output
  45                                       with a return code of EFI_BUFFER_TOO_SMALL,
  46                                       the size of RNGAlgorithmList required to obtain the list.
  47   @param[out] RNGAlgorithmList        A caller-allocated memory buffer filled by the driver
  48                                       with one EFI_RNG_ALGORITHM element for each supported
  49                                       RNG algorithm. The list must not change across multiple
  50                                       calls to the same driver. The first algorithm in the list
  51                                       is the default algorithm for the driver.
  52
  53   @retval EFI_SUCCESS                 The RNG algorithm list was returned successfully.
  54   @retval EFI_UNSUPPORTED             The services is not supported by this driver.
  55   @retval EFI_DEVICE_ERROR            The list of algorithms could not be retrieved due to a
  56                                       hardware or firmware error.
  57   @retval EFI_INVALID_PARAMETER       One or more of the parameters are incorrect.
  58   @retval EFI_BUFFER_TOO_SMALL        The buffer RNGAlgorithmList is too small to hold the result.
  59
  60 **/
  61 EFI_STATUS
  62 EFIAPI
  63 RngGetInfo (
  64   IN EFI_RNG_PROTOCOL             *This,
  65   IN OUT UINTN                    *RNGAlgorithmListSize,
  66   OUT EFI_RNG_ALGORITHM           *RNGAlgorithmList
  67   )
  68 {
  69   EFI_STATUS    Status;
  70   UINTN         RequiredSize;
  71
  72   if ((This == NULL) || (RNGAlgorithmListSize == NULL)) {
  73     return EFI_INVALID_PARAMETER;
  74   }
  75
  76   RequiredSize = sizeof (mSupportedRngAlgorithms);
  77   if (*RNGAlgorithmListSize < RequiredSize) {
  78     Status = EFI_BUFFER_TOO_SMALL;
  79   } else {
  80     //
  81     // Return algorithm list supported by driver.
  82     //
  83     if (RNGAlgorithmList != NULL) {
  84       CopyMem (RNGAlgorithmList, mSupportedRngAlgorithms, RequiredSize);
  85       Status = EFI_SUCCESS;
  86     } else {
  87       Status = EFI_INVALID_PARAMETER;
  88     }
  89   }
  90   *RNGAlgorithmListSize = RequiredSize;
  91
  92   return Status;
  93 }
  94
  95 /**
  96   Produces and returns an RNG value using either the default or specified RNG algorithm.
  97
  98   @param[in]  This                    A pointer to the EFI_RNG_PROTOCOL instance.
  99   @param[in]  RNGAlgorithm            A pointer to the EFI_RNG_ALGORITHM that identifies the RNG
 100                                       algorithm to use. May be NULL in which case the function will
 101                                       use its default RNG algorithm.
 102   @param[in]  RNGValueLength          The length in bytes of the memory buffer pointed to by
 103                                       RNGValue. The driver shall return exactly this numbers of bytes.
 104   @param[out] RNGValue                A caller-allocated memory buffer filled by the driver with the
 105                                       resulting RNG value.
 106
 107   @retval EFI_SUCCESS                 The RNG value was returned successfully.
 108   @retval EFI_UNSUPPORTED             The algorithm specified by RNGAlgorithm is not supported by
 109                                       this driver.
 110   @retval EFI_DEVICE_ERROR            An RNG value could not be retrieved due to a hardware or
 111                                       firmware error.
 112   @retval EFI_NOT_READY               There is not enough random data available to satisfy the length
 113                                       requested by RNGValueLength.
 114   @retval EFI_INVALID_PARAMETER       RNGValue is NULL or RNGValueLength is zero.
 115
 116 **/
 117 EFI_STATUS
 118 EFIAPI
 119 RngGetRNG (
 120   IN EFI_RNG_PROTOCOL            *This,
 121   IN EFI_RNG_ALGORITHM           *RNGAlgorithm, OPTIONAL
 122   IN UINTN                       RNGValueLength,
 123   OUT UINT8                      *RNGValue
 124   )
 125 {
 126   EFI_STATUS    Status;
 127
 128   if ((RNGValueLength == 0) || (RNGValue == NULL)) {
 129     return EFI_INVALID_PARAMETER;
 130   }
 131
 132   Status = EFI_UNSUPPORTED;
 133   if (RNGAlgorithm == NULL) {
 134     //
 135     // Use the default RNG algorithm if RNGAlgorithm is NULL.
 136     //
 137     RNGAlgorithm = &gEfiRngAlgorithmSp80090Ctr256Guid;
 138   }
 139
 140   //
 141   // NIST SP800-90-AES-CTR-256 supported by RDRAND
 142   //
 143   if (CompareGuid (RNGAlgorithm, &gEfiRngAlgorithmSp80090Ctr256Guid)) {
 144     Status = RdRandGetBytes (RNGValueLength, RNGValue);
 145     return Status;
 146   }
 147
 148   //
 149   // The "raw" algorithm is intended to provide entropy directly
 150   //
 151   if (CompareGuid (RNGAlgorithm, &gEfiRngAlgorithmRaw)) {
 152     //
 153     // When a DRBG is used on the output of a entropy source,
 154     // its security level must be at least 256 bits according to UEFI Spec.
 155     //
 156     if (RNGValueLength < 32) {
 157       return EFI_INVALID_PARAMETER;
 158     }
 159
 160     Status = RdRandGenerateEntropy (RNGValueLength, RNGValue);
 161     return Status;
 162   }
 163
 164   //
 165   // Other algorithms were unsupported by this driver.
 166   //
 167   return Status;
 168 }
 169
 170 //
 171 // The Random Number Generator (RNG) protocol
 172 //
 173 EFI_RNG_PROTOCOL mRngRdRand = {
 174   RngGetInfo,
 175   RngGetRNG
 176 };
 177
 178 /**
 179   The user Entry Point for the Random Number Generator (RNG) driver.
 180
 181   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
 182   @param[in] SystemTable    A pointer to the EFI System Table.
 183
 184   @retval EFI_SUCCESS       The entry point is executed successfully.
 185   @retval EFI_NOT_SUPPORTED Platform does not support RNG.
 186   @retval Other             Some error occurs when executing this entry point.
 187
 188 **/
 189 EFI_STATUS
 190 EFIAPI
 191 RngDriverEntry (
 192   IN EFI_HANDLE          ImageHandle,
 193   IN EFI_SYSTEM_TABLE    *SystemTable
 194   )
 195 {
 196   EFI_STATUS    Status;
 197   EFI_HANDLE    Handle;
 198
 199   //
 200   // Verify RdRand support on Platform.
 201   //
 202   Status = IsRdRandSupported ();
 203   if (EFI_ERROR (Status)) {
 204     return Status;
 205   }
 206
 207   //
 208   // Install UEFI RNG (Random Number Generator) Protocol
 209   //
 210   Handle = NULL;
 211   Status = gBS->InstallMultipleProtocolInterfaces (
 212                   &Handle,
 213                   &gEfiRngProtocolGuid,
 214                   &mRngRdRand,
 215                   NULL
 216                   );
 217
 218   return Status;
 219 }