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 197