Danger

This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns. You may instead be interested in Fernet (symmetric encryption) .

Symmetric encryption

Symmetric encryption is a way to encrypt or hide the contents of material where the sender and receiver both use the same secret key. Note that symmetric encryption is not sufficient for most applications because it only provides secrecy but not authenticity. That means an attacker can’t see the message but an attacker can create bogus messages and force the application to decrypt them. In many contexts, a lack of authentication on encrypted messages can result in a loss of secrecy as well.

For this reason in nearly all contexts it is necessary to combine encryption with a message authentication code, such as HMAC , in an “encrypt-then-MAC” formulation as described by Colin Percival . cryptography includes a recipe named Fernet (symmetric encryption) that does this for you. To minimize the risk of security issues you should evaluate Fernet to see if it fits your needs before implementing anything using this module. If Fernet (symmetric encryption) is not appropriate for your use-case then you may still benefit from Authenticated encryption which combines encryption and authentication securely.

class cryptography.hazmat.primitives.ciphers. Cipher ( algorithm , mode ) [source]

Cipher objects combine an algorithm such as AES with a mode like CBC or CTR . A simple example of encrypting and then decrypting content with AES is: 

>>> import os
>>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
>>> key = os.urandom(32)
>>> iv = os.urandom(16)
>>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv))
>>> encryptor = cipher.encryptor()
>>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
>>> decryptor = cipher.decryptor()
>>> decryptor.update(ct) + decryptor.finalize()
b'a secret message'
Parameters :
Raises :

cryptography.exceptions.UnsupportedAlgorithm – This is raised if the provided algorithm is unsupported.

encryptor ( ) [source]
Returns :

An encrypting CipherContext instance.

If the requested combination of algorithm and mode is unsupported an UnsupportedAlgorithm exception will be raised.

decryptor ( ) [source]
Returns :

A decrypting CipherContext instance.

If the requested combination of algorithm and mode is unsupported an UnsupportedAlgorithm exception will be raised.

Algorithms

class cryptography.hazmat.primitives.ciphers.algorithms. AES ( key ) [source]

AES (Advanced Encryption Standard) is a block cipher standardized by NIST. AES is both fast, and cryptographically strong. It is a good default choice for encryption.

Parameters :

key ( bytes-like ) – The secret key. This must be kept secret. Either 128 , 192 , or 256 bits long.

class cryptography.hazmat.primitives.ciphers.algorithms. AES128 ( key ) [source]

Added in version 38.0.0.

An AES class that only accepts 128 bit keys. This is identical to the standard AES class except that it will only accept a single key length.

Parameters :

key ( bytes-like ) – The secret key. This must be kept secret. 128 bits long.

class cryptography.hazmat.primitives.ciphers.algorithms. AES256 ( key ) [source]

Added in version 38.0.0.

An AES class that only accepts 256 bit keys. This is identical to the standard AES class except that it will only accept a single key length.

Parameters :

key ( bytes-like ) – The secret key. This must be kept secret. 256 bits long.

class cryptography.hazmat.primitives.ciphers.algorithms. Camellia ( key ) [source]

Camellia is a block cipher approved for use by CRYPTREC and ISO/IEC. It is considered to have comparable security and performance to AES but is not as widely studied or deployed.

Parameters :

key ( bytes-like ) – The secret key. This must be kept secret. Either 128 , 192 , or 256 bits long.

class cryptography.hazmat.primitives.ciphers.algorithms. ChaCha20 ( key , nonce ) [source]

Added in version 2.1.

Note

In most cases users should use ChaCha20Poly1305 instead of this class. ChaCha20 alone does not provide integrity so it must be combined with a MAC to be secure. ChaCha20Poly1305 does this for you.

ChaCha20 is a stream cipher used in several IETF protocols. While it is standardized in RFC 7539 , this implementation is not RFC-compliant . This implementation uses a 64 bits counter and a 64 bits nonce as defined in the original version of the algorithm, rather than the 32/96 counter/nonce split defined in RFC 7539 .

Parameters :

  • key ( bytes-like ) – The secret key. This must be kept secret. 256 bits (32 bytes) in length.

  • nonce ( bytes-like ) – Should be unique, a nonce . It is critical to never reuse a nonce with a given key. Any reuse of a nonce with the same key compromises the security of every message encrypted with that key. The nonce does not need to be kept secret and may be included with the ciphertext. This must be 128 bits in length. The 128-bit value is a concatenation of the 8-byte little-endian counter and the 8-byte nonce.

Note

In the original version of the algorithm the nonce is defined as a 64-bit value that is later concatenated with a block counter (encoded as a 64-bit little-endian). If you have a separate nonce and block counter you will need to concatenate it yourself before passing it. For example, if you have an initial block counter of 2 and a 64-bit nonce the concatenated nonce would be struct.pack("<Q", 2) + nonce . 

>>> import struct, os
>>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
>>> nonce = os.urandom(8)
>>> counter = 0
>>> full_nonce = struct.pack("<Q", counter) + nonce
>>> algorithm = algorithms.ChaCha20(key, full_nonce)
>>> cipher = Cipher(algorithm, mode=None)
>>> encryptor = cipher.encryptor()
>>> ct = encryptor.update(b"a secret message")
>>> decryptor = cipher.decryptor()
>>> decryptor.update(ct)
b'a secret message'