[mirror_edk2.git] / CryptoPkg / Library / BaseCryptLib / Hash / CryptParallelHash.h

/** @file\r
  ParallelHash related function and type declaration.\r
\r
Copyright (c) 2022, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.\r
Licensed under the OpenSSL license (the "License").  You may not use\r
this file except in compliance with the License.  You can obtain a copy\r
in the file LICENSE in the source distribution or at\r
https://www.openssl.org/source/license.html\r
\r
Copyright 2022 The eXtended Keccak Code Package (XKCP)\r
https://github.com/XKCP/XKCP\r
Keccak, designed by Guido Bertoni, Joan Daemen, Michael Peeters and Gilles Van Assche.\r
Implementation by the designers, hereby denoted as "the implementer".\r
For more information, feedback or questions, please refer to the Keccak Team website:\r
https://keccak.team/\r
To the extent possible under law, the implementer has waived all copyright\r
and related or neighboring rights to the source code in this file.\r
http://creativecommons.org/publicdomain/zero/1.0/\r
**/\r
\r
#include "InternalCryptLib.h"\r
\r
#define KECCAK1600_WIDTH  1600\r
\r
typedef UINT64 uint64_t;\r
\r
//\r
// This struct referring to m_sha3.c from opessl and modified its type name.\r
//\r
typedef struct {\r
  uint64_t         A[5][5];\r
  size_t           block_size;  /* cached ctx->digest->block_size */\r
  size_t           md_size;     /* output length, variable in XOF */\r
  size_t           num;         /* used bytes in below buffer */\r
  unsigned char    buf[KECCAK1600_WIDTH / 8 - 32];\r
  unsigned char    pad;\r
} Keccak1600_Ctx;\r
\r
/**\r
  SHA3_absorb can be called multiple times, but at each invocation\r
  largest multiple of |r| out of |len| bytes are processed. Then\r
  remaining amount of bytes is returned. This is done to spare caller\r
  trouble of calculating the largest multiple of |r|. |r| can be viewed\r
  as blocksize. It is commonly (1600 - 256*n)/8, e.g. 168, 136, 104,\r
  72, but can also be (1600 - 448)/8 = 144. All this means that message\r
  padding and intermediate sub-block buffering, byte- or bitwise, is\r
  caller's responsibility.\r
**/\r
size_t\r
SHA3_absorb (\r
  uint64_t             A[5][5],\r
  const unsigned char  *inp,\r
  size_t               len,\r
  size_t               r\r
  );\r
\r
/**\r
  SHA3_squeeze is called once at the end to generate |out| hash value\r
  of |len| bytes.\r
**/\r
void\r
SHA3_squeeze (\r
  uint64_t       A[5][5],\r
  unsigned char  *out,\r
  size_t         len,\r
  size_t         r\r
  );\r
\r
/**\r
  Encode function from XKCP.\r
\r
  Encodes the input as a byte string in a way that can be unambiguously parsed\r
  from the beginning of the string by inserting the length of the byte string\r
  before the byte string representation of input.\r
\r
  @param[out] EncBuf  Result of left encode.\r
  @param[in]  Value   Input of left encode.\r
\r
  @retval EncLen  Size of encode result in bytes.\r
**/\r
UINTN\r
EFIAPI\r
LeftEncode (\r
  OUT UINT8  *EncBuf,\r
  IN  UINTN  Value\r
  );\r
\r
/**\r
  Encode function from XKCP.\r
\r
  Encodes the input as a byte string in a way that can be unambiguously parsed\r
  from the end of the string by inserting the length of the byte string after\r
  the byte string representation of input.\r
\r
  @param[out] EncBuf  Result of right encode.\r
  @param[in]  Value   Input of right encode.\r
\r
  @retval EncLen  Size of encode result in bytes.\r
**/\r
UINTN\r
EFIAPI\r
RightEncode (\r
  OUT UINT8  *EncBuf,\r
  IN  UINTN  Value\r
  );\r
\r
/**\r
  Keccak initial fuction.\r
\r
  Set up state with specified capacity.\r
\r
  @param[out] Context           Pointer to the context being initialized.\r
  @param[in]  Pad               Delimited Suffix.\r
  @param[in]  BlockSize         Size of context block.\r
  @param[in]  MessageDigestLen  Size of message digest in bytes.\r
\r
  @retval 1  Initialize successfully.\r
  @retval 0  Fail to initialize.\r
**/\r
UINT8\r
EFIAPI\r
KeccakInit (\r
  OUT Keccak1600_Ctx  *Context,\r
  IN  UINT8           Pad,\r
  IN  UINTN           BlockSize,\r
  IN  UINTN           MessageDigstLen\r
  );\r
\r
/**\r
  Sha3 update fuction.\r
\r
  This function performs Sha3 digest on a data buffer of the specified size.\r
  It can be called multiple times to compute the digest of long or discontinuous data streams.\r
\r
  @param[in,out] Context   Pointer to the Keccak context.\r
  @param[in]     Data      Pointer to the buffer containing the data to be hashed.\r
  @param[in]     DataSize  Size of Data buffer in bytes.\r
\r
  @retval 1  Update successfully.\r
**/\r
UINT8\r
EFIAPI\r
Sha3Update (\r
  IN OUT Keccak1600_Ctx  *Context,\r
  IN const VOID          *Data,\r
  IN UINTN               DataSize\r
  );\r
\r
/**\r
  Completes computation of Sha3 message digest.\r
\r
  This function completes sha3 hash computation and retrieves the digest value into\r
  the specified memory. After this function has been called, the keccak context cannot\r
  be used again.\r
\r
  @param[in, out]  Context        Pointer to the keccak context.\r
  @param[out]      MessageDigest  Pointer to a buffer that receives the message digest.\r
\r
  @retval 1   Meaasge digest computation succeeded.\r
**/\r
UINT8\r
EFIAPI\r
Sha3Final (\r
  IN OUT Keccak1600_Ctx  *Context,\r
  OUT    UINT8           *MessageDigest\r
  );\r
\r
/**\r
  Computes the CSHAKE-256 message digest of a input data buffer.\r
\r
  This function performs the CSHAKE-256 message digest of a given data buffer, and places\r
  the digest value into the specified memory.\r
\r
  @param[in]   Data               Pointer to the buffer containing the data to be hashed.\r
  @param[in]   DataSize           Size of Data buffer in bytes.\r
  @param[in]   OutputLen          Size of output in bytes.\r
  @param[in]   Name               Pointer to the function name string.\r
  @param[in]   NameLen            Size of the function name in bytes.\r
  @param[in]   Customization      Pointer to the customization string.\r
  @param[in]   CustomizationLen   Size of the customization string in bytes.\r
  @param[out]  HashValue          Pointer to a buffer that receives the CSHAKE-256 digest\r
                                  value.\r
\r
  @retval TRUE   CSHAKE-256 digest computation succeeded.\r
  @retval FALSE  CSHAKE-256 digest computation failed.\r
  @retval FALSE  This interface is not supported.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
CShake256HashAll (\r
  IN   CONST VOID  *Data,\r
  IN   UINTN       DataSize,\r
  IN   UINTN       OutputLen,\r
  IN   CONST VOID  *Name,\r
  IN   UINTN       NameLen,\r
  IN   CONST VOID  *Customization,\r
  IN   UINTN       CustomizationLen,\r
  OUT  UINT8       *HashValue\r
  );\r
Commit	Line	Data
c1e66210 ZL	1	/** @file\r
	2	ParallelHash related function and type declaration.\r
	3	\r
	4	Copyright (c) 2022, Intel Corporation. All rights reserved.<BR>\r
	5	SPDX-License-Identifier: BSD-2-Clause-Patent\r
	6	\r
	7	Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.\r
	8	Licensed under the OpenSSL license (the "License"). You may not use\r
	9	this file except in compliance with the License. You can obtain a copy\r
	10	in the file LICENSE in the source distribution or at\r
	11	https://www.openssl.org/source/license.html\r
	12	\r
	13	Copyright 2022 The eXtended Keccak Code Package (XKCP)\r
	14	https://github.com/XKCP/XKCP\r
	15	Keccak, designed by Guido Bertoni, Joan Daemen, Michael Peeters and Gilles Van Assche.\r
	16	Implementation by the designers, hereby denoted as "the implementer".\r
	17	For more information, feedback or questions, please refer to the Keccak Team website:\r
	18	https://keccak.team/\r
	19	To the extent possible under law, the implementer has waived all copyright\r
	20	and related or neighboring rights to the source code in this file.\r
	21	http://creativecommons.org/publicdomain/zero/1.0/\r
	22	**/\r
	23	\r
	24	#include "InternalCryptLib.h"\r
	25	\r
	26	#define KECCAK1600_WIDTH 1600\r
	27	\r
355515a0 LZ	28	typedef UINT64 uint64_t;\r
355515a0 LZ	29	\r
c1e66210 ZL	30	//\r
	31	// This struct referring to m_sha3.c from opessl and modified its type name.\r
	32	//\r
	33	typedef struct {\r
	34	uint64_t A[5][5];\r
	35	size_t block_size; /* cached ctx->digest->block_size */\r
	36	size_t md_size; /* output length, variable in XOF */\r
	37	size_t num; /* used bytes in below buffer */\r
	38	unsigned char buf[KECCAK1600_WIDTH / 8 - 32];\r
	39	unsigned char pad;\r
	40	} Keccak1600_Ctx;\r
	41	\r
	42	/**\r
	43	SHA3_absorb can be called multiple times, but at each invocation\r
	44	largest multiple of \|r\| out of \|len\| bytes are processed. Then\r
	45	remaining amount of bytes is returned. This is done to spare caller\r
	46	trouble of calculating the largest multiple of \|r\|. \|r\| can be viewed\r
	47	as blocksize. It is commonly (1600 - 256*n)/8, e.g. 168, 136, 104,\r
	48	72, but can also be (1600 - 448)/8 = 144. All this means that message\r
	49	padding and intermediate sub-block buffering, byte- or bitwise, is\r
	50	caller's responsibility.\r
	51	**/\r
	52	size_t\r
	53	SHA3_absorb (\r
	54	uint64_t A[5][5],\r
	55	const unsigned char *inp,\r
	56	size_t len,\r
	57	size_t r\r
	58	);\r
	59	\r
	60	/**\r
	61	SHA3_squeeze is called once at the end to generate \|out\| hash value\r
	62	of \|len\| bytes.\r
	63	**/\r
	64	void\r
	65	SHA3_squeeze (\r
	66	uint64_t A[5][5],\r
	67	unsigned char *out,\r
	68	size_t len,\r
	69	size_t r\r
	70	);\r
	71	\r
	72	/**\r
	73	Encode function from XKCP.\r
	74	\r
	75	Encodes the input as a byte string in a way that can be unambiguously parsed\r
	76	from the beginning of the string by inserting the length of the byte string\r
	77	before the byte string representation of input.\r
	78	\r
	79	@param[out] EncBuf Result of left encode.\r
	80	@param[in] Value Input of left encode.\r
	81	\r
	82	@retval EncLen Size of encode result in bytes.\r
	83	**/\r
	84	UINTN\r
	85	EFIAPI\r
	86	LeftEncode (\r
	87	OUT UINT8 *EncBuf,\r
	88	IN UINTN Value\r
	89	);\r
	90	\r
	91	/**\r
	92	Encode function from XKCP.\r
	93	\r
94	Encodes the input as a byte string in a way that can be unambiguously parsed\r
95	from the end of the string by inserting the length of the byte string after\r
96	the byte string representation of input.\r
97	\r
98	@param[out] EncBuf Result of right encode.\r
99	@param[in] Value Input of right encode.\r
100	\r
101	@retval EncLen Size of encode result in bytes.\r
102	**/\r
103	UINTN\r
104	EFIAPI\r
105	RightEncode (\r
106	OUT UINT8 *EncBuf,\r
107	IN UINTN Value\r
108	);\r
109	\r
110	/**\r
111	Keccak initial fuction.\r
112	\r
113	Set up state with specified capacity.\r
114	\r
115	@param[out] Context Pointer to the context being initialized.\r
116	@param[in] Pad Delimited Suffix.\r
117	@param[in] BlockSize Size of context block.\r
118	@param[in] MessageDigestLen Size of message digest in bytes.\r
119	\r
120	@retval 1 Initialize successfully.\r
121	@retval 0 Fail to initialize.\r
122	**/\r
123	UINT8\r
124	EFIAPI\r
125	KeccakInit (\r
126	OUT Keccak1600_Ctx *Context,\r
127	IN UINT8 Pad,\r
128	IN UINTN BlockSize,\r
129	IN UINTN MessageDigstLen\r
130	);\r
131	\r
132	/**\r
133	Sha3 update fuction.\r
134	\r
135	This function performs Sha3 digest on a data buffer of the specified size.\r
136	It can be called multiple times to compute the digest of long or discontinuous data streams.\r
137	\r
138	@param[in,out] Context Pointer to the Keccak context.\r
139	@param[in] Data Pointer to the buffer containing the data to be hashed.\r
140	@param[in] DataSize Size of Data buffer in bytes.\r
141	\r
142	@retval 1 Update successfully.\r
143	**/\r
144	UINT8\r
145	EFIAPI\r
146	Sha3Update (\r
147	IN OUT Keccak1600_Ctx *Context,\r
148	IN const VOID *Data,\r
149	IN UINTN DataSize\r
150	);\r
151	\r
152	/**\r
153	Completes computation of Sha3 message digest.\r
154	\r
155	This function completes sha3 hash computation and retrieves the digest value into\r
156	the specified memory. After this function has been called, the keccak context cannot\r
157	be used again.\r
158	\r
159	@param[in, out] Context Pointer to the keccak context.\r
160	@param[out] MessageDigest Pointer to a buffer that receives the message digest.\r
161	\r
162	@retval 1 Meaasge digest computation succeeded.\r
163	**/\r
164	UINT8\r
165	EFIAPI\r
166	Sha3Final (\r
167	IN OUT Keccak1600_Ctx *Context,\r
168	OUT UINT8 *MessageDigest\r
169	);\r
170	\r
171	/**\r
172	Computes the CSHAKE-256 message digest of a input data buffer.\r
173	\r
174	This function performs the CSHAKE-256 message digest of a given data buffer, and places\r
175	the digest value into the specified memory.\r
176	\r
177	@param[in] Data Pointer to the buffer containing the data to be hashed.\r
178	@param[in] DataSize Size of Data buffer in bytes.\r
179	@param[in] OutputLen Size of output in bytes.\r
180	@param[in] Name Pointer to the function name string.\r
181	@param[in] NameLen Size of the function name in bytes.\r
182	@param[in] Customization Pointer to the customization string.\r
183	@param[in] CustomizationLen Size of the customization string in bytes.\r
184	@param[out] HashValue Pointer to a buffer that receives the CSHAKE-256 digest\r
185	value.\r
186	\r
187	@retval TRUE CSHAKE-256 digest computation succeeded.\r
188	@retval FALSE CSHAKE-256 digest computation failed.\r
189	@retval FALSE This interface is not supported.\r
190	\r
191	**/\r
192	BOOLEAN\r
193	EFIAPI\r
194	CShake256HashAll (\r
195	IN CONST VOID *Data,\r
196	IN UINTN DataSize,\r
197	IN UINTN OutputLen,\r
198	IN CONST VOID *Name,\r
199	IN UINTN NameLen,\r
200	IN CONST VOID *Customization,\r
201	IN UINTN CustomizationLen,\r
202	OUT UINT8 *HashValue\r
203	);\r