The IV parameter is currently ignored when initializing a cipher in ECB or CTR mode. For CTR mode, it is confusing: it takes some time to see that a different parameter is needed (the counter). For ECB mode, it is outright dangerous. This patch forces an exception to be raised.
This patch adds encrypt_and_digest() and decrypt_and_verify() methods to a cipher object. In most cases they are just shortcuts to the existing functions. For SIV mode, decrypt_and_verify() replaces decrypt(). [dlitz@dlitz.net: Squashed with bugfix commit:] Bug in encrypt_and_digest() (all AEAD modes) decrypt() was being called instead of encrypt(). Added also a unit test to validate that composition of encrypt_and_digest() and decrypt_and_verify() is the identity function. [dlitz@dlitz.net: Included changes from the following commit from the author's pull request:] - [9c13f9c] Rename 'IV' parameter to 'nonce' for AEAD modes. [dlitz@dlitz.net: Whitespace fixed with "git rebase --whitespace=fix"] [dlitz@dlitz.net: Replaced MacMismatchError with ValueError] [dlitz@dlitz.net: Replaced ApiUsageError with TypeError]
The main change done by this commit is adding support
for MODE_GCM (NIST SP 800 38D). Test vectors are included.
The mode uses a C extension (Crypto.Util.galois._ghash)
to compute the GHASH step. The C implementation is the most
basic one and it is still significantly (5x times) slower than CTR.
Optimizations can be introduced using tables (CPU/memory trade-off)
or even AES NI instructions on newer x86 CPUs.
This patch also simplifies Crypto.Cipher.blockalgo.py by:
* removing duplicated code previously shared by digest() and verify().
* removing duplicated code previously shared by Crypto.Hash.CMAC
and Crypto.Cipher.block_algo (management of internal buffers
for MACs that can only operate on block aligned data, like
CMAC, CBCMAC, and now also GHASH).
[dlitz@dlitz.net: Included changes from the following commits from the author's pull request:]
- [9c13f9c] Rename 'IV' parameter to 'nonce' for AEAD modes.
- [ca460a7] Made blockalgo.py more PEP-8 compliant;
The second parameter of the _GHASH constructor
is now the length of the block (block_size)
and not the full module.
[dlitz@dlitz.net: Replaced MacMismatchError with ValueError]
[dlitz@dlitz.net: Replaced ApiUsageError with TypeError]
[dlitz@dlitz.net: Replaced renamed variable `ht` with original `h`]
[dlitz@dlitz.net: Whitespace fixed with "git rebase --whitespace=fix"]
This patch add supports for SIV, an AEAD block cipher
mode defined in RFC5297. SIV is only valid for AES.
The PRF of SIV (S2V) is factored out in the Protocol.KDF module.
See the following example to get a feeling of the API (slightly
different than other AEAD mode, during decryption).
Encryption (Python 2):
>>> from Crypto.Cipher import AES
>>> key = b'0'*32
>>> siv = AES.new(key, AES.MODE_SIV)
>>> ct = siv.encrypt(b'Message')
>>> mac = siv.digest()
Decryption (Python 2):
>>> from Crypto.Cipher import AES, MacMismatchError
>>> key = b'0'*32
>>> siv = AES.new(key, AES.MODE_SIV)
>>> pt = siv.decrypt(ct + mac)
>>> try:
>>> siv.verify(mac)
>>> print "Plaintext", pt
>>> except MacMismatchError:
>>> print "Error"
This change also fixes the description/design of AEAD API.
With SIV (RFC5297), decryption can only start when the MAC is known.
The original AEAD API did not support that.
For SIV the MAC is now exceptionally passed together with the ciphertext
to the decrypt() method.
[dlitz@dlitz.net: Included changes from the following commits from the author's pull request:]
- [9c13f9c] Rename 'IV' parameter to 'nonce' for AEAD modes.
- [d7727fb] Fix description/design of AEAD API.
- [fb62fae] ApiUsageError becomes TypeError [whitespace]
- [4ec64d8] Removed last references to ApiUsageError [whitespace]
- [ee46922] Removed most 'import *' statements
- [ca460a7] Made blockalgo.py more PEP-8 compliant;
The second parameter of the _GHASH constructor
is now the length of the block (block_size)
and not the full module.
[dlitz@dlitz.net: A conflict that was not resolved in the previous
commit was originally resolved here. Moved the
resolution to the previous commit.]
[dlitz@dlitz.net: Replaced MacMismatchError with ValueError]
[dlitz@dlitz.net: Replaced ApiUsageError with TypeError]
[dlitz@dlitz.net: Whitespace fixed with "git rebase --whitespace=fix"]
[dlitz@dlitz.net: Included changes from the following commits from the author's pull request:]
- [9c13f9c] Rename 'IV' parameter to 'nonce' for AEAD modes.
- [ca460a7] Made blockalgo.py more PEP-8 compliant; The second parameter
of the _GHASH constructor is now the length of the block
(block_size) and not the full module.
[dlitz@dlitz.net: Fixed unresolved conflict in lib/Crypto/Cipher/blockalgo.py]
[dlitz@dlitz.net: Included changes from the following commits from the author's pull request:] - [5306cf3] Added support for CCM mode (AES cipher only) - [9abe301] Added CCM tests - [f0c1395] Add MacMismatchError and ApiUsageError - [fb62fae] ApiUsageError becomes TypeError - [9c13f9c] Rename 'IV' parameter to 'nonce' for AEAD modes. - [4ec64d8] Removed last references to ApiUsageError - [80bfd35] Corrected AES-CCM examples [dlitz@dlitz.net: Removed unrelated documentation change] [dlitz@dlitz.net: Renamed 'targs' back to 'args'] [dlitz@dlitz.net: Whitespace fixed with "git rebase --whitespace=fix"]
Closes: https://bugs.launchpad.net/pycrypto/+bug/996193 Closes: https://github.com/dlitz/pycrypto/pull/26 [dlitz: Squashed and fixed whitespace.]
The `disable_shortcut` option served as a workaround in case `__PCT_CTR_SHORTCUT__` leaked through a wrapper object, but I don't think anyone actually used it, and it was a bad idea to expose it as part of the public API. Now that we do strong type checking inside block_template.c, there shoujld be no need to ever use this option. It's now a no-op, retained for backward compatibility only. It will be removed in some future version of PyCrypto.
- METH_NOARGS was introduced in Python 2.2. - Python 2.1 doesn't have True and False builtins.