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