Cryptographic Structs#

Hashes#

class caterpillar.py.Algorithm(create: Callable[[_ContextLike], Any] | None = None, update: Callable[[Any, bytes, _ContextLike], Any] | None = None, digest: Callable[[Any, _ContextLike], bytes] | None = None, name: str | None = None)[source]#

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.py.Digest(algorithm: Algorithm, struct: _StructLike, name: str | None = None, verify: bool = False, path: str | None = None)[source]#

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

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.

Ciphers#

class caterpillar.fields.Encrypted(length: int | ellipsis | _ContextLambda, algorithm: Type[CipherAlgorithm], mode: Type[Mode] | Mode, padding: Padding | Type[Padding] = None, algo_args: Iterable[_ContextLambda | Any] | None = None, mode_args: Iterable[_ContextLambda | Any] | None = None, padding_args: Iterable[_ContextLambda | Any] | None = None, post: _StructLike | None = 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: _ContextLike) → CipherAlgorithm[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: _ContextLike) → Mode[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: _ContextLike) → 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_: type, field: Any, args: Any, context: _ContextLambda) → Any[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: Any, context: _ContextLike) → None[source]#

Pack a single element.

Parameters:

  • obj (Any) – The element to pack.

  • context (_ContextLike) – The current operation context.

unpack_single(context: _ContextLike) → memoryview[source]#

Unpack a single element.

Parameters:

context (_ContextLike) – The current operation context.

Returns:

The unpacked element as a memoryview.

Return type:

memoryview

Standard interface#

TODO default functions