|
| 1 | +/** @file |
| 2 | + Random Number Generator (RNG) GUIDs and structures shared across RNG interfaces. |
| 3 | +
|
| 4 | + Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR> |
| 5 | + Copyright (c) Microsoft Corporation. |
| 6 | + SPDX-License-Identifier: BSD-2-Clause-Patent |
| 7 | +
|
| 8 | +**/ |
| 9 | + |
| 10 | +#ifndef RNG_GUID_H_ |
| 11 | +#define RNG_GUID_H_ |
| 12 | + |
| 13 | +FILE_LICENCE ( BSD2_PATENT ); |
| 14 | + |
| 15 | +typedef struct _EFI_RNG_INTERFACE EFI_RNG_INTERFACE; |
| 16 | + |
| 17 | +/// |
| 18 | +/// A selection of EFI_RNG_PROTOCOL algorithms. |
| 19 | +/// The algorithms listed are optional, not meant to be exhaustive and be argmented by |
| 20 | +/// vendors or other industry standards. |
| 21 | +/// |
| 22 | +typedef EFI_GUID EFI_RNG_ALGORITHM; |
| 23 | + |
| 24 | +/// |
| 25 | +/// The algorithms corresponds to SP800-90 as defined in |
| 26 | +/// NIST SP 800-90, "Recommendation for Random Number Generation Using Deterministic Random |
| 27 | +/// Bit Generators", March 2007. |
| 28 | +/// |
| 29 | +#define EFI_RNG_ALGORITHM_SP800_90_HASH_256_GUID \ |
| 30 | + { \ |
| 31 | + 0xa7af67cb, 0x603b, 0x4d42, {0xba, 0x21, 0x70, 0xbf, 0xb6, 0x29, 0x3f, 0x96 } \ |
| 32 | + } |
| 33 | +#define EFI_RNG_ALGORITHM_SP800_90_HMAC_256_GUID \ |
| 34 | + { \ |
| 35 | + 0xc5149b43, 0xae85, 0x4f53, {0x99, 0x82, 0xb9, 0x43, 0x35, 0xd3, 0xa9, 0xe7 } \ |
| 36 | + } |
| 37 | +#define EFI_RNG_ALGORITHM_SP800_90_CTR_256_GUID \ |
| 38 | + { \ |
| 39 | + 0x44f0de6e, 0x4d8c, 0x4045, {0xa8, 0xc7, 0x4d, 0xd1, 0x68, 0x85, 0x6b, 0x9e } \ |
| 40 | + } |
| 41 | + |
| 42 | +/// |
| 43 | +/// The algorithms correspond to X9.31 as defined in |
| 44 | +/// NIST, "Recommended Random Number Generator Based on ANSI X9.31 Appendix A.2.4 Using |
| 45 | +/// the 3-Key Triple DES and AES Algorithm", January 2005. |
| 46 | +/// |
| 47 | +#define EFI_RNG_ALGORITHM_X9_31_3DES_GUID \ |
| 48 | + { \ |
| 49 | + 0x63c4785a, 0xca34, 0x4012, {0xa3, 0xc8, 0x0b, 0x6a, 0x32, 0x4f, 0x55, 0x46 } \ |
| 50 | + } |
| 51 | +#define EFI_RNG_ALGORITHM_X9_31_AES_GUID \ |
| 52 | + { \ |
| 53 | + 0xacd03321, 0x777e, 0x4d3d, {0xb1, 0xc8, 0x20, 0xcf, 0xd8, 0x88, 0x20, 0xc9 } \ |
| 54 | + } |
| 55 | + |
| 56 | +/// |
| 57 | +/// The "raw" algorithm, when supported, is intended to provide entropy directly from |
| 58 | +/// the source, without it going through some deterministic random bit generator. |
| 59 | +/// |
| 60 | +#define EFI_RNG_ALGORITHM_RAW \ |
| 61 | + { \ |
| 62 | + 0xe43176d7, 0xb6e8, 0x4827, {0xb7, 0x84, 0x7f, 0xfd, 0xc4, 0xb6, 0x85, 0x61 } \ |
| 63 | + } |
| 64 | + |
| 65 | +/// |
| 66 | +/// The Arm Architecture states the RNDR that the DRBG algorithm should be compliant |
| 67 | +/// with NIST SP800-90A, while not mandating a particular algorithm, so as to be |
| 68 | +/// inclusive of different geographies. |
| 69 | +/// |
| 70 | +#define EFI_RNG_ALGORITHM_ARM_RNDR \ |
| 71 | + { \ |
| 72 | + 0x43d2fde3, 0x9d4e, 0x4d79, {0x02, 0x96, 0xa8, 0x9b, 0xca, 0x78, 0x08, 0x41} \ |
| 73 | + } |
| 74 | + |
| 75 | +/** |
| 76 | + Returns information about the random number generation implementation. |
| 77 | +
|
| 78 | + @param[in] This A pointer to this interface instance. |
| 79 | + @param[in,out] RNGAlgorithmListSize On input, the size in bytes of RNGAlgorithmList. |
| 80 | + On output with a return code of EFI_SUCCESS, the size |
| 81 | + in bytes of the data returned in RNGAlgorithmList. On output |
| 82 | + with a return code of EFI_BUFFER_TOO_SMALL, |
| 83 | + the size of RNGAlgorithmList required to obtain the list. |
| 84 | + @param[out] RNGAlgorithmList A caller-allocated memory buffer filled by the driver |
| 85 | + with one EFI_RNG_ALGORITHM element for each supported |
| 86 | + RNG algorithm. The list must not change across multiple |
| 87 | + calls to the same driver. The first algorithm in the list |
| 88 | + is the default algorithm for the driver. |
| 89 | +
|
| 90 | + @retval EFI_SUCCESS The RNG algorithm list was returned successfully. |
| 91 | + @retval EFI_UNSUPPORTED The services is not supported by this driver. |
| 92 | + @retval EFI_DEVICE_ERROR The list of algorithms could not be retrieved due to a |
| 93 | + hardware or firmware error. |
| 94 | + @retval EFI_INVALID_PARAMETER One or more of the parameters are incorrect. |
| 95 | + @retval EFI_BUFFER_TOO_SMALL The buffer RNGAlgorithmList is too small to hold the result. |
| 96 | +
|
| 97 | +**/ |
| 98 | +typedef |
| 99 | +EFI_STATUS |
| 100 | +(EFIAPI *EFI_RNG_GET_INFO)( |
| 101 | + IN EFI_RNG_INTERFACE *This, |
| 102 | + IN OUT UINTN *RNGAlgorithmListSize, |
| 103 | + OUT EFI_RNG_ALGORITHM *RNGAlgorithmList |
| 104 | + ); |
| 105 | + |
| 106 | +/** |
| 107 | + Produces and returns an RNG value using either the default or specified RNG algorithm. |
| 108 | +
|
| 109 | + @param[in] This A pointer to this interface instance. |
| 110 | + @param[in] RNGAlgorithm A pointer to the EFI_RNG_ALGORITHM that identifies the RNG |
| 111 | + algorithm to use. May be NULL in which case the function will |
| 112 | + use its default RNG algorithm. |
| 113 | + @param[in] RNGValueLength The length in bytes of the memory buffer pointed to by |
| 114 | + RNGValue. The driver shall return exactly this numbers of bytes. |
| 115 | + @param[out] RNGValue A caller-allocated memory buffer filled by the driver with the |
| 116 | + resulting RNG value. |
| 117 | +
|
| 118 | + @retval EFI_SUCCESS The RNG value was returned successfully. |
| 119 | + @retval EFI_UNSUPPORTED The algorithm specified by RNGAlgorithm is not supported by |
| 120 | + this driver. |
| 121 | + @retval EFI_DEVICE_ERROR An RNG value could not be retrieved due to a hardware or |
| 122 | + firmware error. |
| 123 | + @retval EFI_NOT_READY There is not enough random data available to satisfy the length |
| 124 | + requested by RNGValueLength. |
| 125 | + @retval EFI_INVALID_PARAMETER RNGValue is NULL or RNGValueLength is zero. |
| 126 | +
|
| 127 | +**/ |
| 128 | +typedef |
| 129 | +EFI_STATUS |
| 130 | +(EFIAPI *EFI_RNG_GET_RNG)( |
| 131 | + IN EFI_RNG_INTERFACE *This, |
| 132 | + IN EFI_RNG_ALGORITHM *RNGAlgorithm OPTIONAL, |
| 133 | + IN UINTN RNGValueLength, |
| 134 | + OUT UINT8 *RNGValue |
| 135 | + ); |
| 136 | + |
| 137 | +/// |
| 138 | +/// The Random Number Generator (RNG) interface provides random bits for use in |
| 139 | +/// applications, or entropy for seeding other random number generators. |
| 140 | +/// |
| 141 | +/// This interface is shared between the RNG Protocol defined in the UEFI 2.4 Specification |
| 142 | +/// and the RNG PPI defined in the PI 1.9 Specification. |
| 143 | +/// |
| 144 | +struct _EFI_RNG_INTERFACE { |
| 145 | + EFI_RNG_GET_INFO GetInfo; |
| 146 | + EFI_RNG_GET_RNG GetRNG; |
| 147 | +}; |
| 148 | + |
| 149 | +extern EFI_GUID gEfiRngAlgorithmSp80090Hash256Guid; |
| 150 | +extern EFI_GUID gEfiRngAlgorithmSp80090Hmac256Guid; |
| 151 | +extern EFI_GUID gEfiRngAlgorithmSp80090Ctr256Guid; |
| 152 | +extern EFI_GUID gEfiRngAlgorithmX9313DesGuid; |
| 153 | +extern EFI_GUID gEfiRngAlgorithmX931AesGuid; |
| 154 | +extern EFI_GUID gEfiRngAlgorithmRaw; |
| 155 | +extern EFI_GUID gEfiRngAlgorithmArmRndr; |
| 156 | + |
| 157 | +#endif // #ifndef RNG_GUID_H_ |
0 commit comments