Classic modes of operation for symmetric block ciphers¶
A block cipher uses a symmetric key to encrypt data of fixed and very short length (the block size), such as 16 bytes for AES. In order to cope with data of arbitrary length, the cipher must be combined with a mode of operation.
You create a cipher object with the new() function
in the relevant module under Crypto.Cipher:
the first parameter is always the cryptographic key (a byte string)
the second parameter is always the constant that selects the desired mode of operation
Constants for each mode of operation are defined at the module level for each algorithm.
Their name starts with MODE_, for instance Crypto.Cipher.AES.MODE_CBC.
Note that not all ciphers support all modes.
The class of the object returned by new() depends on the mode,
and its full API is at the end of the section of each mode
(for instance, CbcMode for CBC).
For instance:
>>> from Crypto.Cipher import AES
>>> from Crypto.Random import get_random_bytes
>>>
>>> key = get_random_bytes(16)
>>> cipher = AES.new(key, AES.MODE_CBC)
>>>
>>> # You can now use use cipher to encrypt or decrypt...
The state machine for a cipher configured with a classic mode is:
Fig. 2 Generic state diagram for a cipher object¶
What follows is a list of classic modes of operation: they all provide confidentiality but not data integrity (unlike modern AEAD modes, which are described in another section).
ECB mode¶
Electronic CodeBook. The most basic but also the weakest mode of operation. Each block of plaintext is encrypted independently of any other block.
Warning
The ECB mode should not be used because it is semantically insecure. For one, it exposes correlation between blocks.
The new() function at the module level under Crypto.Cipher instantiates
a new ECB cipher object for the relevant base algorithm.
In the following definition, <algorithm> could be AES:
- Crypto.Cipher.<algorithm>.new(key, mode)
Create a new ECB object, using <algorithm> as the base block cipher.
The method encrypt() (and likewise decrypt()) of an ECB cipher object
expects data to have length multiple of the block size (e.g. 16 bytes for AES).
You might need to use Crypto.Util.Padding to align the plaintext to the right boundary.
ECB cipher object¶
- class Crypto.Cipher._mode_ecb.EcbMode¶
Electronic Code Book (ECB).
This is the simplest encryption mode. Each of the plaintext blocks is directly encrypted into a ciphertext block, independently of any other block.
This mode is dangerous because it exposes frequency of symbols in your plaintext. Other modes (e.g. CBC) should be used instead.
See NIST SP800-38A , Section 6.1.
- encrypt(plaintext, output=None)¶
Encrypt data with the key set at initialization.
The data to encrypt can be broken up in two or more pieces and
encryptcan be called multiple times.That is, the statement:
>>> c.encrypt(a) + c.encrypt(b)
is equivalent to:
>>> c.encrypt(a+b)
This function does not add any padding to the plaintext.
- Parameters:
plaintext (bytes/bytearray/memoryview) – The piece of data to encrypt. The length must be multiple of the cipher block length.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the ciphertext must be written to. If
None, the ciphertext is returned.- Return type:
- Returns:
If
outputisNone, the ciphertext is returned asbytes. Otherwise,None.
- decrypt(ciphertext, output=None)¶
Decrypt data with the key set at initialization.
The data to decrypt can be broken up in two or more pieces and
decryptcan be called multiple times.That is, the statement:
>>> c.decrypt(a) + c.decrypt(b)
is equivalent to:
>>> c.decrypt(a+b)
This function does not remove any padding from the plaintext.
- Parameters:
ciphertext (bytes/bytearray/memoryview) – The piece of data to decrypt. The length must be multiple of the cipher block length.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the plaintext must be written to. If
None, the plaintext is returned.- Return type:
- Returns:
If
outputisNone, the plaintext is returned asbytes. Otherwise,None.
CBC mode¶
Ciphertext Block Chaining, defined in NIST SP 800-38A, section 6.2. It is a mode of operation where each plaintext block gets XOR-ed with the previous ciphertext block prior to encryption.
The new() function at the module level under Crypto.Cipher instantiates
a new CBC cipher object for the relevant base algorithm.
In the following definition, <algorithm> could be AES:
- Crypto.Cipher.<algorithm>.new(key, mode, *, iv=None)
Create a new CBC object, using <algorithm> as the base block cipher.
- Parameters:
- Returns:
a CBC cipher object (
CbcMode)
The method encrypt() (and likewise decrypt()) of a CBC cipher object
expects data to have length multiple of the block size (e.g. 16 bytes for AES).
You might need to use Crypto.Util.Padding to align the plaintext to the right boundary.
A CBC cipher object has a read-only attribute iv, holding the
Initialization Vector (bytes).
Example (encryption):
>>> import json
>>> from base64 import b64encode
>>> from Crypto.Cipher import AES
>>> from Crypto.Util.Padding import pad
>>> from Crypto.Random import get_random_bytes
>>>
>>> data = b"secret"
>>> key = get_random_bytes(16)
>>> cipher = AES.new(key, AES.MODE_CBC)
>>> ct_bytes = cipher.encrypt(pad(data, AES.block_size))
>>> iv = b64encode(cipher.iv).decode('utf-8')
>>> ct = b64encode(ct_bytes).decode('utf-8')
>>> result = json.dumps({'iv':iv, 'ciphertext':ct})
>>> print(result)
'{"iv": "bWRHdzkzVDFJbWNBY0EwSmQ1UXFuQT09", "ciphertext": "VDdxQVo3TFFCbXIzcGpYa1lJbFFZQT09"}'
Example (decryption):
>>> import json
>>> from base64 import b64decode
>>> from Crypto.Cipher import AES
>>> from Crypto.Util.Padding import unpad
>>>
>>> # We assume that the key was securely shared beforehand
>>> try:
... b64 = json.loads(json_input)
... iv = b64decode(b64['iv'])
... ct = b64decode(b64['ciphertext'])
... cipher = AES.new(key, AES.MODE_CBC, iv)
... pt = unpad(cipher.decrypt(ct), AES.block_size)
... print("The message was: ", pt)
... except (ValueError, KeyError):
... print("Incorrect decryption")
CBC cipher object¶
- class Crypto.Cipher._mode_cbc.CbcMode¶
Cipher-Block Chaining (CBC).
Each of the ciphertext blocks depends on the current and all previous plaintext blocks.
An Initialization Vector (IV) is required.
See NIST SP800-38A , Section 6.2 .
- block_size¶
The block size of the underlying cipher, in bytes.
- iv¶
The Initialization Vector originally used to create the object. The value does not change.
- encrypt(plaintext, output=None)¶
Encrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have encrypted a message you cannot encrypt (or decrypt) another message using the same object.
The data to encrypt can be broken up in two or more pieces and
encryptcan be called multiple times.That is, the statement:
>>> c.encrypt(a) + c.encrypt(b)
is equivalent to:
>>> c.encrypt(a+b)
That also means that you cannot reuse an object for encrypting or decrypting other data with the same key.
This function does not add any padding to the plaintext.
- Parameters:
plaintext (bytes/bytearray/memoryview) – The piece of data to encrypt. Its length must be multiple of the cipher block size.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the ciphertext must be written to. If
None, the ciphertext is returned.- Return type:
- Returns:
If
outputisNone, the ciphertext is returned asbytes. Otherwise,None.
- decrypt(ciphertext, output=None)¶
Decrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have decrypted a message you cannot decrypt (or encrypt) another message with the same object.
The data to decrypt can be broken up in two or more pieces and
decryptcan be called multiple times.That is, the statement:
>>> c.decrypt(a) + c.decrypt(b)
is equivalent to:
>>> c.decrypt(a+b)
This function does not remove any padding from the plaintext.
- Parameters:
ciphertext (bytes/bytearray/memoryview) – The piece of data to decrypt. Its length must be multiple of the cipher block size.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the plaintext must be written to. If
None, the plaintext is returned.- Return type:
- Returns:
If
outputisNone, the plaintext is returned asbytes. Otherwise,None.
CTR mode¶
CounTeR mode, defined in NIST SP 800-38A, section 6.5 and Appendix B. This mode turns the block cipher into a stream cipher. Each byte of plaintext is XOR-ed with a byte taken from a keystream: the result is the ciphertext. The keystream is generated by encrypting a sequence of counter blocks with ECB.
A counter block is exactly as long as the cipher block size (e.g. 16 bytes for AES). It consists of the concatenation of two pieces:
a fixed nonce, set at initialization.
a variable counter, which gets increased by 1 for any subsequent counter block. The counter is big endian encoded.
The new() function at the module level under Crypto.Cipher instantiates
a new CTR cipher object for the relevant base algorithm.
In the following definition, <algorithm> could be AES:
- Crypto.Cipher.<algorithm>.new(key, mode, *, nonce=None, initial_value=None, counter=None, threads=1)
Create a new CTR object, using <algorithm> as the base block cipher.
- Parameters:
key (bytes) – the cryptographic key
mode – the constant
Crypto.Cipher.<algorithm>.MODE_CTRnonce (bytes) – the value of the fixed nonce. It must be unique for the combination message/key. Its length varies from 0 to the block size minus 1. If not present, the library creates a random nonce of length equal to block size/2.
initial_value (integer or bytes) – the value of the counter for the first counter block. It can be either an integer or bytes (which is the same integer, just big endian encoded). If not specified, the counter starts at 0.
counter – a custom counter object created with
Crypto.Util.Counter.new(). This allows the definition of a more complex counter block.threads (int) – the maximum number of threads used to encrypt or decrypt long data (default: 1, no extra threads). Use 0 for as many threads as the CPU cores available to the process.
- Returns:
a CTR cipher object (
CtrMode)
The methods encrypt() and decrypt() of a CTR cipher object
accept data of any length (i.e. padding is not needed).
Both raise Crypto.MessageTooLongError (which is also an OverflowError)
as soon as the counter wraps around to repeat the original value.
The CTR cipher object has a read-only attribute nonce (bytes):
the fixed part at the beginning of the counter block.
If you create the cipher with a custom counter (that is, you pass the result of
Crypto.Util.Counter.new() as the counter parameter of new()),
the attribute only holds the prefix you gave to that function (b'' if you gave none).
If you also gave a suffix, reading the attribute raises AttributeError,
because no value of the nonce parameter could produce that counter block,
and the prefix alone would not be enough to decrypt.
The cipher object cannot tell which of those values must be delivered to the recipient,
so you must keep them yourself. It does not reveal the current value of the counter either:
see How do I get the nonce or the next counter value in CTR mode?.
A counter block must never be used twice with the same key, because a repeated keystream breaks the confidentiality of both messages. If the nonce is random, the risk grows with the number of messages encrypted under the same key. The nonce that the library creates by default is 8 bytes long, which is not enough for a very large number of messages. A 12-byte nonce makes a collision far less likely, but it leaves only 32 bits for the counter, so a single message cannot be longer than 64 GiB:
Random nonce |
Longest message |
Probability of a repeated nonce after 216 messages |
After 224 messages |
After 232 messages |
|---|---|---|---|---|
8 bytes (default) |
268 bytes |
1.2 · 10-10 |
7.6 · 10-6 |
39% |
12 bytes |
64 GiB |
below 10-19 |
1.8 · 10-15 |
1.2 · 10-10 |
Each block of the keystream only depends on its counter block,
so the CTR mode can use several CPU cores.
This is disabled by default; enable it with the threads parameter:
>>> cipher = AES.new(key, AES.MODE_CTR, nonce=nonce, threads=4)
>>> ciphertext = cipher.encrypt(very_long_message)
With threads=0, it uses as many threads as the CPU cores available to the process.
The output does not depend on the number of threads.
Threads only help with long data passed in large chunks:
each thread processes at least 1 MiB of a single encrypt() or decrypt() call.
Example (encryption):
>>> import json
>>> from base64 import b64encode
>>> from Crypto.Cipher import AES
>>> from Crypto.Random import get_random_bytes
>>>
>>> data = b"secret"
>>> key = get_random_bytes(16)
>>> cipher = AES.new(key, AES.MODE_CTR)
>>> ct_bytes = cipher.encrypt(data)
>>> nonce = b64encode(cipher.nonce).decode('utf-8')
>>> ct = b64encode(ct_bytes).decode('utf-8')
>>> result = json.dumps({'nonce':nonce, 'ciphertext':ct})
>>> print(result)
{"nonce": "XqP8WbylRt0=", "ciphertext": "Mie5lqje"}
Example (decryption):
>>> import json
>>> from base64 import b64decode
>>> from Crypto.Cipher import AES
>>>
>>> # We assume that the key was securely shared beforehand
>>> try:
... b64 = json.loads(json_input)
... nonce = b64decode(b64['nonce'])
... ct = b64decode(b64['ciphertext'])
... cipher = AES.new(key, AES.MODE_CTR, nonce=nonce)
... pt = cipher.decrypt(ct)
... print("The message was: ", pt)
... except (ValueError, KeyError):
... print("Incorrect decryption")
CTR cipher object¶
- class Crypto.Cipher._mode_ctr.CtrMode¶
CounTeR (CTR) mode.
This mode is very similar to ECB, in that encryption of one block is done independently of all other blocks.
Unlike ECB, the block position contributes to the encryption and no information leaks about symbol frequency.
Each message block is associated to a counter which must be unique across all messages that get encrypted with the same key (not just within the same message). The counter is as big as the block size.
Counters can be generated in several ways. The most straightword one is to choose an initial counter block (which can be made public, similarly to the IV for the other modes) and increment its lowest m bits by one (modulo 2^m) for each block. In most cases, m is chosen to be half the block size.
See NIST SP800-38A, Section 6.5 (for the mode) and Appendix B (for how to manage the initial counter block).
- block_size¶
The block size of the underlying cipher, in bytes.
- property nonce: bytes¶
The fixed part at the beginning of the counter block. It is not available if the counter block has a fixed suffix.
- encrypt(plaintext, output=None)¶
Encrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have encrypted a message you cannot encrypt (or decrypt) another message using the same object.
The data to encrypt can be broken up in two or more pieces and
encryptcan be called multiple times.That is, the statement:
>>> c.encrypt(a) + c.encrypt(b)
is equivalent to:
>>> c.encrypt(a+b)
This function does not add any padding to the plaintext.
- Parameters:
plaintext (bytes/bytearray/memoryview) – The piece of data to encrypt. It can be of any length.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the ciphertext must be written to. If
None, the ciphertext is returned.- Return type:
- Returns:
If
outputisNone, the ciphertext is returned asbytes. Otherwise,None.
- decrypt(ciphertext, output=None)¶
Decrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have decrypted a message you cannot decrypt (or encrypt) another message with the same object.
The data to decrypt can be broken up in two or more pieces and
decryptcan be called multiple times.That is, the statement:
>>> c.decrypt(a) + c.decrypt(b)
is equivalent to:
>>> c.decrypt(a+b)
This function does not remove any padding from the plaintext.
- Parameters:
ciphertext (bytes/bytearray/memoryview) – The piece of data to decrypt. It can be of any length.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the plaintext must be written to. If
None, the plaintext is returned.- Return type:
- Returns:
If
outputisNone, the plaintext is returned asbytes. Otherwise,None.
CFB mode¶
Cipher FeedBack, defined in NIST SP 800-38A, section 6.3. It is a mode of operation which turns the block cipher into a stream cipher. Each byte of plaintext is XOR-ed with a byte taken from a keystream: the result is the ciphertext.
The keystream is obtained on a per-segment basis: the plaintext is broken up in segments (from 1 byte up to the size of a block). Then, for each segment, the keystream is obtained by encrypting with the block cipher the last piece of ciphertext produced so far - possibly backfilled with the Initialization Vector, if not enough ciphertext is available yet.
The new() function at the module level under Crypto.Cipher instantiates
a new CFB cipher object for the relevant base algorithm.
In the following definition, <algorithm> could be AES:
- Crypto.Cipher.<algorithm>.new(key, mode, *, iv=None, segment_size=8)
Create a new CFB object, using <algorithm> as the base block cipher.
- Parameters:
key (bytes) – the cryptographic key
mode – the constant
Crypto.Cipher.<algorithm>.MODE_CFBiv (bytes) – the Initialization Vector. It must be unique for the combination message/key. It is as long as the block size (e.g. 16 bytes for AES). If not present, the library creates a random IV.
segment_size (integer) – the number of bits (not bytes!) the plaintext and the ciphertext are segmented in (default if not specified: 8 bits = 1 byte).
- Returns:
a CFB cipher object (
CfbMode)
The methods encrypt() and decrypt() of a CFB cipher object
accept data of any length (i.e. padding is not needed).
The CFB cipher object has a read-only attribute iv (bytes), holding
the Initialization Vector.
Example (encryption):
>>> import json
>>> from base64 import b64encode
>>> from Crypto.Cipher import AES
>>> from Crypto.Random import get_random_bytes
>>>
>>> data = b"secret"
>>> key = get_random_bytes(16)
>>> cipher = AES.new(key, AES.MODE_CFB)
>>> ct_bytes = cipher.encrypt(data)
>>> iv = b64encode(cipher.iv).decode('utf-8')
>>> ct = b64encode(ct_bytes).decode('utf-8')
>>> result = json.dumps({'iv':iv, 'ciphertext':ct})
>>> print(result)
{"iv": "VoamO23kFSOZcK1O2WiCDQ==", "ciphertext": "f8jciJ8/"}
Example (decryption):
>>> import json
>>> from base64 import b64decode
>>> from Crypto.Cipher import AES
>>>
>>> # We assume that the key was securely shared beforehand
>>> try:
... b64 = json.loads(json_input)
... iv = b64decode(b64['iv'])
... ct = b64decode(b64['ciphertext'])
... cipher = AES.new(key, AES.MODE_CFB, iv=iv)
... pt = cipher.decrypt(ct)
... print("The message was: ", pt)
... except (ValueError, KeyError):
... print("Incorrect decryption")
CFB cipher object¶
- class Crypto.Cipher._mode_cfb.CfbMode¶
Cipher FeedBack (CFB).
This mode is similar to CFB, but it transforms the underlying block cipher into a stream cipher.
Plaintext and ciphertext are processed in segments of s bits. The mode is therefore sometimes labelled s-bit CFB.
An Initialization Vector (IV) is required.
See NIST SP800-38A , Section 6.3.
- block_size¶
The block size of the underlying cipher, in bytes.
- iv¶
The Initialization Vector originally used to create the object. The value does not change.
- encrypt(plaintext, output=None)¶
Encrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have encrypted a message you cannot encrypt (or decrypt) another message using the same object.
The data to encrypt can be broken up in two or more pieces and
encryptcan be called multiple times.That is, the statement:
>>> c.encrypt(a) + c.encrypt(b)
is equivalent to:
>>> c.encrypt(a+b)
This function does not add any padding to the plaintext.
- Parameters:
plaintext (bytes/bytearray/memoryview) – The piece of data to encrypt. It can be of any length.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the ciphertext must be written to. If
None, the ciphertext is returned.- Return type:
- Returns:
If
outputisNone, the ciphertext is returned asbytes. Otherwise,None.
- decrypt(ciphertext, output=None)¶
Decrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have decrypted a message you cannot decrypt (or encrypt) another message with the same object.
The data to decrypt can be broken up in two or more pieces and
decryptcan be called multiple times.That is, the statement:
>>> c.decrypt(a) + c.decrypt(b)
is equivalent to:
>>> c.decrypt(a+b)
This function does not remove any padding from the plaintext.
- Parameters:
ciphertext (bytes/bytearray/memoryview) – The piece of data to decrypt. It can be of any length.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the plaintext must be written to. If
None, the plaintext is returned.- Return type:
- Returns:
If
outputisNone, the plaintext is returned asbytes. Otherwise,None.
OFB mode¶
Output FeedBack, defined in NIST SP 800-38A, section 6.4. It is another mode that leads to a stream cipher. Each byte of plaintext is XOR-ed with a byte taken from a keystream: the result is the ciphertext. The keystream is obtained by recursively encrypting the Initialization Vector.
The new() function at the module level under Crypto.Cipher instantiates
a new OFB cipher object for the relevant base algorithm.
In the following definition, <algorithm> could be AES:
- Crypto.Cipher.<algorithm>.new(key, mode, *, iv=None)
Create a new OFB object, using <algorithm> as the base block cipher.
- Parameters:
- Returns:
an OFB cipher object (
OfbMode)
The methods encrypt() and decrypt() of an OFB cipher object
accept data of any length (i.e. padding is not needed).
The OFB cipher object has a read-only attribute iv (bytes), holding
the Initialization Vector.
Example (encryption):
>>> import json
>>> from base64 import b64encode
>>> from Crypto.Cipher import AES
>>> from Crypto.Random import get_random_bytes
>>>
>>> data = b"secret"
>>> key = get_random_bytes(16)
>>> cipher = AES.new(key, AES.MODE_OFB)
>>> ct_bytes = cipher.encrypt(data)
>>> iv = b64encode(cipher.iv).decode('utf-8')
>>> ct = b64encode(ct_bytes).decode('utf-8')
>>> result = json.dumps({'iv':iv, 'ciphertext':ct})
>>> print(result)
{"iv": "NUuRJbL0UMp8+UMCk2/vQA==", "ciphertext": "XGVGc1Gw"}
Example (decryption):
>>> import json
>>> from base64 import b64decode
>>> from Crypto.Cipher import AES
>>>
>>> # We assume that the key was securely shared beforehand
>>> try:
... b64 = json.loads(json_input)
... iv = b64decode(b64['iv'])
... ct = b64decode(b64['ciphertext'])
... cipher = AES.new(key, AES.MODE_OFB, iv=iv)
... pt = cipher.decrypt(ct)
... print("The message was: ", pt)
... except (ValueError, KeyError):
... print("Incorrect decryption")
OFB cipher object¶
- class Crypto.Cipher._mode_ofb.OfbMode¶
Output FeedBack (OFB).
This mode is very similar to CBC, but it transforms the underlying block cipher into a stream cipher.
The keystream is the iterated block encryption of the previous ciphertext block.
An Initialization Vector (IV) is required.
See NIST SP800-38A , Section 6.4.
- block_size¶
The block size of the underlying cipher, in bytes.
- iv¶
The Initialization Vector originally used to create the object. The value does not change.
- encrypt(plaintext, output=None)¶
Encrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have encrypted a message you cannot encrypt (or decrypt) another message using the same object.
The data to encrypt can be broken up in two or more pieces and
encryptcan be called multiple times.That is, the statement:
>>> c.encrypt(a) + c.encrypt(b)
is equivalent to:
>>> c.encrypt(a+b)
This function does not add any padding to the plaintext.
- Parameters:
plaintext (bytes/bytearray/memoryview) – The piece of data to encrypt. It can be of any length.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the ciphertext must be written to. If
None, the ciphertext is returned.- Return type:
- Returns:
If
outputisNone, the ciphertext is returned asbytes. Otherwise,None.
- decrypt(ciphertext, output=None)¶
Decrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have decrypted a message you cannot decrypt (or encrypt) another message with the same object.
The data to decrypt can be broken up in two or more pieces and
decryptcan be called multiple times.That is, the statement:
>>> c.decrypt(a) + c.decrypt(b)
is equivalent to:
>>> c.decrypt(a+b)
This function does not remove any padding from the plaintext.
- Parameters:
ciphertext (bytes/bytearray/memoryview) – The piece of data to decrypt. It can be of any length.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the plaintext is written to. If
None, the plaintext is returned.- Return type:
- Returns:
If
outputisNone, the plaintext is returned asbytes. Otherwise,None.
OpenPGP mode¶
Constant: Crypto.Cipher.<cipher>.MODE_OPENPGP.
OpenPGP (defined in RFC4880). A variant of CFB, with two differences:
The first invocation to the
encrypt()method returns the encrypted IV concatenated to the first chunk of ciphertext (as opposed to the ciphertext only). The encrypted IV is as long as the block size plus 2 more bytes.When the cipher object is intended for decryption, the parameter
ivtonew()is the encrypted IV (and not the IV, which is still the case for encryption).
Like for CTR, an OpenPGP cipher object has a read-only attribute iv.
OpenPGP cipher object¶
- class Crypto.Cipher._mode_openpgp.OpenPgpMode¶
OpenPGP mode.
This mode is a variant of CFB, and it is only used in PGP and OpenPGP applications. If in doubt, use another mode.
An Initialization Vector (IV) is required.
Unlike CFB, the encrypted IV (not the IV itself) is transmitted to the receiver.
The IV is a random data block. For legacy reasons, two of its bytes are duplicated to act as a checksum for the correctness of the key, which is now known to be insecure and is ignored. The encrypted IV is therefore 2 bytes longer than the clean IV.
- block_size¶
The block size of the underlying cipher, in bytes.
- iv¶
The Initialization Vector originally used to create the object (without the two extra bytes used for decryption).
- encrypt(plaintext)¶
Encrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have encrypted a message you cannot encrypt (or decrypt) another message using the same object.
The data to encrypt can be broken up in two or more pieces and
encryptcan be called multiple times.That is, the statement:
>>> c.encrypt(a) + c.encrypt(b)
is equivalent to:
>>> c.encrypt(a+b)
This function does not add any padding to the plaintext.
- Parameters:
plaintext (bytes/bytearray/memoryview) – The piece of data to encrypt.
- Return type:
- Returns:
the encrypted data, as a byte string. It is as long as plaintext with one exception: when encrypting the first message chunk, the encypted IV is prepended to the returned ciphertext.
- decrypt(ciphertext)¶
Decrypt data with the key and the parameters set at initialization.
A cipher object is stateful: once you have decrypted a message you cannot decrypt (or encrypt) another message with the same object.
The data to decrypt can be broken up in two or more pieces and
decryptcan be called multiple times.That is, the statement:
>>> c.decrypt(a) + c.decrypt(b)
is equivalent to:
>>> c.decrypt(a+b)
This function does not remove any padding from the plaintext.
- Parameters:
ciphertext (bytes/bytearray/memoryview) – The piece of data to decrypt.
- Return type:
- Returns:
the decrypted data (byte string).
XTS mode¶
XEX-based Tweaked-codebook mode with ciphertext Stealing, defined in IEEE 1619 and NIST SP 800-38E. It is meant for encrypting storage, such as a disk, where each data unit (such as a sector) is stored in place, and the ciphertext cannot be longer than the plaintext. It is only available for AES.
Warning
XTS does not authenticate the data, and it has no room for a nonce or a tag. An attacker who can modify the ciphertext can turn it into random-looking plaintext (one block for each block changed), can restore an old version of a data unit, and can see if a block in a data unit has gone back to a previous value.
Unless you are constrained by the storage format, use an authenticated mode instead.
Each cipher object processes one data unit:
Crypto.Cipher.AES.new(key, AES.MODE_XTS, tweak=tweak)
The arguments are:
key: 32 bytes (two AES-128 keys) or 64 bytes (two AES-256 keys), concatenated. The two keys must be different, and independent of each other: generate the whole value at random.tweak: 16 bytes that identify the data unit, and that must be different for each data unit encrypted with the same key. It is mandatory: it must come from the position of the data, so it is not generated for you, and it is not stored with the ciphertext. The standard way is the number of the sector, as a little-endian value:number.to_bytes(16, "little").
The methods encrypt() and decrypt()
return data of the same length as their input.
A data unit must be at least 16 bytes long, and it cannot be longer than 16 MiB (220 blocks).
There is no padding, as its length does not need to be a multiple of the block size.
A data unit can be processed in several pieces. Each one must have a length that is a multiple of 16 bytes, except for the last one, which can have any length above 16 bytes.
Example of encryption and decryption of a disk sector:
>>> from Crypto.Cipher import AES
>>> from Crypto.Random import get_random_bytes
>>>
>>> key = get_random_bytes(64)
>>> sector_number = 1234
>>> tweak = sector_number.to_bytes(16, "little")
>>> sector = b"A" * 512
>>>
>>> ciphertext = AES.new(key, AES.MODE_XTS, tweak=tweak).encrypt(sector)
>>> assert AES.new(key, AES.MODE_XTS, tweak=tweak).decrypt(ciphertext) == sector
XTS cipher object¶
- class Crypto.Cipher._mode_xts.XtsMode¶
XEX-based Tweaked-codebook mode with ciphertext Stealing (XTS).
This mode is meant for encrypting storage, where each data unit (such as a disk sector) is stored in place and cannot grow. It does not provide integrity.
An object encrypts or decrypts one data unit.
See IEEE 1619 and NIST SP 800-38E.
- encrypt(plaintext, output=None)¶
Encrypt (a piece of) the data unit.
The data can be split over several calls: the length of each piece must be a multiple of 16 bytes, except for the last one, which can have any length above 16 bytes. The data unit must be at least 16 bytes long, and it cannot be longer than 16 MiB (220 blocks).
- Parameters:
plaintext (bytes/bytearray/memoryview) – The piece of data to encrypt.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the ciphertext must be written to. It can be the same buffer as
plaintext. IfNone, the ciphertext is returned.- Return type:
- Returns:
If
outputisNone, the ciphertext is returned asbytes. Otherwise,None.
- decrypt(ciphertext, output=None)¶
Decrypt (a piece of) the data unit.
The data can be split over several calls: the length of each piece must be a multiple of 16 bytes, except for the last one, which can have any length above 16 bytes. The data unit must be at least 16 bytes long, and it cannot be longer than 16 MiB (220 blocks).
- Parameters:
ciphertext (bytes/bytearray/memoryview) – The piece of data to decrypt.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the plaintext must be written to. It can be the same buffer as
ciphertext. IfNone, the plaintext is returned.- Return type:
- Returns:
If
outputisNone, the plaintext is returned asbytes. Otherwise,None.