[SB][Library][Fix] Fix shift issue in sha3 kernel

ipl_ci · ipl_ci · commit 261c6f3ccba1 · 2025-05-22T06:51:28.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ This is a list of notable changes to Intel® Cryptography Primitives Library, in
 - Added support for HKDF, Hashed Message Authentication Code (HMAC)-based key derivation function as defined by RFC-5869.
 - Added key and signature generations for the eXtended Merkle Signature Scheme (XMSS) algorithm.
 - Minimal supported BoringSSL version was increased to [0.20250114.0](https://github.com/google/boringssl/releases/tag/0.20250114.0) tag.
+- Added support for SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128 and SHAKE256 hash algorithms as defined by FIPS PUB 202.
 
 ## Intel(R) Cryptography Primitives Library 1.1.0
 
diff --git a/doc/source/bibliography.rst b/doc/source/bibliography.rst
@@ -111,6 +111,15 @@ to you in using cryptography functions of Intel® Cryptography Primitives Librar
       198*. The Key-Hash Message Authentication Code (HMAC), July 2008.
       Available from http://csrc.nist.gov/publications/.
 
+
+   .. _fips-pub-202:
+
+   [FIPS PUB 202]
+      *Federal Information Processing Standards Publications, FIPS PUB
+      202*. SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions, August 2015.
+      Available from http://csrc.nist.gov/publications/.
+
+
    .. _ieee-p1363a:
 
    [IEEE P1363A]
diff --git a/doc/source/gfpecsetpointhash-gfpecsetpointhashbackcompatible.rst b/doc/source/gfpecsetpointhash-gfpecsetpointhashbackcompatible.rst
@@ -104,6 +104,10 @@ Return Values
      -  Indicates an error condition if msgLen is negative.
    * -     ippStsQuadraticNonResidueErr
      -  Indicates an error condition if the square of the ``Y``-coordinate of the point is a quadratic non-residue modulo ``p``.
+   * -     ippStsNotSupportedModeErr
+     -  Indicates an error condition if the provided hash algorithm identifier is not supported.
+   * -     ippStsMemAllocErr
+     -  An internal functional error. If this output status appears, update to the latest version of the library or contact `Intel <https://github.com/intel/cryptography-primitives/issues>`_.
 
 
 
diff --git a/doc/source/hashduplicate.rst b/doc/source/hashduplicate.rst
@@ -76,6 +76,8 @@ Return Values
      -     Indicates an error condition if any of the specified pointers is NULL.
    * -     ippStsContextMatchErr
      -     Indicates an error condition if any of the context parameters does not match the operation.
+   * -     ippStsNotSupportedModeErr
+     -     Indicates an error condition if the provided hash algorithm identifier is not supported.
 
 
 
diff --git a/doc/source/hashfinal.rst b/doc/source/hashfinal.rst
@@ -75,6 +75,7 @@ Return Values
      -     Indicates an error condition if any of the specified pointers is NULL.
    * -     ippStsContextMatchErr
      -     Indicates an error condition if the context parameter does not match the operation.
-
+   * -     ippStsNotSupportedModeErr
+     -     Indicates an error condition if the provided hash algorithm identifier is not supported.
 
 
diff --git a/doc/source/hashgetsize.rst b/doc/source/hashgetsize.rst
@@ -19,6 +19,9 @@ IppStatus ippsHashGetSize(int \*pSize);
 IppStatus ippsHashGetSize_rmf(int \*pSize);
 
 
+IppStatus ippsHashGetSizeOptimal_rmf(int \*pSize, IppsHashMethod\* pMethod);
+
+
 Include Files
 -------------
 
@@ -35,6 +38,8 @@ Parameters
 
    * -     pSize
      -  Pointer to the value of the IppsHashState or IppsHashState_rmf context size.
+   * -      IppsHashMethod\*
+     -  Pointer to the hash method.
 
 
 
@@ -48,8 +53,10 @@ Description
    ippsHashGetSize function is deprecated. Please refer to :ref:`Deprecated Functions <appendix-b-deprecated-functions>`
    section for the recommendations for transition.
 
-The function gets the size of the IppsHashState or IppsHashState_rmf
-context in bytes and stores it in \*pSize.
+The functions get the size of the IppsHashState or IppsHashState_rmf
+context in bytes and stores it in \*pSize. ippsHashGetSize and ippsHashGetSize_rmf are universal for supported hash methods 
+and provide a size sufficient for the largest method. ippsHashGetSizeOptimal_rmf provides the minimum size required 
+for a particular method and can be used to reduce memory consumption.
 
 
 .. note::
diff --git a/doc/source/hashgettag.rst b/doc/source/hashgettag.rst
@@ -84,6 +84,8 @@ Return Values
      -  Indicates an error condition if tagLen < 1 or tagLen exceeds the maximal length of a particular digest.
    * -     ippStsContextMatchErr
      -  Indicates an error condition if the context parameter does not match the operation.
+   * -     ippStsNotSupportedModeErr
+     -  Indicates an error condition if the provided hash algorithm identifier is not supported.
 
 
 
diff --git a/doc/source/hashmethod.rst b/doc/source/hashmethod.rst
@@ -85,13 +85,40 @@ const IppsHashMethod\* ippsHashMethod_SM3_NI(void);
 const IppsHashMethod\* ippsHashMethod_SM3_TT(void);
 
 
+const IppsHashMethod\* ippsHashMethod_SHA3_224(void);
+
+const IppsHashMethod\* ippsHashMethod_SHA3_256(void);
+
+const IppsHashMethod\* ippsHashMethod_SHA3_384(void);
+
+const IppsHashMethod\* ippsHashMethod_SHA3_512(void);
+
+
+const IppsHashMethod\* ippsHashMethod_SHAKE128(int digestBitsize);
+
+const IppsHashMethod\* ippsHashMethod_SHAKE256(int digestBitsize);
+
 Include Files
 -------------
 
 
 ``ippcp.h``
 
 
+
+Parameters
+----------
+
+
+.. list-table::
+   :header-rows: 0
+
+   * -      digestBitsize
+     -  The size of output digest in bits. Should be positive multiple of 8 integer.
+
+
+
+
 Description
 -----------
 
@@ -122,6 +149,8 @@ Return Values
 
    * -     const ippsHashMethod\*
      -  Pointer to the particular hash method.
+   * -     ``NULL``
+     -  digestBitsize is not positive multiple of 8 integer.
 
 
 
diff --git a/doc/source/hashmethodset.rst b/doc/source/hashmethodset.rst
@@ -86,6 +86,19 @@ const IppStatus ippsHashMethodSet_SM3_NI(IppsHashMethod\* pMethod);
 const IppStatus ippsHashMethodSet_SM3_TT(IppsHashMethod\* pMethod);
 
 
+const IppStatus ippsHashMethodSet_SHA3_224(IppsHashMethod\* pMethod);
+
+const IppStatus ippsHashMethodSet_SHA3_256(IppsHashMethod\* pMethod);
+
+const IppStatus ippsHashMethodSet_SHA3_384(IppsHashMethod\* pMethod);
+
+const IppStatus ippsHashMethodSet_SHA3_512(IppsHashMethod\* pMethod);
+
+
+const IppStatus ippsHashMethodSet_SHAKE128(IppsHashMethod\* pMethod, int digestBitsize);
+
+const IppStatus ippsHashMethodSet_SHAKE256(IppsHashMethod\* pMethod, int digestBitsize);
+
 Include Files
 -------------
 
@@ -102,6 +115,8 @@ Parameters
 
    * -      IppsHashMethod\*
      -  Pointer to the uninitialized hash method.
+   * -      digestBitsize
+     -  The size of output digest in bits. Should be positive multiple of 8 integer.
 
 
 
@@ -139,6 +154,8 @@ Return Values
      -  Indicates no errors. Any other value indicates an error or warning.
    * -      ippStsNullPtrErr
      -  Indicates an error condition if any of the specified pointers is NULL.
+   * -      ippStsOutOfRangeErr     
+     -  Indicates an error condition if digestBitsize is not positive multiple of 8 integer.
 
 
 
diff --git a/doc/source/hashpack-hashunpack.rst b/doc/source/hashpack-hashunpack.rst
@@ -102,6 +102,8 @@ Return Values
      -     Indicates an error condition in a ippsHashPack_rmf call if the context parameter does not match the operation.
    * -     ippStsNoMem
      -     Indicates an error condition if the value of bufferSize is less than the size of the IppsHashState_rmf context.
+   * -     ippStsNotSupportedModeErr
+     -     Indicates an error condition if the provided hash algorithm identifier is not supported.
 
 
 
diff --git a/doc/source/hashstatemethodset.rst b/doc/source/hashstatemethodset.rst
@@ -50,6 +50,18 @@ IppStatus ippsHashStateMethodSet_SHA512_224_NI(IppsHashState_rmf* pState, IppsHa
 
 IppStatus ippsHashStateMethodSet_SHA512_224_TT(IppsHashState_rmf* pState, IppsHashMethod* pMethod)
 
+IppStatus ippsHashStateMethodSet_SHA3_224(IppsHashState_rmf* pState, IppsHashMethod* pMethod)
+
+IppStatus ippsHashStateMethodSet_SHA3_256(IppsHashState_rmf* pState, IppsHashMethod* pMethod)
+
+IppStatus ippsHashStateMethodSet_SHA3_384(IppsHashState_rmf* pState, IppsHashMethod* pMethod)
+
+IppStatus ippsHashStateMethodSet_SHA3_512(IppsHashState_rmf* pState, IppsHashMethod* pMethod)
+
+IppStatus ippsHashStateMethodSet_SHAKE128(IppsHashState_rmf* pState, IppsHashMethod* pMethod, int digestBitsize)
+
+IppStatus ippsHashStateMethodSet_SHAKE256(IppsHashState_rmf* pState, IppsHashMethod* pMethod, int digestBitsize)
+
 Include Files
 -------------
 
@@ -66,6 +78,8 @@ Parameters
      - Pointer to the ``IppsHashState_rmf`` context being updated. 
    * - pMethod
      - Pointer to the method for the update of the context.
+   * - digestBitsize
+     - The size of output digest in bits. Should be positive multiple of 8 integer.
 		 
 	  
 Description
@@ -90,5 +104,7 @@ Return Values
      - Indicates no errors. Any other value indicates an error or warning.
    * - ippStsNullPtrErr
      - Indicates an error condition if any of the specified pointers are NULL.
+   * - ippStsOutOfRangeErr     
+     - Indicates an error condition if digestBitsize is not positive multiple of 8 integer.
  
 
diff --git a/doc/source/hashupdate.rst b/doc/source/hashupdate.rst
@@ -90,6 +90,8 @@ Return Values
 
            * The length of the input data stream is less than zero.
            * The length of the totally processed stream (including the current update request) exceeds the limit defined by the particular hash algorithm.
+   * -     ippStsNotSupportedModeErr
+     -     Indicates an error condition if the provided hash algorithm identifier is not supported.
 
 
 
diff --git a/doc/source/mgf1_rmf-mgf2_rmf.rst b/doc/source/mgf1_rmf-mgf2_rmf.rst
@@ -81,6 +81,10 @@ Return Values
      -  Indicates an error condition if any of the specified pointers is NULL
    * -     ippStsLengthErr   
      -  Indicates an error condition if any of the specified lengths is negative or zero.
+   * -     ippStsNotSupportedModeErr
+     -  Indicates an error condition if the provided hash algorithm identifier is not supported.
+   * -     ippStsMemAllocErr
+     -  An internal functional error. If this output status appears, update to the latest version of the library or contact `Intel <https://github.com/intel/cryptography-primitives/issues>`_.
 
 
 
diff --git a/doc/source/one-way-hash-primitives.rst b/doc/source/one-way-hash-primitives.rst
@@ -33,6 +33,7 @@ The :ref:`Hash Functions <hash-functions>`
 section describes functions that implement the following hash algorithms
 for streaming messages: MD5 :term:`RFC 1321 <[RFC 1321]>`,
 SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 :term:`FIPS PUB 180-2 <[FIPS PUB 180-2]>`,
+SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256 :term:`FIPS PUB 202 <[FIPS PUB 202]>`,
 and SM3 :term:`SM3 <[SM3]>`.
 These algorithms are widely used in enterprise applications nowadays.
 
@@ -81,9 +82,25 @@ hash algorithm as shown in the table below.
      -     MD5
    * -      ippHashAlg_SM3
      -     SM3
+   * -     ippHashAlg_SHA3_224*
+     -     SHA3-224
+   * -     ippHashAlg_SHA3_256*
+     -     SHA3-256
+   * -     ippHashAlg_SHA3_384*
+     -     SHA3-384
+   * -     ippHashAlg_SHA3_512*
+     -     SHA3-512
+   * -     ippHashAlg_SHAKE128*
+     -     SHAKE128
+   * -     ippHashAlg_SHAKE256*
+     -     SHAKE256
 
 
 
+`* - supported by reduced memory footprint functions only. The support of the SHA3 family 
+algorithm was added only for reduced memory footprint(_rmf) functions, the functionality 
+of the deprecated API was not extended.`
+
 
 Reduced Memory Footprint Functions
 ----------------------------------
@@ -169,6 +186,18 @@ the syntax.
      -      SM3 (using the SM3 instruction set)
    * -      ippsHashMethod_SM3_TT
      -      SM3 (using the Intel® SM3 instruction set if it is available at run time)
+   * -      ippsHashMethod_SHA3_224
+     -      SHA3_224 (without the Intel® SHA-NI instruction set)
+   * -      ippsHashMethod_SHA3_256
+     -      SHA3_256 (without the Intel® SHA-NI instruction set)
+   * -      ippsHashMethod_SHA3_384
+     -      SHA3_384 (without the Intel® SHA-NI instruction set)
+   * -      ippsHashMethod_SHA3_512
+     -      SHA3_512 (without the Intel® SHA-NI instruction set)
+   * -      ippsHashMethod_SHAKE128
+     -      SHAKE128 (without the Intel® SHA-NI instruction set)
+   * -      ippsHashMethod_SHAKE256
+     -      SHAKE256 (without the Intel® SHA-NI instruction set)
 
 
 
diff --git a/doc/source/rsa_mb_sign_pkcs1v15_rmf.rst b/doc/source/rsa_mb_sign_pkcs1v15_rmf.rst
@@ -125,6 +125,8 @@ Return Values
      -     Indicates a mismatch between types of private keys or exponents ``e`` in public keys.
    * -     ippStsContextMatchErr
      -     No valid keys were found.
+   * -     ippStsNotSupportedModeErr
+     -     Indicates an error condition if the provided hash algorithm identifier is not supported.
 
 
 .. rubric:: Related Information
diff --git a/doc/source/rsa_mb_sign_pss_rmf.rst b/doc/source/rsa_mb_sign_pss_rmf.rst
@@ -130,6 +130,8 @@ Return Values
      -     Indicates a mismatch between types of private keys or exponents ``e`` in public keys.
    * -     ippStsContextMatchErr
      -     No valid keys were found.
+   * -     ippStsNotSupportedModeErr
+     -     Indicates an error condition if the provided hash algorithm identifier is not supported.
 
 
 .. rubric:: Related Information
diff --git a/doc/source/rsa_mb_verify_pkcs1v15_rmf.rst b/doc/source/rsa_mb_verify_pkcs1v15_rmf.rst
@@ -123,6 +123,8 @@ Return Values
      -     Indicates a mismatch between exponents ``e`` in public keys.
    * -     ippStsContextMatchErr
      -     No valid keys were found.
+   * -     ippStsNotSupportedModeErr
+     -     Indicates an error condition if the provided hash algorithm identifier is not supported.
 
 
 
diff --git a/doc/source/rsa_mb_verify_pss_rmf.rst b/doc/source/rsa_mb_verify_pss_rmf.rst
@@ -123,6 +123,8 @@ Return Values
      -     Indicates a mismatch between exponents ``e`` in public keys.
    * -     ippStsContextMatchErr
      -     No valid keys were found.
+   * -     ippStsNotSupportedModeErr
+     -     Indicates an error condition if the provided hash algorithm identifier is not supported.
 
 
 
diff --git a/sources/ippcp/hash/sha3/pcpsha3ca.c b/sources/ippcp/hash/sha3/pcpsha3ca.c
@@ -59,6 +59,8 @@ __IPPCP_INLINE Ipp64u cp_rotl64(Ipp64u lane, Ipp64u bits)
     // reduce rotation to max 63 bits to avoid losing bits
     bits %= 64;
 
+    if (bits == 0)
+        return lane;
     return (lane << bits) | (lane >> (64 - bits));
 }
 
@@ -88,7 +90,7 @@ IPP_OWN_DEFN(void, cp_keccak_kernel, (Ipp64u state[5 * 5]))
         }
 
         // FIPS PUB 202 - SHA-3 Standard, 3.2.2 Specification of rho
-        for (int i = 0; i < (5 * 5); i++) {
+        for (int i = 1; i < (5 * 5); i++) {
             state[i] = cp_rotl64(state[i], KECCAK_RHO_OFFSETS[i]);
         }
 
