Utilities

This module exposes different functions which can be useful when dealing with cryptography and workers.

Task handling

wacryptolib.utilities.TaskRunnerStateMachineBase(**kwargs)

State machine for all sensors/players, checking that the order of start/stop/join operations is correct.

The two-steps shutdown (stop(), and later join()) allows caller to efficiently and safely stop numerous runners.

wacryptolib.utilities.PeriodicTaskHandler(interval_s, count=-1, runonstart=True, task_func=None, **kwargs)

This class runs a task at a specified interval, with start/stop/join controls.

If task_func argument is not provided, then _offloaded_run_task() must be overridden by subclass.

Hashing

wacryptolib.utilities.SUPPORTED_HASH_ALGOS = ['SHA256', 'SHA512', 'SHA3_256', 'SHA3_512']

Hash algorithms authorized for use with hash_message()

wacryptolib.utilities.hash_message(message, hash_algo)

Hash a message with the selected hash algorithm, and return the hash as bytes.

Serialization

wacryptolib.utilities.dump_to_json_str(data, **extra_options)

Dump a data tree to a json representation as string. Supports advanced types like bytes, uuids, dates...

wacryptolib.utilities.load_from_json_str(data, **extra_options)

Load a data tree from a json representation as string. Supports advanced types like bytes, uuids, dates...

Raises exceptions.ValidationError on loading error.

wacryptolib.utilities.dump_to_json_bytes(data, **extra_options)

Same as dump_to_json_str, but returns UTF8-encoded bytes.

wacryptolib.utilities.load_from_json_bytes(data, **extra_options)

Same as load_from_json_str, but takes UTF8-encoded bytes as input.

wacryptolib.utilities.dump_to_json_file(filepath, data, **extra_options)

Same as dump_to_json_bytes, but writes data to filesystem (and returns bytes too).

wacryptolib.utilities.load_from_json_file(filepath, **extra_options)

Same as load_from_json_bytes, but reads data from filesystem.

Miscellaneous

wacryptolib.utilities.generate_uuid0(ts=None)

Generate a random UUID partly based on Unix timestamp (not part of official "variants").

Uses 6 bytes to encode the time and does not encode any version bits, leaving 10 bytes (80 bits) of random data.

When just transmitting these UUIDs around, the stdlib "uuid" module does the job fine, no need for uuid0 lib.

Parameters:

ts (Optional[float]) -- optional timestamp to use instead of current time (if not falsey)

Returns:

uuid0 object (subclass of UUID)

wacryptolib.utilities.split_as_chunks(bytestring, *, chunk_size, must_pad, accept_incomplete_chunk=False)

Split a bytestring into chunks (or blocks)

Parameters:

  • bytestring (bytes) -- element to be split into chunks

  • chunk_size (int) -- size of a chunk in bytes

  • must_pad (bool) -- whether the bytestring must be padded first or not

  • accept_incomplete_chunk (bool) -- do not raise error if a chunk with a length != chunk_size is obtained

Return type:

List[bytes]

Returns:

list of bytes chunks

wacryptolib.utilities.recombine_chunks(chunks, *, chunk_size, must_unpad)

Recombine chunks which were previously separated.

Parameters:

  • chunks (Sequence[bytes]) -- sequence of bytestring parts

  • chunk_size (int) -- size of a chunk in bytes (only used for error checking, when unpadding occurs)

  • must_unpad (bool) -- whether the bytestring must be unpadded after recombining, or not

Return type:

bytes

Returns:

initial bytestring