4.8.4. Cryptographic Structs#

4.8.4.1. Hashes#

class caterpillar.fields.Algorithm(create=None, update=None, digest=None, name=None)[source]#

Added in version 2.4.0.

A class representing a cryptographic or checksum algorithm.

This class allows for the creation, updating, and finalization of values using a specified algorithm. It abstracts the necessary methods to interact with hash algorithms or checksums like SHA256 or CRC32.

Example usage with SHA256:

>>> SHA256 = Algorithm(
...     create=lambda context: hashlib.sha256(),
...     update=lambda algo_obj, data, context: algo_obj.update(data),
...     digest=lambda algo_obj, context: algo_obj.digest(),
... )

Example usage with CRC32:

>>> CRC32 = Algorithm(
...     create=lambda context: zlib.crc32(b""),
...     update=lambda crc_value, data, context: crc32(data, crc_value),
...     digest=lambda crc_value, context: crc_value,
... )

This class can be used to handle both cryptographic algorithms and non-cryptographic checksums.

Parameters:

  • create (Callable[[_ContextLike], Any]) – A callable that creates an instance of the algorithm or checksum.

  • update (Callable[[Any, bytes, _ContextLike], Any]) – A callable that updates the algorithm or checksum with new data.

  • digest (Callable[[Any, _ContextLike], bytes]) – A callable that returns the digest or checksum value.

  • name (Optional[str]) – An optional name for the algorithm.

class caterpillar.fields.Digest(algorithm, struct, name=None, verify=False, path=None)[source]#

A class to handle the creation, updating, and verification of digests using a specified algorithm.

Added in version 2.4.0.

Changed in version 2.4.3: Python 3.14 is not supported, use DigestField instead.

The Digest class allows you to integrate hash or checksum algorithms into a struct by installing hooks that manage the digest state during packing and unpacking. It supports automatic calculation and validation of digests during serialization (packing) and deserialization (unpacking).

Example usage:

>>> @struct
... class Format:
...     with Digest(SHA256, Bytes(32), "sha256", verify=True):
...         user_data: Bytes(10)
...

This example defines a struct with a user_data field and a sha256 digest field. The Digest class automatically calculates the SHA256 checksum of user_data during packing and validates the checksum during unpacking.

The resulting struct has the following fields:

>>> Format.__struct__.fields
[
    Action(Digest.begin),
    Field('user_data', struct=<Bytes>),
    Action(Digest.end),
    Field('sha256', struct=<Bytes>),
    Action(Digest.verify)
]

The Action objects install hooks into the current stream for digest calculation and validation. When packing an object, the digest will be updated automatically:

>>> obj = Format(user_data=b"helloworld" * 10)
Format(user_data=b"helloworld", sha256=<_DigestValue>)

On packing, the digest is calculated and included in the serialized output:

>>> pack(obj, Format)
b"hello world\xb9M'\xb9" ...

If verification is enabled, unpacking will check the validity of the digest:

>>> unpack(Format, b"invalid data with sha256")
Traceback (most recent call last):
...
caterpillar.exception.ValidationError: Failed to verify digest of 'sha256'!
- Expected: <expected_digest_value>
- Actual: <actual_digest_value>
Context-Path: <root>.sha256
Parameters:

  • algorithm (Algorithm) – The checksum or cryptographic algorithm used to generate the digest.

  • struct (_StructLike) – The struct to which the digest will be attached.

  • name (Optional[str]) – An optional name for the digest field (defaults to ‘sha256’ or another default name).

  • verify (bool) – Whether to enable verification of the digest upon unpacking. Default is False.

  • path (Optional[str]) – Optional path to the digest field in the context, used for accessing and storing the digest.

class caterpillar.fields.DigestField(target: str, struct, verify=False)[source]#

Added in version 2.4.5.

Represents a field in a struct that stores or verifies a digest.

This struct field computes a digest over all preceding fields and then either:

  • Packs the resulting digest value.

  • Unpacks a stored digest and optionally verifies it.

Example Usage:

@struct
class Format:
    _hash_begin: DigestField.begin("hash", Sha2_256_Algo)
    user_data: Bytes(10)
    hash: Sha2_256_Field("hash", verify=True) = None
Parameters:

  • target (str) – The unique name shared with the corresponding DigestFieldAction.

  • struct (_StructLike) – The struct used to pack/unpack the digest value (e.g., Bytes(32))

  • verify (bool) – Whether to verify the unpacked digest against the computed one.

class caterpillar.fields.DigestFieldAction(target: str, algorithm: Algorithm)[source]#

Added in version 2.4.5.

Represents an Action used to initialize a digest computation before struct processing begins.

This action is intended to be used as a pre-processing step before serializing or parsing struct fields that are to be hashed. It injects a digest hook into the IO stream to intercept and update digest state as data is read or written.

The following context variables will be populated based on the given target: - _digest_obj__<target>: The current state of the digest computation. (hash object) - _digest_hook__<target>: The IO hook associated with the digest computation. - _digest_algo__<target>: The algorithm used for the digest computation.

Parameters:

  • target (str) – The unique name identifying this digest field.

  • algorithm (Algorithm) – The digest algorithm implementation (must support create/update/digest).

4.8.4.2. Ciphers#

class caterpillar.fields.Encrypted(length, algorithm, mode, padding=None, algo_args=None, mode_args=None, padding_args=None, post=None)[source]#

Struct that is able to encrypt/decrypt blocks of memory.

Parameters:

  • length (Union[int, _GreedyType, _ContextLambda]) – Length of the encrypted data.

  • algorithm (Type[algorithms.CipherAlgorithm]) – Encryption algorithm.

  • mode (Union[Type[modes.Mode], modes.Mode]) – Encryption mode.

  • padding (Union[Padding, Type[Padding]], optional) – Padding scheme for encryption.

  • algo_args (Optional[Iterable[_ArgType]], optional) – Additional arguments for the encryption algorithm.

  • mode_args (Optional[Iterable[_ArgType]], optional) – Additional arguments for the encryption mode.

  • padding_args (Optional[Iterable[_ArgType]], optional) – Additional arguments for the padding scheme.

  • post – Post-processing structure.

algorithm(context)[source]#

Get the encryption algorithm instance.

Parameters:

context (_ContextLike) – The current operation context.

Returns:

An instance of the encryption algorithm.

Return type:

algorithms.CipherAlgorithm

mode(context)[source]#

Get the encryption mode instance.

Parameters:

context (_ContextLike) – The current operation context.

Returns:

An instance of the encryption mode.

Return type:

modes.Mode

padding(context) → Padding[source]#

Get the padding scheme instance.

Parameters:

context (_ContextLike) – The current operation context.

Returns:

An instance of the padding scheme.

Return type:

Padding

get_instance(type_, field, args, context)[source]#

Get an instance of a specified type.

Parameters:

  • type (type) – The desired type of the instance.

  • field (Any) – The field or instance.

  • args (Any) – Additional arguments for the instance.

  • context (_ContextLambda) – The current operation context.

Returns:

An instance of the specified type.

Return type:

Any

pack_single(obj, context) → None[source]#

Pack a single element.

Parameters:

  • obj (Any) – The element to pack.

  • context (_ContextLike) – The current operation context.

unpack_single(context)[source]#

Unpack a single element.

Parameters:

context (_ContextLike) – The current operation context.

Returns:

The unpacked element as a memoryview.

Return type:

memoryview

4.8.4.3. Standard interface#

TODO default functions