iPXE
Rng.h
Go to the documentation of this file.
00001 /** @file
00002   EFI_RNG_PROTOCOL as defined in UEFI 2.4.
00003   The UEFI Random Number Generator Protocol is used to provide random bits for use
00004   in applications, or entropy for seeding other random number generators.
00005 
00006 Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
00007 This program and the accompanying materials are licensed and made available under
00008 the terms and conditions of the BSD License that accompanies this distribution.
00009 The full text of the license may be found at
00010 http://opensource.org/licenses/bsd-license.php.
00011 
00012 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00013 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00014 
00015 **/
00016 
00017 #ifndef __EFI_RNG_PROTOCOL_H__
00018 #define __EFI_RNG_PROTOCOL_H__
00019 
00020 FILE_LICENCE ( BSD3 );
00021 
00022 ///
00023 /// Global ID for the Random Number Generator Protocol
00024 ///
00025 #define EFI_RNG_PROTOCOL_GUID \
00026   { \
00027     0x3152bca5, 0xeade, 0x433d, {0x86, 0x2e, 0xc0, 0x1c, 0xdc, 0x29, 0x1f, 0x44 } \
00028   }
00029 
00030 typedef struct _EFI_RNG_PROTOCOL EFI_RNG_PROTOCOL;
00031 
00032 ///
00033 /// A selection of EFI_RNG_PROTOCOL algorithms.
00034 /// The algorithms listed are optional, not meant to be exhaustive and be argmented by
00035 /// vendors or other industry standards.
00036 ///
00037 
00038 typedef EFI_GUID EFI_RNG_ALGORITHM;
00039 
00040 ///
00041 /// The algorithms corresponds to SP800-90 as defined in
00042 /// NIST SP 800-90, "Recommendation for Random Number Generation Using Deterministic Random
00043 /// Bit Generators", March 2007.
00044 ///
00045 #define EFI_RNG_ALGORITHM_SP800_90_HASH_256_GUID \
00046   { \
00047     0xa7af67cb, 0x603b, 0x4d42, {0xba, 0x21, 0x70, 0xbf, 0xb6, 0x29, 0x3f, 0x96 } \
00048   }
00049 #define EFI_RNG_ALGORITHM_SP800_90_HMAC_256_GUID \
00050   { \
00051     0xc5149b43, 0xae85, 0x4f53, {0x99, 0x82, 0xb9, 0x43, 0x35, 0xd3, 0xa9, 0xe7 } \
00052   }
00053 #define EFI_RNG_ALGORITHM_SP800_90_CTR_256_GUID \
00054   { \
00055     0x44f0de6e, 0x4d8c, 0x4045, {0xa8, 0xc7, 0x4d, 0xd1, 0x68, 0x85, 0x6b, 0x9e } \
00056   }
00057 ///
00058 /// The algorithms correspond to X9.31 as defined in
00059 /// NIST, "Recommended Random Number Generator Based on ANSI X9.31 Appendix A.2.4 Using
00060 /// the 3-Key Triple DES and AES Algorithm", January 2005.
00061 ///
00062 #define EFI_RNG_ALGORITHM_X9_31_3DES_GUID \
00063   { \
00064     0x63c4785a, 0xca34, 0x4012, {0xa3, 0xc8, 0x0b, 0x6a, 0x32, 0x4f, 0x55, 0x46 } \
00065   }
00066 #define EFI_RNG_ALGORITHM_X9_31_AES_GUID \
00067   { \
00068     0xacd03321, 0x777e, 0x4d3d, {0xb1, 0xc8, 0x20, 0xcf, 0xd8, 0x88, 0x20, 0xc9 } \
00069   }
00070 ///
00071 /// The "raw" algorithm, when supported, is intended to provide entropy directly from
00072 /// the source, without it going through some deterministic random bit generator.
00073 ///
00074 #define EFI_RNG_ALGORITHM_RAW \
00075   { \
00076     0xe43176d7, 0xb6e8, 0x4827, {0xb7, 0x84, 0x7f, 0xfd, 0xc4, 0xb6, 0x85, 0x61 } \
00077   }
00078 
00079 /**
00080   Returns information about the random number generation implementation.
00081 
00082   @param[in]     This                 A pointer to the EFI_RNG_PROTOCOL instance.
00083   @param[in,out] RNGAlgorithmListSize On input, the size in bytes of RNGAlgorithmList.
00084                                       On output with a return code of EFI_SUCCESS, the size
00085                                       in bytes of the data returned in RNGAlgorithmList. On output
00086                                       with a return code of EFI_BUFFER_TOO_SMALL,
00087                                       the size of RNGAlgorithmList required to obtain the list.
00088   @param[out] RNGAlgorithmList        A caller-allocated memory buffer filled by the driver
00089                                       with one EFI_RNG_ALGORITHM element for each supported
00090                                       RNG algorithm. The list must not change across multiple
00091                                       calls to the same driver. The first algorithm in the list
00092                                       is the default algorithm for the driver.
00093 
00094   @retval EFI_SUCCESS                 The RNG algorithm list was returned successfully.
00095   @retval EFI_UNSUPPORTED             The services is not supported by this driver.
00096   @retval EFI_DEVICE_ERROR            The list of algorithms could not be retrieved due to a
00097                                       hardware or firmware error.
00098   @retval EFI_INVALID_PARAMETER       One or more of the parameters are incorrect.
00099   @retval EFI_BUFFER_TOO_SMALL        The buffer RNGAlgorithmList is too small to hold the result.
00100 
00101 **/
00102 typedef
00103 EFI_STATUS
00104 (EFIAPI *EFI_RNG_GET_INFO) (
00105   IN EFI_RNG_PROTOCOL             *This,
00106   IN OUT UINTN                    *RNGAlgorithmListSize,
00107   OUT EFI_RNG_ALGORITHM           *RNGAlgorithmList
00108   );
00109 
00110 /**
00111   Produces and returns an RNG value using either the default or specified RNG algorithm.
00112 
00113   @param[in]  This                    A pointer to the EFI_RNG_PROTOCOL instance.
00114   @param[in]  RNGAlgorithm            A pointer to the EFI_RNG_ALGORITHM that identifies the RNG
00115                                       algorithm to use. May be NULL in which case the function will
00116                                       use its default RNG algorithm.
00117   @param[in]  RNGValueLength          The length in bytes of the memory buffer pointed to by
00118                                       RNGValue. The driver shall return exactly this numbers of bytes.
00119   @param[out] RNGValue                A caller-allocated memory buffer filled by the driver with the
00120                                       resulting RNG value.
00121 
00122   @retval EFI_SUCCESS                 The RNG value was returned successfully.
00123   @retval EFI_UNSUPPORTED             The algorithm specified by RNGAlgorithm is not supported by
00124                                       this driver.
00125   @retval EFI_DEVICE_ERROR            An RNG value could not be retrieved due to a hardware or
00126                                       firmware error.
00127   @retval EFI_NOT_READY               There is not enough random data available to satisfy the length
00128                                       requested by RNGValueLength.
00129   @retval EFI_INVALID_PARAMETER       RNGValue is NULL or RNGValueLength is zero.
00130 
00131 **/
00132 typedef
00133 EFI_STATUS
00134 (EFIAPI *EFI_RNG_GET_RNG) (
00135   IN EFI_RNG_PROTOCOL            *This,
00136   IN EFI_RNG_ALGORITHM           *RNGAlgorithm, OPTIONAL
00137   IN UINTN                       RNGValueLength,
00138   OUT UINT8                      *RNGValue
00139   );
00140 
00141 ///
00142 /// The Random Number Generator (RNG) protocol provides random bits for use in
00143 /// applications, or entropy for seeding other random number generators.
00144 ///
00145 struct _EFI_RNG_PROTOCOL {
00146   EFI_RNG_GET_INFO                GetInfo;
00147   EFI_RNG_GET_RNG                 GetRNG;
00148 };
00149 
00150 extern EFI_GUID gEfiRngProtocolGuid;
00151 extern EFI_GUID gEfiRngAlgorithmSp80090Hash256Guid;
00152 extern EFI_GUID gEfiRngAlgorithmSp80090Hmac256Guid;
00153 extern EFI_GUID gEfiRngAlgorithmSp80090Ctr256Guid;
00154 extern EFI_GUID gEfiRngAlgorithmX9313DesGuid;
00155 extern EFI_GUID gEfiRngAlgorithmX931AesGuid;
00156 extern EFI_GUID gEfiRngAlgorithmRaw;
00157 
00158 #endif