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