GCM support

11 files changed, 334 insertions, 13 deletions

diff --git a/cryptography/exceptions.py b/cryptography/exceptions.py
index c2e71493..f2a731f0 100644
--- a/cryptography/exceptions.py
+++ b/cryptography/exceptions.py
@@ -18,3 +18,7 @@ class UnsupportedAlgorithm(Exception):
 
 class AlreadyFinalized(Exception):
     pass
+
+
+class NotFinalized(Exception):
+    pass
diff --git a/cryptography/hazmat/bindings/openssl/backend.py b/cryptography/hazmat/bindings/openssl/backend.py
index 9f8ea939..08afa4d6 100644
--- a/cryptography/hazmat/bindings/openssl/backend.py
+++ b/cryptography/hazmat/bindings/openssl/backend.py
@@ -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)
@@ -238,6 +243,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 +278,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,
@@ -298,10 +320,29 @@ class _CipherContext(object):
         if res == 0:
             self._backend._handle_error()
 
+        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
+            size = self._cipher.block_size
+            self._tag = self._backend.ffi.buffer(tag_buf)[:size]
+
         res = self._backend.lib.EVP_CIPHER_CTX_cleanup(self._ctx)
         assert res == 1
         return self._backend.ffi.buffer(buf)[:outlen[0]]
 
+    def add_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
+
 
 @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..5a4e7850 100644
--- a/cryptography/hazmat/primitives/ciphers/base.py
+++ b/cryptography/hazmat/primitives/ciphers/base.py
@@ -14,7 +14,7 @@
 from __future__ import absolute_import, division, print_function
 
 from cryptography import utils
-from cryptography.exceptions import AlreadyFinalized
+from cryptography.exceptions import AlreadyFinalized, NotFinalized
 from cryptography.hazmat.primitives import interfaces
 
 
@@ -28,20 +28,39 @@ class Cipher(object):
         self._backend = backend
 
     def encryptor(self):
-        return _CipherContext(self._backend.create_symmetric_encryption_ctx(
-            self.algorithm, self.mode
-        ))
+        if isinstance(self.mode, interfaces.ModeWithAAD):
+            return _AEADCipherContext(
+                self._backend.create_symmetric_encryption_ctx(
+                    self.algorithm, self.mode
+                )
+            )
+        else:
+            return _CipherContext(
+                self._backend.create_symmetric_encryption_ctx(
+                    self.algorithm, self.mode
+                )
+            )
 
     def decryptor(self):
-        return _CipherContext(self._backend.create_symmetric_decryption_ctx(
-            self.algorithm, self.mode
-        ))
+        if isinstance(self.mode, interfaces.ModeWithAAD):
+            return _AEADCipherContext(
+                self._backend.create_symmetric_decryption_ctx(
+                    self.algorithm, self.mode
+                )
+            )
+        else:
+            return _CipherContext(
+                self._backend.create_symmetric_decryption_ctx(
+                    self.algorithm, self.mode
+                )
+            )
 
 
 @utils.register_interface(interfaces.CipherContext)
 class _CipherContext(object):
     def __init__(self, ctx):
         self._ctx = ctx
+        self._tag = None
 
     def update(self, data):
         if self._ctx is None:
@@ -52,5 +71,22 @@ class _CipherContext(object):
         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
+
+
+@utils.register_interface(interfaces.AEADCipherContext)
+@utils.register_interface(interfaces.CipherContext)
+class _AEADCipherContext(_CipherContext):
+    def add_data(self, data):
+        if self._ctx is None:
+            raise AlreadyFinalized("Context was already finalized")
+        self._ctx.add_data(data)
+
+    @property
+    def tag(self):
+        if self._ctx is not None:
+            raise NotFinalized("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..cb191d98 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.ModeWithAAD)
+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..574c8226 100644
--- a/cryptography/hazmat/primitives/interfaces.py
+++ b/cryptography/hazmat/primitives/interfaces.py
@@ -56,6 +56,10 @@ class ModeWithNonce(six.with_metaclass(abc.ABCMeta)):
         """
 
 
+class ModeWithAAD(six.with_metaclass(abc.ABCMeta)):
+    pass
+
+
 class CipherContext(six.with_metaclass(abc.ABCMeta)):
     @abc.abstractmethod
     def update(self, data):
@@ -70,6 +74,20 @@ class CipherContext(six.with_metaclass(abc.ABCMeta)):
         """
 
 
+class AEADCipherContext(six.with_metaclass(abc.ABCMeta)):
+    @abc.abstractproperty
+    def tag(self):
+        """
+        Returns tag bytes after finalizing encryption.
+        """
+
+    @abc.abstractmethod
+    def add_data(self, data):
+        """
+        add_data takes bytes and returns nothing.
+        """
+
+
 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..7ec3cd27 100644
--- a/docs/exceptions.rst
+++ b/docs/exceptions.rst
@@ -7,6 +7,11 @@ Exceptions
 
     This is raised when a context is used after being finalized.
 
+.. class:: NotFinalized
+
+    This is raised when the AEAD tag property is accessed on a context
+    before it is finalized.
+
 
 .. class:: UnsupportedAlgorithm
 
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index edf3c050..5b249c06 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -118,6 +118,27 @@ 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. ``AEADCipherContext`` contains an additional method ``add_data``
+    for adding additional authenticated by non-encrypted data. You should call
+    this before calls to ``update``. When you are done call ``finalize()`` to
+    finish the operation. Once this is complete you can obtain the tag value
+    from the ``tag`` property.
+
+    .. method:: add_data(data)
+
+        :param bytes data: The data you wish to authenticate but not encrypt.
+        :raises: :class:`~cryptography.exceptions.AlreadyFinalized`
+
+    .. method:: tag
+
+        :return bytes: Returns the tag value as bytes.
+        :raises: :class:`~cryptography.exceptions.NotFinalized`
+
 .. _symmetric-encryption-algorithms:
 
 Algorithms
@@ -295,6 +316,33 @@ Modes
                                         reuse an ``initialization_vector`` with
                                         a given ``key``.
 
+.. class:: GCM(initialization_vector, tag=None)
+
+    GCM (Galois Counter Mode) is a mode of operation for block ciphers. It
+    is an AEAD (authenticated encryption with additional data) mode.
+
+    :param bytes initialization_vector: Must be random bytes. They do not need
+                                        to be kept secret (they can be included
+                                        in a transmitted message). Recommended
+                                        to be 96-bit by NIST, but can be up to
+                                        2\ :sup:`64` - 1 bits. Do not reuse an
+                                        ``initialization_vector`` with a given
+                                        ``key``.
+
+    .. doctest::
+
+        >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+        >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv))
+        >>> encryptor = cipher.encryptor()
+        >>> encryptor.add_data(b"authenticated but encrypted payload")
+        >>> ct = encryptor.update(b"a secret message") + encryptor.finalize()
+        >>> tag = encryptor.tag
+        >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag))
+        >>> decryptor = cipher.decryptor()
+        >>> decryptor.add_data(b"authenticated but encrypted payload")
+        >>> decryptor.update(ct) + decryptor.finalize()
+        'a secret message'
+
 
 Insecure Modes
 --------------
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..296821a4 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_use_after_finalize_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_use_after_finalize = generate_aead_use_after_finalize_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..f286e02d 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_use_after_finalize_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_use_after_finalize_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..839ff822 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, NotFinalized,
+)
 
 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.add_data(binascii.unhexlify(aad))
+        actual_plaintext = decryptor.update(binascii.unhexlify(ciphertext))
+        with pytest.raises(AssertionError):
+            decryptor.finalize()
+    else:
+        cipher = Cipher(
+            cipher_factory(binascii.unhexlify(params["key"])),
+            mode_factory(binascii.unhexlify(params["iv"]), None),
+            backend
+        )
+        encryptor = cipher.encryptor()
+        encryptor.add_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.add_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,36 @@ 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_use_after_finalize_test(cipher_factory, mode_factory,
+                                          only_if, skip_message):
+    def test_aead_use_after_finalize(self):
+        for backend in _ALL_BACKENDS:
+            yield (
+                aead_use_after_finalize_test,
+                backend,
+                cipher_factory,
+                mode_factory,
+                only_if,
+                skip_message
+            )
+    return test_aead_use_after_finalize
+
+
+def aead_use_after_finalize_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(NotFinalized):
+        encryptor.tag
+    encryptor.finalize()
+    with pytest.raises(AlreadyFinalized):
+        encryptor.add_data(b"b" * 16)