CryptoPkg/Library/BaseCryptLib/Hash/CryptParallelHash.h

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