SHA

How to use the crypto_condor.primitives.SHA module to test implementations of the SHA-1, SHA-2, and SHA-3 families of hash functions.

Supported parameters

The supported algorithms are defined by the Algorithm enum.

Implementations can be either bit- or byte-oriented. To select an orientation use the Orientation enum.

enum crypto_condor.primitives.SHA.Algorithm(value)

Supported hash algorithms.

Member Type:

str

Valid values are as follows:

SHA_1 = <Algorithm.SHA_1: 'SHA-1'>
SHA_224 = <Algorithm.SHA_224: 'SHA-224'>
SHA_256 = <Algorithm.SHA_256: 'SHA-256'>
SHA_384 = <Algorithm.SHA_384: 'SHA-384'>
SHA_512 = <Algorithm.SHA_512: 'SHA-512'>
SHA_512_224 = <Algorithm.SHA_512_224: 'SHA-512/224'>
SHA_512_256 = <Algorithm.SHA_512_256: 'SHA-512/256'>
SHA3_224 = <Algorithm.SHA3_224: 'SHA3-224'>
SHA3_256 = <Algorithm.SHA3_256: 'SHA3-256'>
SHA3_384 = <Algorithm.SHA3_384: 'SHA3-384'>
SHA3_512 = <Algorithm.SHA3_512: 'SHA3-512'>
enum crypto_condor.primitives.SHA.Orientation(value)

Orientation of the implementation.

Member Type:

str

Valid values are as follows:

BIT = <Orientation.BIT: 'bit'>
BYTE = <Orientation.BYTE: 'byte'>

Test an implementation directly

crypto_condor.primitives.SHA.test(hash_function, hash_algorithm, orientation=Orientation.BYTE)

Tests a SHA implementation.

Runs NIST test vectors on the given function. The function to test must conform to the HashFunction protocol.

Parameters:

  • hash_function (HashFunction) – The implementation to test.

  • hash_algorithm (Algorithm) – The hash algorithm implemented by hash_function.

  • orientation (Orientation) – The orientation of the implementation, either bit- or byte-oriented.

Returns:

A ResultsDict containing the results of short message (short), long message (long), and Monte-Carlo (monte-carlo) tests.

Return type:

ResultsDict

Example

First import the SHA module.

>>> from crypto_condor.primitives import SHA

Let’s test PyCryptodome’s implementation of SHA-256. For this, we need to wrap the SHA256 class so it behaves like HashFunction.

>>> from Crypto.Hash import SHA256

>>> def my_sha256(data: bytes) -> bytes:
...     return SHA256.new(data=data).digest()

We define the parameters to test.

>>> algorithm = SHA.Algorithm.SHA_256
>>> orientation = SHA.Orientation.BYTE

And call test() on our function and selected parameters.

>>> results_dict = SHA.test(my_sha256, algorithm, orientation)
[NIST] ...
>>> assert results_dict.check()

Test the output of an implementation

crypto_condor.primitives.SHA.verify_file(filename, hash_algorithm)

Verifies SHA hashes.

Tests hashes from a file. The file must follow the format described below.

Format:

  • One set of arguments per line.

  • Lines are separated by newlines (\n).

  • Lines that start with ‘#’ are counted as comments and ignored.

  • Arguments are written in hexadecimal and separated by slashes.

  • The order of arguments is:

message/hash
Parameters:

  • filename (str) – Name of the file to test.

  • hash_algorithm (Algorithm) – Hash algorithm used to generate the hashes.

Returns:

The results of hashing the message with the internal implementation and comparing with the expected output.

Return type:

Results

Example

First import the SHA module.

>>> from crypto_condor.primitives import SHA

Let’s generate a file of random messages and their hash.

>>> import random
>>> filename = "/tmp/crypto-condor-test/SHA-256-verify.txt"
>>> algorithm = SHA.Algorithm.SHA_256
>>> with open(filename, "w") as file:
...     for i in range(20):
...         message = random.randbytes(64)
...         digest = SHA._sha(algorithm, message)
...         line = f"{message.hex()}/{digest.hex()}\n"
...         _ = file.write(line)

We call verify_file() on our test file.

>>> results = SHA.verify_file(filename, algorithm)
Testing ...
>>> assert results.check()

Run a wrapper

Note

Available wrappers are defined by Wrapper.

crypto_condor.primitives.SHA.run_wrapper(wrapper, hash_algorithm, orientation)

Runs the corresponding wrapper.

Parameters:

  • wrapper (Path) – The wrapper to test.

  • language – The language of the wrapper to run.

  • hash_algorithm (Algorithm) – The hash algorithm to test.

  • orientation (Orientation) – The orientation of the implementation, either bit- or byte-oriented.

Returns:

A ResultsDict containing the results of short message (short), long message (long), and Monte-Carlo (monte-carlo) tests.

Return type:

ResultsDict

enum crypto_condor.primitives.SHA.Wrapper(value)

Defines the available wrappers.

Member Type:

str

Valid values are as follows:

PYTHON = <Wrapper.PYTHON: 'Python'>
C = <Wrapper.C: 'C'>

Protocols

protocol crypto_condor.primitives.SHA.HashFunction

Represents a hash function.

Hash functions must behave like __call__ to be tested with this module.

Classes that implement this protocol must have the following methods / attributes:

__call__(data)

Hashes the given data.

Parameters:

data (bytes) – The input data.

Returns:

The resulting hash.

Return type:

bytes