GCM support
diff --git a/cryptography/exceptions.py b/cryptography/exceptions.py
index c2e7149..f2a731f 100644
--- a/cryptography/exceptions.py
+++ b/cryptography/exceptions.py
@@ -18,3 +18,7 @@
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 9f8ea93..08afa4d 100644
--- a/cryptography/hazmat/bindings/openssl/backend.py
+++ b/cryptography/hazmat/bindings/openssl/backend.py
@@ -28,7 +28,7 @@
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 @@
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 @@
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 @@
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 @@
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 48e6da6..5a4e785 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 @@
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 @@
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 1d0de68..cb191d9 100644
--- a/cryptography/hazmat/primitives/ciphers/modes.py
+++ b/cryptography/hazmat/primitives/ciphers/modes.py
@@ -56,3 +56,14 @@
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 8cc9d42..574c822 100644
--- a/cryptography/hazmat/primitives/interfaces.py
+++ b/cryptography/hazmat/primitives/interfaces.py
@@ -56,6 +56,10 @@
"""
+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 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 c6f5a7c..7ec3cd2 100644
--- a/docs/exceptions.rst
+++ b/docs/exceptions.rst
@@ -7,6 +7,11 @@
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 edf3c05..5b249c0 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -118,6 +118,27 @@
: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 @@
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 d178da7..f7b0b9a 100644
--- a/tests/hazmat/primitives/test_aes.py
+++ b/tests/hazmat/primitives/test_aes.py
@@ -18,7 +18,7 @@
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 @@
),
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 f6c44b4..296821a 100644
--- a/tests/hazmat/primitives/test_block.py
+++ b/tests/hazmat/primitives/test_block.py
@@ -18,12 +18,16 @@
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 @@
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 cee0b20..f286e02 100644
--- a/tests/hazmat/primitives/test_utils.py
+++ b/tests/hazmat/primitives/test_utils.py
@@ -2,7 +2,8 @@
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 @@
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 6c67ddb..839ff82 100644
--- a/tests/hazmat/primitives/utils.py
+++ b/tests/hazmat/primitives/utils.py
@@ -4,9 +4,11 @@
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 @@
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 @@
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)