crypto - Extended functionality from the base64 and hashlib libraries

Purpose:

This module provides a light wrapper around the base64 and hashlib libraries to provide some additional functionality.

Platform:

Linux/Windows | Python 3.7+

Developer:

J Berendt

Email:

support@s3dev.uk

Comments:

n/a

Example:

Example code use:

>>> from utils4.crypto import crypto

To obtain a quick MD5 hash:

>>> s = "The quick brown fox jumps over the lazy dog"
>>> output = crypto.md5(s)
>>> print(output)

9e107d9d372bb6826bd81d3542a419d6

To obtain a Base64 encoded MD5 hash:

>>> s = "The quick brown fox jumps over the lazy dog"
>>> output = crypto.b64md5(s)
>>> print(output)

OWUxMDdkOWQzNzJiYjY4MjZiZDgxZDM1NDJhNDE5ZDY=

For examples on checksumming a file, please refer to:

Crypto.checksum_crc32()

Crypto.checksum_md5()

Crypto.checksum_sha1()

Crypto.checksum_sha256()

Crypto.checksum_sha512()

class crypto.Crypto[source]

Main class used for hashing and encoding.

This class acts as a simple wrapper around the base64 and hashlib libraries, providing additional functionality.

b64(data: str, decode: bool = True) → bytes | str[source]

Create an encoded or decoded Base64 encryption.

Parameters:

data (str) – String to be encoded. If a str data type is received, it is encoded to bytes before encoding.
decode (bool, optional) – Return a decoded string. Defaults to True.

Returns:

An encoded or decoded Base64 encrypted string.

Return type:

Union[bytes, str]

b64md5(data: iter | str, trunc: int = None) → str[source]

Create an optionally truncated Base64 encoded MD5 hash from a string or array.

Parameters:

data (Union[iter, str]) – A string or an iterable object containing strings to be encoded.
trunc (int, optional) – Truncate the Base64 string to (n) characters. As string slicing is used, values such as -1 are also valid. Defaults to None.

Returns:

An (optionally truncated) Base64 encoded MD5 hash of the passed string or iterable.

Return type:

str

static checksum_crc32(path: str, return_integer: bool = False) → int | str[source]

Generate a 32-bit CRC32 checksum for the given file.

Parameters:

path (str) – Full path to the file.
return_integer (bool, optional) – Return the original unsigned 32-bit integer, rather than the hex string. Defaults to False.

Important

This algorithm is not cryptographically strong and should not be used for authentication or digital signatures; nor is it suitable for use as a general hash algorithm.

– zlib.crc32 Documentation

Design:

This method breaks the file into 32768-byte chunks for more memory efficient reading. Meaning this method has a maximum memory use overhead of ~32K.

Example:

Example for calculating the crc32 checksum for a file, returning a hex string:

>>> from utils4.crypto import crypto

>>> crypto.checksum_crc32(path='/tmp/test.txt')
'2a30e66b'

Example for calculating the crc32 checksum for a file, returning an integer:

>>> from utils4.crypto import crypto

>>> crypto.checksum_crc32(path='/tmp/test.txt', return_integer=True)
707847787

Returns:

If the return_integer value is False (default action), a CRC32 32-bit hex string (checksum string) of the file’s contents is returned. Otherwise, an unsigned 32-bit integer is returned.

Return type:

Union[int, str]

static checksum_md5(path: str) → str[source]

Generate a 128-bit MD5 checksum for the given file.

Parameters:

path (str) – Full path to the file.

Design:

This method breaks the file into 32768-byte chunks (64-bytes * 512 blocks) for more memory efficient reading; taking advantage of the fact that MD5 uses 512-bit (64-byte) digest blocks. Meaning this method has a maximum memory use overhead of ~32K.

Example:

Example calculating the MD5 checksum for a file:

>>> from utils4.crypto import crypto

>>> crypto.checksum_md5(path='/tmp/test.txt')
'9ec06901e8f25eb9810c5e0db88e7dcd'

Returns:

A 128-bit MD5 hex digest (checksum string) of the file’s contents.

Return type:

str

static checksum_sha1(path: str) → str[source]

Generate a 160-bit SHA1 checksum for the given file.

Parameters:

path (str) – Full path to the file.

Design:

This method breaks the file into 32768-byte chunks (64-bytes * 512 blocks) for more memory efficient reading; taking advantage of the fact that SHA1 uses 512-bit (64-byte) digest blocks. Meaning this method has a maximum memory use overhead of ~32K.

Example:

Example calculating the SHA1 checksum for a file:

>>> from utils4.crypto import crypto

>>> crypto.checksum_sha1(path='/tmp/test.txt')
'e49a1493c637a24800119fb53ef7dbc580221e89'

Returns:

A 160-bit SHA1 hex digest (checksum string) of the file’s contents.

Return type:

str

static checksum_sha256(path: str) → str[source]

Generate a 256-bit SHA256 checksum for the given file.

Parameters:

path (str) – Full path to the file.

Design:

This method breaks the file into 32768-byte chunks (64-bytes * 512 blocks) for more memory efficient reading; taking advantage of the fact that SHA256 uses 512-bit (64-byte) digest blocks. Meaning this method has a maximum memory use overhead of ~32K.

Example:

Example calculating the SHA256 checksum for a file:

>>> from utils4.crypto import crypto

>>> crypto.checksum_sha256(path='/tmp/test.txt')
'e899df8e51b60bf8a6ede73fe5c7b4267bf5e48937e848bac3c6efd906833821'

Returns:

A 256-bit SHA256 hex digest (checksum string) of the file’s contents.

Return type:

str

static checksum_sha512(path: str) → str[source]

Generate a 512-bit SHA512 checksum for the given file.

Parameters:

path (str) – Full path to the file.

Design:

This method breaks the file into 32768-byte chunks (128-bytes * 256 blocks) for more memory efficient reading; taking advantage of the fact that SHA512 uses 1024-bit (128-byte) digest blocks. Meaning this method has a maximum memory use overhead of ~32K.

Example:

Example calculating the SHA512 checksum for a file:

>>> from utils4.crypto import crypto

>>> crypto.checksum_sha512(path='/tmp/test.txt')
('247adcb6f5b284b3e45c9281171ba7a6'
 '2502692ee9ee8020bd5827602972409f'
 '9bdfc2ec7e5452223c19b3745d3f04e2'
 '542ef0d0e075139d1ee3b5f678c9aaec')  # Single string

Returns:

A 512-bit SHA512 hex digest (checksum string) of the file’s contents.

Return type:

str

md5(data: str, decode: bool = True) → str[source]

Create an optionally encoded or decoded MD5 hash.

Parameters:

data (str) – String to be hashed. If a str data type is passed, it is encoded to bytes before hashing.
decode (bool, optional) – Return a decoded string. Defaults to True.

Returns:

An encoded or decoded MD5 hash, depending on the value passed to the decode parameter.

Return type:

str

static _encode(data: bytes | str) → bytes[source]

Test if a string is str or bytes before processing.

Parameters:: data (Union[bytes, str]) – String value to be encoded.

If the received data parameter is a str type, it is converted to a bytes type and returned. If the string is already a bytes type, it is returned, unmodified.

Raises:: ValueError – If the data object is neither a str or bytes type.
Returns:: A bytes encoded string.
Return type:: bytes