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