SHA-3 (Keccak) for Python

Common errors

• ERROR: Failed building wheel for pysha3

  cause This error typically occurs when attempting to install the unmaintained `pysha3` package on newer Python versions (e.g., Python 3.11+), as it lacks pre-built wheels and its `setup.py` may fail compilation without specific C build tools or for incompatibility reasons.
  fix Install `safe-pysha3` instead, which is actively maintained and provides compatible wheels for modern Python versions: `pip install safe-pysha3`. If a wheel is not available for your specific platform/Python version, ensure you have a C compiler installed.

• Hash outputs do not match between different SHA-3 implementations or versions.

  cause This is often due to the historical change in the SHA-3 standard's padding delimiter. Older `pysha3` versions (<1.0) implemented the pre-NIST Keccak standard, which produces different hashes for 'SHA-3' than the final FIPS202 standard.
  fix Confirm whether you need FIPS202-compliant SHA-3 or the older Keccak variant. If FIPS202 SHA-3, upgrade to `safe-pysha3` and use `hashlib.sha3_xxx()`. If the older Keccak is intentionally desired, use the `keccak_xxx()` functions from `safe-pysha3`'s `sha3` module.

Warnings

• breaking The `pysha3` library version 1.0 (and `safe-pysha3`) is not compatible with `pysha3` versions older than 1.0 regarding standard SHA-3 output. The NIST finalization of SHA-3 changed the delimiter suffix from 0x01 to 0x06, meaning hashes generated by older versions for 'SHA-3' will differ from current FIPS202-compliant versions.
  Fix: Upgrade to `safe-pysha3`. For FIPS202-compliant SHA-3, use `hashlib.sha3_xxx()`. If the pre-NIST Keccak hash is specifically required, use the `keccak_xxx()` functions provided by `safe-pysha3`'s `sha3` module.
• breaking A critical buffer overflow vulnerability (CVE-2022-37454) was present in the underlying Keccak XKCP SHA-3 reference implementation used by `pysha3` and early `safe-pysha3` versions. This flaw could lead to arbitrary code execution or compromise cryptographic properties.
  Fix: Ensure you are using `safe-pysha3` version 1.0.4 or newer. This version specifically includes the fix for CVE-2022-37454.
• deprecated The original `pysha3` package has reached its end of life and is no longer supported, as SHA-3 functionality was merged into Python's standard `hashlib` module in Python 3.6. Using the unmaintained `pysha3` can lead to installation issues and security vulnerabilities.
  Fix: Migrate to `safe-pysha3` for continued support, bug fixes, and compatibility with newer Python versions (3.9-3.13).

Install

• pip install safe-pysha3 Install latest version

Imports

• hashlib.sha3_256
  wrong:

  import sha3
  sha3.SHA3_256()

  correct:

  import hashlib
  hashlib.sha3_256

  For Python 3.6+, SHA-3 functions are integrated into `hashlib`. `safe-pysha3` monkey-patches `hashlib` upon import, making the standard `hashlib` interface the preferred and most compatible way to access SHA-3 algorithms. Direct `sha3` module access is mostly for internal use or older Python versions.
• keccak_256

  from sha3 import keccak_256

  Use `keccak_xxx` functions for the original Keccak (pre-NIST standard) hash if specific compatibility with older implementations is required.

Quickstart

This quickstart demonstrates how to calculate SHA3-256 and SHAKE-128 hashes using the standard `hashlib` interface, which `safe-pysha3` extends. It also shows how to access the `keccak_512` function directly for pre-NIST Keccak hashes.

import hashlib

data = b"Hello, safe-pysha3!"

# Calculate SHA3-256 hash
sha3_256_hasher = hashlib.sha3_256()
sha3_256_hasher.update(data)
print(f"SHA3-256: {sha3_256_hasher.hexdigest()}")

# Calculate SHAKE-128 hash with 32-byte output
shake_128_hasher = hashlib.shake_128()
shake_128_hasher.update(data)
print(f"SHAKE-128 (32 bytes): {shake_128_hasher.hexdigest(32)}")

# Accessing a pre-NIST Keccak hash directly from sha3 module (if needed)
from sha3 import keccak_512
keccak_512_hasher = keccak_512()
keccak_512_hasher.update(data)
print(f"Keccak-512: {keccak_512_hasher.hexdigest()}")