Merge pull request #176 from reaperhulk/gcm-support
[WIP] GCM support
diff --git a/cryptography/exceptions.py b/cryptography/exceptions.py
index c2e7149..e9d8819 100644
--- a/cryptography/exceptions.py
+++ b/cryptography/exceptions.py
@@ -18,3 +18,15 @@
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 9f8ea93..1b19dda 100644
--- a/cryptography/hazmat/bindings/openssl/backend.py
+++ b/cryptography/hazmat/bindings/openssl/backend.py
@@ -19,7 +19,7 @@
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 @@
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)
@@ -193,8 +198,10 @@
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 @@
@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 @@
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 @@
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 @@
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 48e6da6..b8615cb 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 @@
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 @@
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 1d0de68..e1c7018 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.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 8cc9d42..e3f4f58 100644
--- a/cryptography/hazmat/primitives/interfaces.py
+++ b/cryptography/hazmat/primitives/interfaces.py
@@ -56,6 +56,14 @@
"""
+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 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 c6f5a7c..087066b 100644
--- a/docs/exceptions.rst
+++ b/docs/exceptions.rst
@@ -8,6 +8,18 @@
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 edf3c05..8d8d558 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -118,6 +118,36 @@
: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 @@
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 @@
.. _`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 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..2806efd 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_exception_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_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 cee0b20..ebb8b5c 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_exception_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_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 6c67ddb..9aa3a89 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, NotYetFinalized, AlreadyUpdated, InvalidTag,
+)
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.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 @@
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