[mirror_edk2.git] / MdePkg / Include / Protocol / Hash2.h

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