crypto - Extended functionality from the base64 and hashlib libraries
- Purpose:
This module provides a light wrapper around the
base64
andhashlib
libraries to provide some additional functionality.- Platform:
Linux/Windows | Python 3.7+
- Developer:
J Berendt
- Email:
- 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:
- class crypto.Crypto[source]
Main class used for hashing and encoding.
This class acts as a simple wrapper around the
base64
andhashlib
libraries, providing additional functionality.- static _encode(data: bytes | str) bytes [source]
Test if a string is
str
orbytes
before processing.- Parameters:
data (Union[bytes, str]) – String value to be encoded.
If the received
data
parameter is astr
type, it is converted to abytes
type and returned. If the string is already abytes
type, it is returned, unmodified.- Raises:
ValueError – If the
data
object is neither astr
orbytes
type.- Returns:
A
bytes
encoded string.- Return type:
bytes
- 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 tobytes
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 isFalse
(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 tobytes
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