crypto module¶

Crypto functions for implementing your secure file store client.

class crypto.Crypto¶

Bases: object

A class grouping together all of the Crypto API functions.

We provide a set of symmetric key ciphers, block cipher modes of operation, and cryptographic hash functions to select from. You must pass the name of the cipher, mode, or function you desire to the respective methods in the API. These names are defined in the dictionaries name_to_cipher, name_to_mode, and name_to_hash.

Ciphers:

‘AES’, ‘ARC2’, ‘ARC4’, ‘Blowfish’, ‘CAST’, ‘DES’, ‘DES3’, ‘XOR’

See the PyCrypto Cipher package for more details.

Modes:

‘ECB’, ‘CBC’, ‘CFB’, ‘OFB’, ‘CTR’

See the PyCrypto blockalgo module for more details.

Hash Functions:

‘MD2’, ‘MD4’, ‘MD5’, ‘RIPEMD’, ‘SHA’, ‘SHA224’, ‘SHA256’, ‘SHA384’, ‘SHA512’

See the PyCrypto Hash package for more details.

asymmetric_decrypt(ciphertext, private_key)¶

Produce the PKCS#1 OAEP decryption of the ciphertext.

See the PyCrypto PKCS1_OAEP module for more information about the underlying implementation.

Parameters:	ciphertext (str) – The ciphertext that contains the message to recover. private_key (An RSA key object) – The private key to decrypt with.
Returns:	The original message
Return type:	str
Raises:	CryptoError – If the decryption fails.

asymmetric_encrypt(message, public_key)¶

Produce the PKCS#1 OAEP encryption of the message.

See the PyCrypto PKCS1_OAEP module for more information about the underlying implementation. PKCS#1 OAEP is a secure public-key encryption scheme – it is semantically secure against adaptive chosen-ciphertext attacks.

Parameters:	message (str or bytes) – The message to encrypt. It can be of variable length, but not longer than the RSA modulus (in bytes) minus 2, minus twice the hash output size (64 bytes). For 2048 bit keys, this gives 2048/8-2-64 = 190 bytes. public_key (An RSA key object) – The public key to encrypt with.
Returns:	The ciphertext in which the message is encrypted.
Return type:	str
Raises:	CryptoError – If message is not a string. ValueError – If the RSA key length is not sufficiently long to deal with the given message.

asymmetric_sign(message, private_key)¶

Produce the PKCS#1 PSS RSA signature of the message.

See the PyCrypto PKCS1_PSS module for more information about the underlying implementation. PKCS#1 PSS is a secure signature scheme.

Parameters:	message (str) – The message to sign. private_key (An RSA key object) – The private key to sign with.
Returns:	The signature.
Return type:	str
Raises:	CryptoError – If message is not a string. ValueError – If the RSA key length is not sufficiently long to deal with the given hash algorithm (SHA512). TypeError – If the RSA key has no private half.

asymmetric_verify(message, signature, public_key)¶

Verify that a PKCS#1 PSS RSA signature is authentic.

See the PyCrypto PKCS1_PSS module for more information about the underlying implementation.

Parameters:	message (str) – The original message. signature (str) – The signature to be verified. public_key (An RSA key object) – The public key of the signer.
Returns:	True if verification is correct. False otherwise.
Return type:	bool
Raises:	CryptoError – If message or signature are not strings.

cryptographic_hash(message, hash_name=None)¶

Generates the printable digest of message using the named hash function.

See the PyCrypto HashAlgo class for more information about the underlying implementation.

Parameters:	message (str) – The message to hash. hash_name (str) – Hash to use, chosen from name_to_hash table.
Returns:	The digest, a string of 2*digest_size characters. Contains only hexadecimal digits.
Return type:	str
Raises:	CryptoError – If name of hash is invalid, or message is not a string.

get_random_bytes(n)¶

Returns n bytes of cryptographically-strong randomness, as a hex-encoded string.

Uses the underlying PyCrypto Random package. Under the hood, this will read random bytes from the OS-provided RNG. On POSIX, this is /dev/urandom. On Windows, this is CryptGenRandom.

This method is secure for cryptographic use.

Params int n:	Number of random bytes to generate.
Returns:	n cryptographically-strong random bytes, as a hex-encoded string
Return type:	str

message_authentication_code(message, key, hash_name=None)¶

Generates the printable MAC of the message.

This uses an HMAC, so you must provide the hash function to use, chosen from the name_to_hash table.

See the PyCrypto HMAC module for more information about the underlying implementation.

Parameters:	message (str) – The message to authenticate. key (str) – Key for the MAC. A string containing the hex-encoded bytes of the key. hash_name (str) – Hash to use, chosen from name_to_hash table.
Returns:	The authentication tag, a string of 2*digest_size bytes. Contains only hexadecimal digits.
Return type:	str
Raises:	CryptoError – If name of hash is invalid, or if the key or message are not strings.

new_counter(nbits, initial_value=1, prefix='', suffix='')¶

A fast counter implementation for use with block ciphers in CTR mode.

See the PyCrypto Counter module for more information about the underlying implementation.

To use with crypto.Crypto.symmetric_encrypt() and crypto.Crypto.symmetric_decrypt(), use this method to create a new Counter object and pass it as the counter argument.

Parameters:	nbits (int) – Length of the desired counter, in bits. It must be a multiple of 8. initial_value (int) – The initial value of the counter. Default value is 1. prefix (str) – The constant prefix of the counter block. A hex-encoded string of bytes. By default, no prefix is used. suffix (str) – The constant suffix of the counter block. A hex-encoded string of bytes. By default, no suffix is used.
Returns:	A new stateful counter callable object.

symmetric_decrypt(ciphertext, key, cipher_name=None, mode_name='ECB', IV=None, iv=None, counter=None, ctr=None, segment_size=None, **kwargs)¶

Decrypt data with the key for the chosen parameters.

You must select a cipher name from the table name_to_cipher. You must provide all parameters required for your chosen cipher.

This function will automatically unpad the decrypted message.

See PyCrypto BlockAlgo class for more information about the underlying implementation.

Parameters:	ciphertext (str) – The piece of data to decrypt. key (str) – The secret key to use in the symmetric cipher. Length varies depending on the cipher chosen. A string containing the hex-encoded bytes of the key. cipher_name (str) – Cipher to use, chosen from name_to_cipher table. mode_name (str) – Block mode of operation to use, chosen from name_to_mode table. Defaults to EBC mode. IV (str) – The initialization vector to use for encryption or decryption. It is ignored for MODE_ECB and MODE_CTR. For all other modes, it must be block_size bytes longs. Optional – when not present it will be given a default value of all zeroes. A string containing the hex-encoded bytes of the IV. counter (callable) – (Only MODE_CTR) A stateful function that returns the next counter block, which is a byte string of block_size bytes. It is recommended to use crypto.Crypto.new_counter() to create a new counter object to pass as the parameter. segment_size (int) – (Only MODE_CFB) The number of bits the plaintext and ciphertext are segmented in. It must be a multiple of 8. If 0 or not specified, it will be assumed to be 8.
Returns:	the decrypted data
Return type:	str
Raises:	CryptoError – If the cipher or mode name is invalid, or the unpadding fails, or if ciphertext or key are not a strings.

symmetric_encrypt(message, key, cipher_name=None, mode_name='ECB', IV=None, iv=None, counter=None, ctr=None, segment_size=None, **kwargs)¶

Encrypt data with the key for the chosen parameters.

You must select a cipher name from the table name_to_cipher. You must provide all parameters required for your chosen cipher.

This function will automatically pad the message to a multiple of the block size.

See PyCrypto BlockAlgo class for more information about the underlying implementation.

Parameters:	message (str) – The piece of data to encrypt. key (str) – The secret key to use in the symmetric cipher. Length varies depending on the cipher chosen. A string containing the hex-encoded bytes of the key. cipher_name (str) – Cipher to use, chosen from name_to_cipher table. mode_name (str) – Block mode of operation to use, chosen from name_to_mode table. Defaults to EBC mode. IV (str) – The initialization vector to use for encryption or decryption. It is ignored for MODE_ECB and MODE_CTR. For all other modes, it must be block_size bytes longs. Optional – when not present it will be given a default value of all zeroes. A string containing the hex-encoded bytes of the IV. counter (callable) – (Only MODE_CTR) A stateful function that returns the next counter block, which is a byte string of block_size bytes. It is recommended to use crypto.Crypto.new_counter() to create a new counter object to pass as the parameter. segment_size (int) – (Only MODE_CFB) The number of bits the plaintext and ciphertext are segmented in. It must be a multiple of 8. If 0 or not specified, it will be assumed to be 8.
Returns:	the encrypted data
Return type:	str, as long as the plaintext
Raises:	CryptoError – If the cipher or mode name is invalid, or if message or key are not a strings.

exception crypto.CryptoError¶

Bases: RuntimeError

An error which will be raised if anything happens wrong in any of the cryptographic methods.

A CryptoError is raised when a function is called with invalid parameters (such as an invalid ciphername), or is called with the wrong types of arguments (not string for message, ciphertext, or symmetric key), or when an operation fails (such as trying to unpad an invalid padding).