Subrata Banik | 20fe24b | 2021-12-09 02:46:38 +0530 | [diff] [blame] | 1 | /** @file |
| 2 | EFI_HASH2_SERVICE_BINDING_PROTOCOL as defined in UEFI 2.5. |
| 3 | EFI_HASH2_PROTOCOL as defined in UEFI 2.5. |
| 4 | The EFI Hash2 Service Binding Protocol is used to locate hashing services support |
| 5 | provided by a driver and to create and destroy instances of the EFI Hash2 Protocol |
| 6 | so that a multiple drivers can use the underlying hashing services. |
| 7 | EFI_HASH2_PROTOCOL describes hashing functions for which the algorithm-required |
| 8 | message padding and finalization are performed by the supporting driver. |
| 9 | |
| 10 | Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> |
| 11 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 12 | |
| 13 | **/ |
| 14 | |
| 15 | #ifndef __EFI_HASH2_PROTOCOL_H__ |
| 16 | #define __EFI_HASH2_PROTOCOL_H__ |
| 17 | |
| 18 | #define EFI_HASH2_SERVICE_BINDING_PROTOCOL_GUID \ |
| 19 | { \ |
| 20 | 0xda836f8d, 0x217f, 0x4ca0, { 0x99, 0xc2, 0x1c, 0xa4, 0xe1, 0x60, 0x77, 0xea } \ |
| 21 | } |
| 22 | |
| 23 | #define EFI_HASH2_PROTOCOL_GUID \ |
| 24 | { \ |
| 25 | 0x55b1d734, 0xc5e1, 0x49db, { 0x96, 0x47, 0xb1, 0x6a, 0xfb, 0xe, 0x30, 0x5b } \ |
| 26 | } |
| 27 | |
| 28 | #include <Protocol/Hash.h> |
| 29 | |
| 30 | // |
| 31 | // NOTE: |
| 32 | // Algorithms EFI_HASH_ALGORITHM_SHA1_NOPAD and |
| 33 | // EFI_HASH_ALGORITHM_SHA256_NOPAD_GUID are not compatible with |
| 34 | // EFI_HASH2_PROTOCOL and will return EFI_UNSUPPORTED if used with any |
| 35 | // EFI_HASH2_PROTOCOL function. |
| 36 | // |
| 37 | |
| 38 | // |
| 39 | // Note: SHA-1 and MD5 are included for backwards compatibility. |
| 40 | // New driver implementations are encouraged to consider stronger algorithms. |
| 41 | // |
| 42 | |
| 43 | typedef struct _EFI_HASH2_PROTOCOL EFI_HASH2_PROTOCOL; |
| 44 | |
| 45 | typedef UINT8 EFI_MD5_HASH2[16]; |
| 46 | typedef UINT8 EFI_SHA1_HASH2[20]; |
| 47 | typedef UINT8 EFI_SHA224_HASH2[28]; |
| 48 | typedef UINT8 EFI_SHA256_HASH2[32]; |
| 49 | typedef UINT8 EFI_SHA384_HASH2[48]; |
| 50 | typedef UINT8 EFI_SHA512_HASH2[64]; |
| 51 | |
| 52 | typedef union { |
| 53 | EFI_MD5_HASH2 Md5Hash; |
| 54 | EFI_SHA1_HASH2 Sha1Hash; |
| 55 | EFI_SHA224_HASH2 Sha224Hash; |
| 56 | EFI_SHA256_HASH2 Sha256Hash; |
| 57 | EFI_SHA384_HASH2 Sha384Hash; |
| 58 | EFI_SHA512_HASH2 Sha512Hash; |
| 59 | } EFI_HASH2_OUTPUT; |
| 60 | |
| 61 | /** |
| 62 | Returns the size of the hash which results from a specific algorithm. |
| 63 | |
| 64 | @param[in] This Points to this instance of EFI_HASH2_PROTOCOL. |
| 65 | @param[in] HashAlgorithm Points to the EFI_GUID which identifies the algorithm to use. |
| 66 | @param[out] HashSize Holds the returned size of the algorithm's hash. |
| 67 | |
| 68 | @retval EFI_SUCCESS Hash size returned successfully. |
| 69 | @retval EFI_INVALID_PARAMETER This or HashSize is NULL. |
| 70 | @retval EFI_UNSUPPORTED The algorithm specified by HashAlgorithm is not supported by this driver |
| 71 | or HashAlgorithm is null. |
| 72 | |
| 73 | **/ |
| 74 | typedef |
| 75 | EFI_STATUS |
| 76 | (EFIAPI *EFI_HASH2_GET_HASH_SIZE)( |
| 77 | IN CONST EFI_HASH2_PROTOCOL *This, |
| 78 | IN CONST EFI_GUID *HashAlgorithm, |
| 79 | OUT UINTN *HashSize |
| 80 | ); |
| 81 | |
| 82 | /** |
| 83 | Creates a hash for the specified message text. The hash is not extendable. |
| 84 | The output is final with any algorithm-required padding added by the function. |
| 85 | |
| 86 | @param[in] This Points to this instance of EFI_HASH2_PROTOCOL. |
| 87 | @param[in] HashAlgorithm Points to the EFI_GUID which identifies the algorithm to use. |
| 88 | @param[in] Message Points to the start of the message. |
| 89 | @param[in] MessageSize The size of Message, in bytes. |
| 90 | @param[in,out] Hash On input, points to a caller-allocated buffer of the size |
| 91 | returned by GetHashSize() for the specified HashAlgorithm. |
| 92 | On output, the buffer holds the resulting hash computed from the message. |
| 93 | |
| 94 | @retval EFI_SUCCESS Hash returned successfully. |
| 95 | @retval EFI_INVALID_PARAMETER This or Hash is NULL. |
| 96 | @retval EFI_UNSUPPORTED The algorithm specified by HashAlgorithm is not supported by this driver |
| 97 | or HashAlgorithm is Null. |
| 98 | @retval EFI_OUT_OF_RESOURCES Some resource required by the function is not available |
| 99 | or MessageSize is greater than platform maximum. |
| 100 | |
| 101 | **/ |
| 102 | typedef |
| 103 | EFI_STATUS |
| 104 | (EFIAPI *EFI_HASH2_HASH)( |
| 105 | IN CONST EFI_HASH2_PROTOCOL *This, |
| 106 | IN CONST EFI_GUID *HashAlgorithm, |
| 107 | IN CONST UINT8 *Message, |
| 108 | IN UINTN MessageSize, |
| 109 | IN OUT EFI_HASH2_OUTPUT *Hash |
| 110 | ); |
| 111 | |
| 112 | /** |
| 113 | This function must be called to initialize a digest calculation to be subsequently performed using the |
| 114 | EFI_HASH2_PROTOCOL functions HashUpdate() and HashFinal(). |
| 115 | |
| 116 | @param[in] This Points to this instance of EFI_HASH2_PROTOCOL. |
| 117 | @param[in] HashAlgorithm Points to the EFI_GUID which identifies the algorithm to use. |
| 118 | |
| 119 | @retval EFI_SUCCESS Initialized successfully. |
| 120 | @retval EFI_INVALID_PARAMETER This is NULL. |
| 121 | @retval EFI_UNSUPPORTED The algorithm specified by HashAlgorithm is not supported by this driver |
| 122 | or HashAlgorithm is Null. |
| 123 | @retval EFI_OUT_OF_RESOURCES Process failed due to lack of required resource. |
| 124 | @retval EFI_ALREADY_STARTED This function is called when the operation in progress is still in processing Hash(), |
| 125 | or HashInit() is already called before and not terminated by HashFinal() yet on the same instance. |
| 126 | |
| 127 | **/ |
| 128 | typedef |
| 129 | EFI_STATUS |
| 130 | (EFIAPI *EFI_HASH2_HASH_INIT)( |
| 131 | IN CONST EFI_HASH2_PROTOCOL *This, |
| 132 | IN CONST EFI_GUID *HashAlgorithm |
| 133 | ); |
| 134 | |
| 135 | /** |
| 136 | Updates the hash of a computation in progress by adding a message text. |
| 137 | |
| 138 | @param[in] This Points to this instance of EFI_HASH2_PROTOCOL. |
| 139 | @param[in] Message Points to the start of the message. |
| 140 | @param[in] MessageSize The size of Message, in bytes. |
| 141 | |
| 142 | @retval EFI_SUCCESS Digest in progress updated successfully. |
| 143 | @retval EFI_INVALID_PARAMETER This or Hash is NULL. |
| 144 | @retval EFI_OUT_OF_RESOURCES Some resource required by the function is not available |
| 145 | or MessageSize is greater than platform maximum. |
| 146 | @retval EFI_NOT_READY This call was not preceded by a valid call to HashInit(), |
| 147 | or the operation in progress was terminated by a call to Hash() or HashFinal() on the same instance. |
| 148 | |
| 149 | **/ |
| 150 | typedef |
| 151 | EFI_STATUS |
| 152 | (EFIAPI *EFI_HASH2_HASH_UPDATE)( |
| 153 | IN CONST EFI_HASH2_PROTOCOL *This, |
| 154 | IN CONST UINT8 *Message, |
| 155 | IN UINTN MessageSize |
| 156 | ); |
| 157 | |
| 158 | /** |
| 159 | Finalizes a hash operation in progress and returns calculation result. |
| 160 | The output is final with any necessary padding added by the function. |
| 161 | The hash may not be further updated or extended after HashFinal(). |
| 162 | |
| 163 | @param[in] This Points to this instance of EFI_HASH2_PROTOCOL. |
| 164 | @param[in,out] Hash On input, points to a caller-allocated buffer of the size |
| 165 | returned by GetHashSize() for the specified HashAlgorithm specified in preceding HashInit(). |
| 166 | On output, the buffer holds the resulting hash computed from the message. |
| 167 | |
| 168 | @retval EFI_SUCCESS Hash returned successfully. |
| 169 | @retval EFI_INVALID_PARAMETER This or Hash is NULL. |
| 170 | @retval EFI_NOT_READY This call was not preceded by a valid call to HashInit() and at least one call to HashUpdate(), |
| 171 | or the operation in progress was canceled by a call to Hash() on the same instance. |
| 172 | |
| 173 | **/ |
| 174 | typedef |
| 175 | EFI_STATUS |
| 176 | (EFIAPI *EFI_HASH2_HASH_FINAL)( |
| 177 | IN CONST EFI_HASH2_PROTOCOL *This, |
| 178 | IN OUT EFI_HASH2_OUTPUT *Hash |
| 179 | ); |
| 180 | |
| 181 | /// |
| 182 | /// This protocol describes hashing functions for which the algorithm-required message padding and |
| 183 | /// finalization are performed by the supporting driver. |
| 184 | /// |
| 185 | struct _EFI_HASH2_PROTOCOL { |
| 186 | EFI_HASH2_GET_HASH_SIZE GetHashSize; |
| 187 | EFI_HASH2_HASH Hash; |
| 188 | EFI_HASH2_HASH_INIT HashInit; |
| 189 | EFI_HASH2_HASH_UPDATE HashUpdate; |
| 190 | EFI_HASH2_HASH_FINAL HashFinal; |
| 191 | }; |
| 192 | |
| 193 | extern EFI_GUID gEfiHash2ServiceBindingProtocolGuid; |
| 194 | extern EFI_GUID gEfiHash2ProtocolGuid; |
| 195 | |
| 196 | #endif |