MdePkg/Include/Protocol/Hash2.h

   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