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 Algorithms 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 - 2018, Intel Corporation. All rights reserved.<BR>
  18 (C) Copyright 2015 Hewlett Packard Enterprise Development LP<BR>
  19 SPDX-License-Identifier: BSD-2-Clause-Patent
  20
  21 **/
  22
  23 #include "RdRand.h"
  24
  25 //
  26 // Supported RNG Algorithms list by this driver.
  27 //
  28 EFI_RNG_ALGORITHM mSupportedRngAlgorithms[] = {
  29   EFI_RNG_ALGORITHM_SP800_90_CTR_256_GUID,
  30   EFI_RNG_ALGORITHM_RAW
  31 };
  32
  33 /**
  34   Returns information about the random number generation implementation.
  35
  36   @param[in]     This                 A pointer to the EFI_RNG_PROTOCOL instance.
  37   @param[in,out] RNGAlgorithmListSize On input, the size in bytes of RNGAlgorithmList.
  38                                       On output with a return code of EFI_SUCCESS, the size
  39                                       in bytes of the data returned in RNGAlgorithmList. On output
  40                                       with a return code of EFI_BUFFER_TOO_SMALL,
  41                                       the size of RNGAlgorithmList required to obtain the list.
  42   @param[out] RNGAlgorithmList        A caller-allocated memory buffer filled by the driver
  43                                       with one EFI_RNG_ALGORITHM element for each supported
  44                                       RNG algorithm. The list must not change across multiple
  45                                       calls to the same driver. The first algorithm in the list
  46                                       is the default algorithm for the driver.
  47
  48   @retval EFI_SUCCESS                 The RNG algorithm list was returned successfully.
  49   @retval EFI_UNSUPPORTED             The services is not supported by this driver.
  50   @retval EFI_DEVICE_ERROR            The list of algorithms could not be retrieved due to a
  51                                       hardware or firmware error.
  52   @retval EFI_INVALID_PARAMETER       One or more of the parameters are incorrect.
  53   @retval EFI_BUFFER_TOO_SMALL        The buffer RNGAlgorithmList is too small to hold the result.
  54
  55 **/
  56 EFI_STATUS
  57 EFIAPI
  58 RngGetInfo (
  59   IN EFI_RNG_PROTOCOL             *This,
  60   IN OUT UINTN                    *RNGAlgorithmListSize,
  61   OUT EFI_RNG_ALGORITHM           *RNGAlgorithmList
  62   )
  63 {
  64   EFI_STATUS    Status;
  65   UINTN         RequiredSize;
  66
  67   if ((This == NULL) || (RNGAlgorithmListSize == NULL)) {
  68     return EFI_INVALID_PARAMETER;
  69   }
  70
  71   RequiredSize = sizeof (mSupportedRngAlgorithms);
  72   if (*RNGAlgorithmListSize < RequiredSize) {
  73     Status = EFI_BUFFER_TOO_SMALL;
  74   } else {
  75     //
  76     // Return algorithm list supported by driver.
  77     //
  78     if (RNGAlgorithmList != NULL) {
  79       CopyMem (RNGAlgorithmList, mSupportedRngAlgorithms, RequiredSize);
  80       Status = EFI_SUCCESS;
  81     } else {
  82       Status = EFI_INVALID_PARAMETER;
  83     }
  84   }
  85   *RNGAlgorithmListSize = RequiredSize;
  86
  87   return Status;
  88 }
  89
  90 /**
  91   Produces and returns an RNG value using either the default or specified RNG algorithm.
  92
  93   @param[in]  This                    A pointer to the EFI_RNG_PROTOCOL instance.
  94   @param[in]  RNGAlgorithm            A pointer to the EFI_RNG_ALGORITHM that identifies the RNG
  95                                       algorithm to use. May be NULL in which case the function will
  96                                       use its default RNG algorithm.
  97   @param[in]  RNGValueLength          The length in bytes of the memory buffer pointed to by
  98                                       RNGValue. The driver shall return exactly this numbers of bytes.
  99   @param[out] RNGValue                A caller-allocated memory buffer filled by the driver with the
 100                                       resulting RNG value.
 101
 102   @retval EFI_SUCCESS                 The RNG value was returned successfully.
 103   @retval EFI_UNSUPPORTED             The algorithm specified by RNGAlgorithm is not supported by
 104                                       this driver.
 105   @retval EFI_DEVICE_ERROR            An RNG value could not be retrieved due to a hardware or
 106                                       firmware error.
 107   @retval EFI_NOT_READY               There is not enough random data available to satisfy the length
 108                                       requested by RNGValueLength.
 109   @retval EFI_INVALID_PARAMETER       RNGValue is NULL or RNGValueLength is zero.
 110
 111 **/
 112 EFI_STATUS
 113 EFIAPI
 114 RngGetRNG (
 115   IN EFI_RNG_PROTOCOL            *This,
 116   IN EFI_RNG_ALGORITHM           *RNGAlgorithm, OPTIONAL
 117   IN UINTN                       RNGValueLength,
 118   OUT UINT8                      *RNGValue
 119   )
 120 {
 121   EFI_STATUS    Status;
 122
 123   if ((RNGValueLength == 0) || (RNGValue == NULL)) {
 124     return EFI_INVALID_PARAMETER;
 125   }
 126
 127   Status = EFI_UNSUPPORTED;
 128   if (RNGAlgorithm == NULL) {
 129     //
 130     // Use the default RNG algorithm if RNGAlgorithm is NULL.
 131     //
 132     RNGAlgorithm = &gEfiRngAlgorithmSp80090Ctr256Guid;
 133   }
 134
 135   //
 136   // NIST SP800-90-AES-CTR-256 supported by RDRAND
 137   //
 138   if (CompareGuid (RNGAlgorithm, &gEfiRngAlgorithmSp80090Ctr256Guid)) {
 139     Status = RdRandGetBytes (RNGValueLength, RNGValue);
 140     return Status;
 141   }
 142
 143   //
 144   // The "raw" algorithm is intended to provide entropy directly
 145   //
 146   if (CompareGuid (RNGAlgorithm, &gEfiRngAlgorithmRaw)) {
 147     //
 148     // When a DRBG is used on the output of a entropy source,
 149     // its security level must be at least 256 bits according to UEFI Spec.
 150     //
 151     if (RNGValueLength < 32) {
 152       return EFI_INVALID_PARAMETER;
 153     }
 154
 155     Status = RdRandGenerateEntropy (RNGValueLength, RNGValue);
 156     return Status;
 157   }
 158
 159   //
 160   // Other algorithms were unsupported by this driver.
 161   //
 162   return Status;
 163 }
 164
 165 //
 166 // The Random Number Generator (RNG) protocol
 167 //
 168 EFI_RNG_PROTOCOL mRngRdRand = {
 169   RngGetInfo,
 170   RngGetRNG
 171 };
 172
 173 /**
 174   The user Entry Point for the Random Number Generator (RNG) driver.
 175
 176   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
 177   @param[in] SystemTable    A pointer to the EFI System Table.
 178
 179   @retval EFI_SUCCESS       The entry point is executed successfully.
 180   @retval EFI_NOT_SUPPORTED Platform does not support RNG.
 181   @retval Other             Some error occurs when executing this entry point.
 182
 183 **/
 184 EFI_STATUS
 185 EFIAPI
 186 RngDriverEntry (
 187   IN EFI_HANDLE          ImageHandle,
 188   IN EFI_SYSTEM_TABLE    *SystemTable
 189   )
 190 {
 191   EFI_STATUS    Status;
 192   EFI_HANDLE    Handle;
 193
 194   //
 195   // Install UEFI RNG (Random Number Generator) Protocol
 196   //
 197   Handle = NULL;
 198   Status = gBS->InstallMultipleProtocolInterfaces (
 199                   &Handle,
 200                   &gEfiRngProtocolGuid,
 201                   &mRngRdRand,
 202                   NULL
 203                   );
 204
 205   return Status;
 206 }