diff options
| -rw-r--r-- | cryptography/exceptions.py | 12 | ||||
| -rw-r--r-- | cryptography/hazmat/bindings/openssl/backend.py | 56 | ||||
| -rw-r--r-- | cryptography/hazmat/primitives/ciphers/base.py | 63 | ||||
| -rw-r--r-- | cryptography/hazmat/primitives/ciphers/modes.py | 11 | ||||
| -rw-r--r-- | cryptography/hazmat/primitives/interfaces.py | 24 | ||||
| -rw-r--r-- | docs/exceptions.rst | 12 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 72 | ||||
| -rw-r--r-- | tests/hazmat/primitives/test_aes.py | 21 | ||||
| -rw-r--r-- | tests/hazmat/primitives/test_block.py | 17 | ||||
| -rw-r--r-- | tests/hazmat/primitives/test_utils.py | 25 | ||||
| -rw-r--r-- | tests/hazmat/primitives/utils.py | 120 |
11 files changed, 419 insertions, 14 deletions
diff --git a/cryptography/exceptions.py b/cryptography/exceptions.py index c2e71493..e9d88199 100644 --- a/cryptography/exceptions.py +++ b/cryptography/exceptions.py @@ -18,3 +18,15 @@ class UnsupportedAlgorithm(Exception): class AlreadyFinalized(Exception): pass + + +class AlreadyUpdated(Exception): + pass + + +class NotYetFinalized(Exception): + pass + + +class InvalidTag(Exception): + pass diff --git a/cryptography/hazmat/bindings/openssl/backend.py b/cryptography/hazmat/bindings/openssl/backend.py index 9f8ea939..1b19ddaa 100644 --- a/cryptography/hazmat/bindings/openssl/backend.py +++ b/cryptography/hazmat/bindings/openssl/backend.py @@ -19,7 +19,7 @@ import sys import cffi from cryptography import utils -from cryptography.exceptions import UnsupportedAlgorithm +from cryptography.exceptions import UnsupportedAlgorithm, InvalidTag from cryptography.hazmat.bindings.interfaces import ( CipherBackend, HashBackend, HMACBackend ) @@ -28,7 +28,7 @@ from cryptography.hazmat.primitives.ciphers.algorithms import ( AES, Blowfish, Camellia, CAST5, TripleDES, ARC4, ) from cryptography.hazmat.primitives.ciphers.modes import ( - CBC, CTR, ECB, OFB, CFB + CBC, CTR, ECB, OFB, CFB, GCM, ) @@ -186,6 +186,11 @@ class Backend(object): type(None), GetCipherByName("rc4") ) + self.register_cipher_adapter( + AES, + GCM, + GetCipherByName("{cipher.name}-{cipher.key_size}-{mode.name}") + ) def create_symmetric_encryption_ctx(self, cipher, mode): return _CipherContext(self, cipher, mode, _CipherContext._ENCRYPT) @@ -193,8 +198,10 @@ class Backend(object): def create_symmetric_decryption_ctx(self, cipher, mode): return _CipherContext(self, cipher, mode, _CipherContext._DECRYPT) - def _handle_error(self): + def _handle_error(self, mode): code = self.lib.ERR_get_error() + if not code and isinstance(mode, GCM): + raise InvalidTag assert code != 0 lib = self.lib.ERR_GET_LIB(code) func = self.lib.ERR_GET_FUNC(code) @@ -231,6 +238,8 @@ class GetCipherByName(object): @utils.register_interface(interfaces.CipherContext) +@utils.register_interface(interfaces.AEADCipherContext) +@utils.register_interface(interfaces.AEADEncryptionContext) class _CipherContext(object): _ENCRYPT = 1 _DECRYPT = 0 @@ -238,6 +247,9 @@ class _CipherContext(object): def __init__(self, backend, cipher, mode, operation): self._backend = backend self._cipher = cipher + self._mode = mode + self._operation = operation + self._tag = None ctx = self._backend.lib.EVP_CIPHER_CTX_new() ctx = self._backend.ffi.gc(ctx, self._backend.lib.EVP_CIPHER_CTX_free) @@ -270,6 +282,20 @@ class _CipherContext(object): ctx, len(cipher.key) ) assert res != 0 + if isinstance(mode, GCM): + res = self._backend.lib.EVP_CIPHER_CTX_ctrl( + ctx, self._backend.lib.Cryptography_EVP_CTRL_GCM_SET_IVLEN, + len(iv_nonce), self._backend.ffi.NULL + ) + assert res != 0 + if operation == self._DECRYPT: + assert mode.tag is not None + res = self._backend.lib.EVP_CIPHER_CTX_ctrl( + ctx, self._backend.lib.Cryptography_EVP_CTRL_GCM_SET_TAG, + len(mode.tag), mode.tag + ) + assert res != 0 + # pass key/iv res = self._backend.lib.EVP_CipherInit_ex(ctx, self._backend.ffi.NULL, self._backend.ffi.NULL, @@ -296,12 +322,34 @@ class _CipherContext(object): outlen = self._backend.ffi.new("int *") res = self._backend.lib.EVP_CipherFinal_ex(self._ctx, buf, outlen) if res == 0: - self._backend._handle_error() + self._backend._handle_error(self._mode) + + if (isinstance(self._mode, GCM) and + self._operation == self._ENCRYPT): + block_byte_size = self._cipher.block_size // 8 + tag_buf = self._backend.ffi.new("unsigned char[]", block_byte_size) + res = self._backend.lib.EVP_CIPHER_CTX_ctrl( + self._ctx, self._backend.lib.Cryptography_EVP_CTRL_GCM_GET_TAG, + block_byte_size, tag_buf + ) + assert res != 0 + self._tag = self._backend.ffi.buffer(tag_buf)[:] res = self._backend.lib.EVP_CIPHER_CTX_cleanup(self._ctx) assert res == 1 return self._backend.ffi.buffer(buf)[:outlen[0]] + def authenticate_additional_data(self, data): + outlen = self._backend.ffi.new("int *") + res = self._backend.lib.EVP_CipherUpdate( + self._ctx, self._backend.ffi.NULL, outlen, data, len(data) + ) + assert res != 0 + + @property + def tag(self): + return self._tag + @utils.register_interface(interfaces.HashContext) class _HashContext(object): diff --git a/cryptography/hazmat/primitives/ciphers/base.py b/cryptography/hazmat/primitives/ciphers/base.py index 48e6da6f..b8615cb9 100644 --- a/cryptography/hazmat/primitives/ciphers/base.py +++ b/cryptography/hazmat/primitives/ciphers/base.py @@ -14,7 +14,9 @@ from __future__ import absolute_import, division, print_function from cryptography import utils -from cryptography.exceptions import AlreadyFinalized +from cryptography.exceptions import ( + AlreadyFinalized, NotYetFinalized, AlreadyUpdated, +) from cryptography.hazmat.primitives import interfaces @@ -28,14 +30,25 @@ class Cipher(object): self._backend = backend def encryptor(self): - return _CipherContext(self._backend.create_symmetric_encryption_ctx( + ctx = self._backend.create_symmetric_encryption_ctx( self.algorithm, self.mode - )) + ) + return self._wrap_ctx(ctx, True) def decryptor(self): - return _CipherContext(self._backend.create_symmetric_decryption_ctx( + ctx = self._backend.create_symmetric_decryption_ctx( self.algorithm, self.mode - )) + ) + return self._wrap_ctx(ctx, False) + + def _wrap_ctx(self, ctx, encrypt): + if isinstance(self.mode, interfaces.ModeWithAuthenticationTag): + if encrypt: + return _AEADEncryptionContext(ctx) + else: + return _AEADCipherContext(ctx) + else: + return _CipherContext(ctx) @utils.register_interface(interfaces.CipherContext) @@ -54,3 +67,43 @@ class _CipherContext(object): data = self._ctx.finalize() self._ctx = None return data + + +@utils.register_interface(interfaces.AEADCipherContext) +@utils.register_interface(interfaces.CipherContext) +class _AEADCipherContext(object): + def __init__(self, ctx): + self._ctx = ctx + self._tag = None + self._updated = False + + def update(self, data): + if self._ctx is None: + raise AlreadyFinalized("Context was already finalized") + self._updated = True + return self._ctx.update(data) + + def finalize(self): + if self._ctx is None: + raise AlreadyFinalized("Context was already finalized") + data = self._ctx.finalize() + self._tag = self._ctx.tag + self._ctx = None + return data + + def authenticate_additional_data(self, data): + if self._ctx is None: + raise AlreadyFinalized("Context was already finalized") + if self._updated: + raise AlreadyUpdated("Update has been called on this context") + self._ctx.authenticate_additional_data(data) + + +@utils.register_interface(interfaces.AEADEncryptionContext) +class _AEADEncryptionContext(_AEADCipherContext): + @property + def tag(self): + if self._ctx is not None: + raise NotYetFinalized("You must finalize encryption before " + "getting the tag") + return self._tag diff --git a/cryptography/hazmat/primitives/ciphers/modes.py b/cryptography/hazmat/primitives/ciphers/modes.py index 1d0de689..e1c70185 100644 --- a/cryptography/hazmat/primitives/ciphers/modes.py +++ b/cryptography/hazmat/primitives/ciphers/modes.py @@ -56,3 +56,14 @@ class CTR(object): def __init__(self, nonce): self.nonce = nonce + + +@utils.register_interface(interfaces.Mode) +@utils.register_interface(interfaces.ModeWithInitializationVector) +@utils.register_interface(interfaces.ModeWithAuthenticationTag) +class GCM(object): + name = "GCM" + + def __init__(self, initialization_vector, tag=None): + self.initialization_vector = initialization_vector + self.tag = tag diff --git a/cryptography/hazmat/primitives/interfaces.py b/cryptography/hazmat/primitives/interfaces.py index 8cc9d42c..e3f4f586 100644 --- a/cryptography/hazmat/primitives/interfaces.py +++ b/cryptography/hazmat/primitives/interfaces.py @@ -56,6 +56,14 @@ class ModeWithNonce(six.with_metaclass(abc.ABCMeta)): """ +class ModeWithAuthenticationTag(six.with_metaclass(abc.ABCMeta)): + @abc.abstractproperty + def tag(self): + """ + The value of the tag supplied to the constructor of this mode. + """ + + class CipherContext(six.with_metaclass(abc.ABCMeta)): @abc.abstractmethod def update(self, data): @@ -70,6 +78,22 @@ class CipherContext(six.with_metaclass(abc.ABCMeta)): """ +class AEADCipherContext(six.with_metaclass(abc.ABCMeta)): + @abc.abstractmethod + def authenticate_additional_data(self, data): + """ + authenticate_additional_data takes bytes and returns nothing. + """ + + +class AEADEncryptionContext(six.with_metaclass(abc.ABCMeta)): + @abc.abstractproperty + def tag(self): + """ + Returns tag bytes after finalizing encryption. + """ + + class PaddingContext(six.with_metaclass(abc.ABCMeta)): @abc.abstractmethod def update(self, data): diff --git a/docs/exceptions.rst b/docs/exceptions.rst index c6f5a7cc..087066b8 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -8,6 +8,18 @@ Exceptions This is raised when a context is used after being finalized. +.. class:: NotYetFinalized + + This is raised when the AEAD tag property is accessed on a context + before it is finalized. + + +.. class:: AlreadyUpdated + + This is raised when additional data is added to a context after update + has already been called. + + .. class:: UnsupportedAlgorithm This is raised when a backend doesn't support the requested algorithm (or diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index edf3c050..8d8d558b 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -118,6 +118,36 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :meth:`update` and :meth:`finalize` will raise :class:`~cryptography.exceptions.AlreadyFinalized`. +.. class:: AEADCipherContext + + When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object + with an AEAD mode you will receive a return object conforming to the + ``AEADCipherContext`` interface (in addition to the ``CipherContext`` + interface). If it is an encryption context it will additionally be an + ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an + additional method ``authenticate_additional_data`` for adding additional + authenticated but unencrypted data. You should call this before calls to + ``update``. When you are done call ``finalize()`` to finish the operation. + + .. method:: authenticate_additional_data(data) + + :param bytes data: The data you wish to authenticate but not encrypt. + :raises: :class:`~cryptography.exceptions.AlreadyFinalized` + +.. class:: AEADEncryptionContext + + When creating an encryption context using ``encryptor()`` on a ``Cipher`` + object with an AEAD mode you will receive a return object conforming to the + ``AEADEncryptionContext`` interface (as well as ``AEADCipherContext``). + This interface provides one additional attribute ``tag``. ``tag`` can only + be obtained after ``finalize()``. + + .. attribute:: tag + + :return bytes: Returns the tag value as bytes. + :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called + before the context is finalized. + .. _symmetric-encryption-algorithms: Algorithms @@ -295,6 +325,47 @@ Modes reuse an ``initialization_vector`` with a given ``key``. +.. class:: GCM(initialization_vector, tag=None) + + .. danger:: + + When using this mode you MUST not use the decrypted data until every + byte has been decrypted. GCM provides NO guarantees of ciphertext + integrity until decryption is complete. + + GCM (Galois Counter Mode) is a mode of operation for block ciphers. An + AEAD (authenticated encryption with additional data) mode is a type of + block cipher mode that encrypts the message as well as authenticating it + (and optionally additional data that is not encrypted) simultaneously. + Additional means of verifying integrity (like + :doc:`HMAC </hazmat/primitives/hmac>`) are not necessary. + + :param bytes initialization_vector: Must be random bytes. They do not need + to be kept secret (they can be included + in a transmitted message). NIST + `recommends 96-bit IV length`_ for + performance critical situations, but it + can be up to 2\ :sup:`64` - 1 bits. + Do not reuse an ``initialization_vector`` + with a given ``key``. + + :param bytes tag: The tag bytes to verify during decryption. Must be provided + for decryption, but is ignored when encrypting. + + .. doctest:: + + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend) + >>> encryptor = cipher.encryptor() + >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload") + >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() + >>> tag = encryptor.tag + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag), backend) + >>> decryptor = cipher.decryptor() + >>> decryptor.authenticate_additional_data(b"authenticated but not encrypted payload") + >>> decryptor.update(ct) + decryptor.finalize() + 'a secret message' + Insecure Modes -------------- @@ -314,3 +385,4 @@ Insecure Modes .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html +.. _`recommends 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf diff --git a/tests/hazmat/primitives/test_aes.py b/tests/hazmat/primitives/test_aes.py index d178da7b..f7b0b9a0 100644 --- a/tests/hazmat/primitives/test_aes.py +++ b/tests/hazmat/primitives/test_aes.py @@ -18,7 +18,7 @@ import os from cryptography.hazmat.primitives.ciphers import algorithms, modes -from .utils import generate_encrypt_test +from .utils import generate_encrypt_test, generate_aead_test from ...utils import ( load_nist_vectors, load_openssl_vectors, ) @@ -132,3 +132,22 @@ class TestAES(object): ), skip_message="Does not support AES CTR", ) + + test_GCM = generate_aead_test( + load_nist_vectors, + os.path.join("ciphers", "AES", "GCM"), + [ + "gcmDecrypt128.rsp", + "gcmDecrypt192.rsp", + "gcmDecrypt256.rsp", + "gcmEncryptExtIV128.rsp", + "gcmEncryptExtIV192.rsp", + "gcmEncryptExtIV256.rsp", + ], + lambda key: algorithms.AES(key), + lambda iv, tag: modes.GCM(iv, tag), + only_if=lambda backend: backend.cipher_supported( + algorithms.AES("\x00" * 16), modes.GCM("\x00" * 12) + ), + skip_message="Does not support AES GCM", + ) diff --git a/tests/hazmat/primitives/test_block.py b/tests/hazmat/primitives/test_block.py index f6c44b47..2806efd5 100644 --- a/tests/hazmat/primitives/test_block.py +++ b/tests/hazmat/primitives/test_block.py @@ -18,12 +18,16 @@ import binascii import pytest from cryptography import utils -from cryptography.exceptions import UnsupportedAlgorithm, AlreadyFinalized +from cryptography.exceptions import ( + UnsupportedAlgorithm, AlreadyFinalized, +) from cryptography.hazmat.primitives import interfaces from cryptography.hazmat.primitives.ciphers import ( Cipher, algorithms, modes ) +from .utils import generate_aead_exception_test + @utils.register_interface(interfaces.CipherAlgorithm) class DummyCipher(object): @@ -120,3 +124,14 @@ class TestCipherContext(object): decryptor.update(b"1") with pytest.raises(ValueError): decryptor.finalize() + + +class TestAEADCipherContext(object): + test_aead_exceptions = generate_aead_exception_test( + algorithms.AES, + modes.GCM, + only_if=lambda backend: backend.cipher_supported( + algorithms.AES("\x00" * 16), modes.GCM("\x00" * 12) + ), + skip_message="Does not support AES GCM", + ) diff --git a/tests/hazmat/primitives/test_utils.py b/tests/hazmat/primitives/test_utils.py index cee0b20e..ebb8b5c4 100644 --- a/tests/hazmat/primitives/test_utils.py +++ b/tests/hazmat/primitives/test_utils.py @@ -2,7 +2,8 @@ import pytest from .utils import ( base_hash_test, encrypt_test, hash_test, long_string_hash_test, - base_hmac_test, hmac_test, stream_encryption_test + base_hmac_test, hmac_test, stream_encryption_test, aead_test, + aead_exception_test, ) @@ -17,6 +18,28 @@ class TestEncryptTest(object): assert exc_info.value.args[0] == "message!" +class TestAEADTest(object): + def test_skips_if_only_if_returns_false(self): + with pytest.raises(pytest.skip.Exception) as exc_info: + aead_test( + None, None, None, None, + only_if=lambda backend: False, + skip_message="message!" + ) + assert exc_info.value.args[0] == "message!" + + +class TestAEADFinalizeTest(object): + def test_skips_if_only_if_returns_false(self): + with pytest.raises(pytest.skip.Exception) as exc_info: + aead_exception_test( + None, None, None, + only_if=lambda backend: False, + skip_message="message!" + ) + assert exc_info.value.args[0] == "message!" + + class TestHashTest(object): def test_skips_if_only_if_returns_false(self): with pytest.raises(pytest.skip.Exception) as exc_info: diff --git a/tests/hazmat/primitives/utils.py b/tests/hazmat/primitives/utils.py index 6c67ddb3..9aa3a89a 100644 --- a/tests/hazmat/primitives/utils.py +++ b/tests/hazmat/primitives/utils.py @@ -4,9 +4,11 @@ import os import pytest from cryptography.hazmat.bindings import _ALL_BACKENDS -from cryptography.hazmat.primitives import hashes -from cryptography.hazmat.primitives import hmac +from cryptography.hazmat.primitives import hashes, hmac from cryptography.hazmat.primitives.ciphers import Cipher +from cryptography.exceptions import ( + AlreadyFinalized, NotYetFinalized, AlreadyUpdated, InvalidTag, +) from ...utils import load_vectors_from_file @@ -54,6 +56,72 @@ def encrypt_test(backend, cipher_factory, mode_factory, params, only_if, assert actual_plaintext == binascii.unhexlify(plaintext) +def generate_aead_test(param_loader, path, file_names, cipher_factory, + mode_factory, only_if, skip_message): + def test_aead(self): + for backend in _ALL_BACKENDS: + for file_name in file_names: + for params in load_vectors_from_file( + os.path.join(path, file_name), + param_loader + ): + yield ( + aead_test, + backend, + cipher_factory, + mode_factory, + params, + only_if, + skip_message + ) + return test_aead + + +def aead_test(backend, cipher_factory, mode_factory, params, only_if, + skip_message): + if not only_if(backend): + pytest.skip(skip_message) + if params.get("pt") is not None: + plaintext = params.pop("pt") + ciphertext = params.pop("ct") + aad = params.pop("aad") + if params.get("fail") is True: + cipher = Cipher( + cipher_factory(binascii.unhexlify(params["key"])), + mode_factory(binascii.unhexlify(params["iv"]), + binascii.unhexlify(params["tag"])), + backend + ) + decryptor = cipher.decryptor() + decryptor.authenticate_additional_data(binascii.unhexlify(aad)) + actual_plaintext = decryptor.update(binascii.unhexlify(ciphertext)) + with pytest.raises(InvalidTag): + decryptor.finalize() + else: + cipher = Cipher( + cipher_factory(binascii.unhexlify(params["key"])), + mode_factory(binascii.unhexlify(params["iv"]), None), + backend + ) + encryptor = cipher.encryptor() + encryptor.authenticate_additional_data(binascii.unhexlify(aad)) + actual_ciphertext = encryptor.update(binascii.unhexlify(plaintext)) + actual_ciphertext += encryptor.finalize() + tag_len = len(params["tag"]) + assert binascii.hexlify(encryptor.tag)[:tag_len] == params["tag"] + cipher = Cipher( + cipher_factory(binascii.unhexlify(params["key"])), + mode_factory(binascii.unhexlify(params["iv"]), + binascii.unhexlify(params["tag"])), + backend + ) + decryptor = cipher.decryptor() + decryptor.authenticate_additional_data(binascii.unhexlify(aad)) + actual_plaintext = decryptor.update(binascii.unhexlify(ciphertext)) + actual_plaintext += decryptor.finalize() + assert actual_plaintext == binascii.unhexlify(plaintext) + + def generate_stream_encryption_test(param_loader, path, file_names, cipher_factory, only_if=None, skip_message=None): @@ -237,3 +305,51 @@ def base_hmac_test(backend, algorithm, only_if, skip_message): h_copy = h.copy() assert h != h_copy assert h._ctx != h_copy._ctx + + +def generate_aead_exception_test(cipher_factory, mode_factory, + only_if, skip_message): + def test_aead_exception(self): + for backend in _ALL_BACKENDS: + yield ( + aead_exception_test, + backend, + cipher_factory, + mode_factory, + only_if, + skip_message + ) + return test_aead_exception + + +def aead_exception_test(backend, cipher_factory, mode_factory, + only_if, skip_message): + if not only_if(backend): + pytest.skip(skip_message) + cipher = Cipher( + cipher_factory(binascii.unhexlify(b"0" * 32)), + mode_factory(binascii.unhexlify(b"0" * 24)), + backend + ) + encryptor = cipher.encryptor() + encryptor.update(b"a" * 16) + with pytest.raises(NotYetFinalized): + encryptor.tag + with pytest.raises(AlreadyUpdated): + encryptor.authenticate_additional_data(b"b" * 16) + encryptor.finalize() + with pytest.raises(AlreadyFinalized): + encryptor.authenticate_additional_data(b"b" * 16) + with pytest.raises(AlreadyFinalized): + encryptor.update(b"b" * 16) + with pytest.raises(AlreadyFinalized): + encryptor.finalize() + cipher = Cipher( + cipher_factory(binascii.unhexlify(b"0" * 32)), + mode_factory(binascii.unhexlify(b"0" * 24), b"0" * 16), + backend + ) + decryptor = cipher.decryptor() + decryptor.update(b"a" * 16) + with pytest.raises(AttributeError): + decryptor.tag |