securitylib.advanced_crypto — Advanced cryptographic functions library¶

securitylib.advanced_crypto.hash(data, length=32, iterations=1)¶

This function will generate a hashed representation of the data. We want it to be simple, but for advanced usage you can set the length in bytes and the number of iterations.

Parameters:	data (str) – The data to be hashed. length (int) – The length of the output that we want, in bytes. iterations (int) – The number of iterations.
Returns:	str – The generated hash in byte string.

securitylib.advanced_crypto.generate_authenticator(data, authenticator_key, length=32, iterations=1)¶

Alias for the hmac() function.

securitylib.advanced_crypto.hmac(data, hmac_key, length=32, iterations=1)¶

This function will generate an HMAC of the data (provides authentication and integrity). We want it to be simple, but for advanced usage you can set the length in bytes and the number of iterations.

Parameters:	data (str) – The data to be hashed. hmac_key (str) – The secret key to be used by the HMAC, in byte string. You can use generate_hmac_key() to generate it. length (int) – The length of the output that we want, in bytes. iterations (int) – The number of iterations.
Returns:	str – The generated hmac in byte string.

securitylib.advanced_crypto.validate_authenticator(data, authenticator_key, authenticator, length=32, iterations=1)¶

Alias for the validate_hmac() function.

securitylib.advanced_crypto.validate_hmac(data, hmac_key, authenticator, length=32, iterations=1)¶

This function will validate a given HMAC authenticator against the HMAC of the data. Use this function instead of performing the comparison yourself, because it avoids timing attacks.

Parameters:	data (str) – The data protected by the HMAC authenticator. hmac_key (str) – The secret key used to generate the given HMAC authenticator, in byte string. authenticator (str) – The HMAC authenticator you want to compare, in byte string. length (int) – The length used to generate the given HMAC authenticator. iterations (int) – The number of iterations used to generate the given HMAC authenticator.
Returns:	bool – True if the given HMAC authenticator matches the HMAC of the data, False otherwise.

securitylib.advanced_crypto.safe_compare(val1, val2)¶

Compares two strings to each other. The time taken is independent of the number of characters that match.

Parameters:	val1 (str) – First string for comparison. val2 (str) – Second string for comparison.
Returns:	bool – True if the two strings are equal, False otherwise.

securitylib.advanced_crypto.generate_secret_key(length=16)¶

Generates a key of the given length.

Parameters:	length (int) – Length of the key to generate, in bytes.
Returns:	str – The generated key, in byte string.

securitylib.advanced_crypto.generate_encryption_key()¶

Generates a key for use in the encryption functions and classes.

Returns:	str – The generated key, in byte string.

securitylib.advanced_crypto.generate_authenticator_key()¶

Alias for the generate_hmac_key() function.

securitylib.advanced_crypto.generate_hmac_key()¶

Generates a key for use in the hmac() function.

Returns:	str – The generated key, in byte string.

securitylib.advanced_crypto.generate_encryption_key_from_password(password, salt, iterations=15000, dklen=16, hashfunc=None)¶

Alias for the generate_key_from_password() function.

securitylib.advanced_crypto.generate_authenticator_key_from_password(password, salt, iterations=15000, dklen=32, hashfunc=None)¶

Alias for the generate_key_from_password() function.

securitylib.advanced_crypto.generate_key_from_password(password, salt, iterations=15000, dklen=16, hashfunc=None)¶

Use this function to generate a key from a password.

Parameters:	password (str) – The password from which to generate the key. salt (str) – Salt for the password, in byte string. You can use get_random_token() to generate it. iterations (int) – The number of iterations. dklen (int) – Size of the derived key, in bytes. hashfunc – Hash function from the hashlib module. If none is provided, sha256 is used.
Returns:	str – The generated key, in byte string.

securitylib.advanced_crypto.encrypt(data, key, hmac_key, associated_data=None)¶

Use this function to encrypt data (except streaming data, such as video streaming). Two keys must be provided, one to guarantee confidentiality and another to guarantee integrity.

Parameters:	data (str) – The data to encrypt. key (str) – The key to encrypt the data, in byte string. Provides confidentiality. You can use generate_encryption_key() to generate it. hmac_key (str) – The key to authenticate the data, in byte string. Provides integrity. You can use generate_hmac_key() to generate it. associated_data (str) – Data to be authenticated but not encrypted.
Returns:	str – The encrypted data.

securitylib.advanced_crypto.decrypt(ciphertext, key, hmac_key)¶

Use this function to decrypt data that was encrypted using encrypt(). The same keys used to encrypt the data must be provided to decrypt it.

Parameters:	ciphertext (str) – The encrypted data. key (str) – The key that was used to encrypt the data, in byte string. hmac_key (str) – The key that was used to authenticate the data, in byte string.
Returns:	dict – A dictionary with two keys, “data” with the decrypted data, and “associated_data” with the associated data.

class securitylib.advanced_crypto.BlockCipher(key, hmac_key)¶

Use this class to encrypt or decrypt data (except streaming data, such as video streaming). Use it if you want to encrypt or decrypt multiple pieces of data with the same keys, else you can simply use the encrypt() and decrypt() functions.

In other words, this:

>>> block_cipher = BlockCipher(key, hmac_key)
>>> cta = block_cipher.encrypt(a)
>>> ctb = block_cipher.encrypt(b)
>>> ctc = block_cipher.encrypt(c)

is equivalent to this:

>>> cta = encrypt(key, hmac_key, a)
>>> ctb = encrypt(key, hmac_key, b)
>>> ctc = encrypt(key, hmac_key, c)

Parameters:	key (str) – The key to encrypt or decrypt the data, in byte string. Provides confidentiality. You can use generate_encryption_key() to generate it. hmac_key (str) – The key which was or will be used to authenticate the data, in byte string. Provides integrity. You can use generate_hmac_key() to generate it.

encrypt(data, associated_data=None)¶

Parameters:	data (str) – The data to encrypt. associated_data (str) – Data to be authenticated but not encrypted.
Returns:	str – The encrypted data.

decrypt(ciphertext)¶

Parameters:	ciphertext (str) – The encrypted data.
Returns:	dict – A dictionary with two keys, “data” with the decrypted data, and “associated_data” with the associated data.

class securitylib.advanced_crypto.StreamCipher(key)¶

Use this class to encrypt or decrypt a stream using a stream cipher.

Calling encrypt (or decrypt) multiple times for the same StreamCipher instance is equal to calling it once with the concatenation of the input. In other words, this:

>>> stream_cipher.encrypt(a) + stream_cipher.encrypt(b) + stream_cipher.encrypt(c)

is equivalent to this:

>>> stream_cipher.encrypt(a + b + c)

This property makes this class perfect for streams of data which must be encrypted in chunks instead of all at once.

Beware that this class only provides confidentiality, not integrity, i.e. it does not provide any protection against tampering. An HMAC could be computed over each chunk being encrypted to provide integrity, but this would have a huge overhead if the chunks are very small, so a better solution must be found depending on each specific case.

Parameters:	key (str) – The key to encrypt or decrypt the stream, in byte string. Provides confidentiality. You can use generate_encryption_key() to generate it.

encrypt(stream)¶

Parameters:	stream (str) – The stream to encrypt, or part of it.
Returns:	str – The encrypted cipherstream.

decrypt(cipherstream)¶

Parameters:	cipherstream (str) – The encrypted cipherstream, or part of it.
Returns:	str – The decrypted stream.