From ca8e1615068efba728c2e8faf16f04ed0d1f6e29 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 16 Mar 2015 20:57:09 -0500 Subject: AES keywrap support --- docs/hazmat/primitives/index.rst | 1 + docs/hazmat/primitives/keywrap.rst | 43 ++++++++ .../hazmat/backends/openssl/backend.py | 2 +- src/cryptography/hazmat/primitives/keywrap.py | 84 ++++++++++++++++ tests/hazmat/primitives/test_keywrap.py | 112 +++++++++++++++++++++ 5 files changed, 241 insertions(+), 1 deletion(-) create mode 100644 docs/hazmat/primitives/keywrap.rst create mode 100644 src/cryptography/hazmat/primitives/keywrap.py create mode 100644 tests/hazmat/primitives/test_keywrap.py diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index a9ab38a0..cf27622a 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -11,6 +11,7 @@ Primitives symmetric-encryption padding key-derivation-functions + keywrap asymmetric/index constant-time interfaces diff --git a/docs/hazmat/primitives/keywrap.rst b/docs/hazmat/primitives/keywrap.rst new file mode 100644 index 00000000..2ef6b798 --- /dev/null +++ b/docs/hazmat/primitives/keywrap.rst @@ -0,0 +1,43 @@ +.. hazmat:: + +.. module:: cryptography.hazmat.primitives.keywrap + +Key wrapping +============ + +Key wrapping is a cryptographic construct that uses symmetric encryption to +encapsulate key material. + +.. function:: aes_key_wrap(wrapping_key, key_to_wrap, backend) + + :param bytes wrapping_key: The wrapping key. + + :param bytes key_to_wrap: The key to wrap. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + provider that supports + :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`. + + :return bytes: The wrapped key as bytes. + +.. function:: aes_key_unwrap(wrapping_key, wrapped_key, backend) + + :param bytes wrapping_key: The wrapping key. + + :param bytes wrapped_key: The wrapped key. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + provider that supports + :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`. + + :return bytes: The unwrapped key as bytes. + +Exceptions +~~~~~~~~~~ + +.. class:: InvalidUnwrap + + This is raised when a wrapped key fails to unwrap. It can be caused by a + corrupted or invalid wrapped key or an invalid wrapping key. diff --git a/src/cryptography/hazmat/backends/openssl/backend.py b/src/cryptography/hazmat/backends/openssl/backend.py index 58587b94..4c3402f6 100644 --- a/src/cryptography/hazmat/backends/openssl/backend.py +++ b/src/cryptography/hazmat/backends/openssl/backend.py @@ -41,7 +41,7 @@ from cryptography.hazmat.backends.openssl.x509 import ( _DISTPOINT_TYPE_FULLNAME, _DISTPOINT_TYPE_RELATIVENAME ) from cryptography.hazmat.bindings.openssl import binding -from cryptography.hazmat.primitives import hashes, serialization +from cryptography.hazmat.primitives import hashes, keywrap, serialization from cryptography.hazmat.primitives.asymmetric import dsa, ec, rsa from cryptography.hazmat.primitives.asymmetric.padding import ( MGF1, OAEP, PKCS1v15, PSS diff --git a/src/cryptography/hazmat/primitives/keywrap.py b/src/cryptography/hazmat/primitives/keywrap.py new file mode 100644 index 00000000..89925f3d --- /dev/null +++ b/src/cryptography/hazmat/primitives/keywrap.py @@ -0,0 +1,84 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import absolute_import, division, print_function + +import struct + +from cryptography.hazmat.primitives.ciphers import Cipher +from cryptography.hazmat.primitives.ciphers.algorithms import AES +from cryptography.hazmat.primitives.ciphers.modes import ECB +from cryptography.hazmat.primitives.constant_time import bytes_eq + + +def aes_key_wrap(wrapping_key, key_to_wrap, backend): + if len(wrapping_key) not in [16, 24, 32]: + raise ValueError("The wrapping key must be a valid AES key length") + + if len(key_to_wrap) < 16: + raise ValueError("The key to wrap must be at least 16 bytes") + + if len(key_to_wrap) % 8 != 0: + raise ValueError("The key to wrap must be a multiple of 8 bytes") + + # RFC 3394 Key Wrap - 2.2.1 (index method) + encryptor = Cipher(AES(wrapping_key), ECB(), backend).encryptor() + a = b"\xa6\xa6\xa6\xa6\xa6\xa6\xa6\xa6" + r = [key_to_wrap[i:i + 8] for i in range(0, len(key_to_wrap), 8)] + n = len(r) + for j in range(6): + for i in range(n): + # every encryption operation is a discrete 16 byte chunk so + # it is safe to reuse the encryptor for the entire operation + b = encryptor.update(a + r[i]) + # pack/unpack are safe as these are always 64-bit chunks + a = struct.pack( + ">Q", struct.unpack(">Q", b[:8])[0] ^ ((n * j) + i + 1) + ) + r[i] = b[-8:] + + assert encryptor.finalize() == b"" + + return a + b"".join(r) + + +def aes_key_unwrap(wrapping_key, wrapped_key, backend): + if len(wrapped_key) < 24: + raise ValueError("Must be at least 24 bytes") + + if len(wrapped_key) % 8 != 0: + raise ValueError("The wrapped key must be a multiple of 8 bytes") + + if len(wrapping_key) not in [16, 24, 32]: + raise ValueError("The wrapping key must be a valid AES key length") + + # Implement RFC 3394 Key Unwrap - 2.2.2 (index method) + decryptor = Cipher(AES(wrapping_key), ECB(), backend).decryptor() + aiv = b"\xa6\xa6\xa6\xa6\xa6\xa6\xa6\xa6" + + r = [wrapped_key[i:i + 8] for i in range(0, len(wrapped_key), 8)] + a = r.pop(0) + n = len(r) + for j in reversed(range(6)): + for i in reversed(range(n)): + # pack/unpack are safe as these are always 64-bit chunks + atr = struct.pack( + ">Q", struct.unpack(">Q", a)[0] ^ ((n * j) + i + 1) + ) + r[i] + # every decryption operation is a discrete 16 byte chunk so + # it is safe to reuse the decryptor for the entire operation + b = decryptor.update(atr) + a = b[:8] + r[i] = b[-8:] + + assert decryptor.finalize() == b"" + + if not bytes_eq(a, aiv): + raise InvalidUnwrap() + + return b"".join(r) + + +class InvalidUnwrap(Exception): + pass diff --git a/tests/hazmat/primitives/test_keywrap.py b/tests/hazmat/primitives/test_keywrap.py new file mode 100644 index 00000000..f49cdade --- /dev/null +++ b/tests/hazmat/primitives/test_keywrap.py @@ -0,0 +1,112 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import absolute_import, division, print_function + +import binascii +import os + +import pytest + +from cryptography.hazmat.backends.interfaces import CipherBackend +from cryptography.hazmat.primitives import keywrap +from cryptography.hazmat.primitives.ciphers import algorithms, modes + +from .utils import _load_all_params +from ...utils import load_nist_vectors + + +@pytest.mark.requires_backend_interface(interface=CipherBackend) +class TestAESKeyWrap(object): + @pytest.mark.parametrize( + "params", + _load_all_params( + os.path.join("keywrap", "kwtestvectors"), + ["KW_AE_128.txt", "KW_AE_192.txt", "KW_AE_256.txt"], + load_nist_vectors + ) + ) + @pytest.mark.supported( + only_if=lambda backend: backend.cipher_supported( + algorithms.AES("\x00" * 16), modes.ECB() + ), + skip_message="Does not support AES key wrap (RFC 3394)", + ) + def test_wrap(self, backend, params): + wrapping_key = binascii.unhexlify(params["k"]) + key_to_wrap = binascii.unhexlify(params["p"]) + wrapped_key = keywrap.aes_key_wrap(wrapping_key, key_to_wrap, backend) + assert params["c"] == binascii.hexlify(wrapped_key) + + @pytest.mark.parametrize( + "params", + _load_all_params( + os.path.join("keywrap", "kwtestvectors"), + ["KW_AD_128.txt", "KW_AD_192.txt", "KW_AD_256.txt"], + load_nist_vectors + ) + ) + @pytest.mark.supported( + only_if=lambda backend: backend.cipher_supported( + algorithms.AES("\x00" * 16), modes.ECB() + ), + skip_message="Does not support AES key wrap (RFC 3394)", + ) + def test_unwrap(self, backend, params): + wrapping_key = binascii.unhexlify(params["k"]) + wrapped_key = binascii.unhexlify(params["c"]) + if params.get("fail") is True: + with pytest.raises(keywrap.InvalidUnwrap): + keywrap.aes_key_unwrap(wrapping_key, wrapped_key, backend) + else: + unwrapped_key = keywrap.aes_key_unwrap( + wrapping_key, wrapped_key, backend + ) + assert params["p"] == binascii.hexlify(unwrapped_key) + + @pytest.mark.supported( + only_if=lambda backend: backend.cipher_supported( + algorithms.AES("\x00" * 16), modes.ECB() + ), + skip_message="Does not support AES key wrap (RFC 3394)", + ) + def test_wrap_invalid_key_length(self, backend): + with pytest.raises(ValueError): + keywrap.aes_key_wrap(b"badkey", b"sixteen_byte_key", backend) + + @pytest.mark.supported( + only_if=lambda backend: backend.cipher_supported( + algorithms.AES("\x00" * 16), modes.ECB() + ), + skip_message="Does not support AES key wrap (RFC 3394)", + ) + def test_unwrap_invalid_key_length(self, backend): + with pytest.raises(ValueError): + keywrap.aes_key_unwrap(b"badkey", b"\x00" * 24, backend) + + @pytest.mark.supported( + only_if=lambda backend: backend.cipher_supported( + algorithms.AES("\x00" * 16), modes.ECB() + ), + skip_message="Does not support AES key wrap (RFC 3394)", + ) + def test_wrap_invalid_key_to_wrap_length(self, backend): + with pytest.raises(ValueError): + keywrap.aes_key_wrap(b"sixteen_byte_key", b"\x00" * 15, backend) + + with pytest.raises(ValueError): + keywrap.aes_key_wrap(b"sixteen_byte_key", b"\x00" * 23, backend) + + @pytest.mark.supported( + only_if=lambda backend: backend.cipher_supported( + algorithms.AES("\x00" * 16), modes.ECB() + ), + skip_message="Does not support AES key wrap (RFC 3394)", + ) + def test_unwrap_invalid_wrapped_key_length(self, backend): + with pytest.raises(ValueError): + keywrap.aes_key_unwrap(b"sixteen_byte_key", b"\x00" * 16, backend) + + with pytest.raises(ValueError): + keywrap.aes_key_unwrap(b"sixteen_byte_key", b"\x00" * 27, backend) -- cgit v1.2.3 From 0d76a2e5dafec9f5da42cd671be8c72f5b78e98c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 17 May 2015 13:36:13 -0700 Subject: add changelog entry --- CHANGELOG.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index dd476a91..b64a0d18 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -12,6 +12,9 @@ Changelog * Added support for parsing certificate revocation lists (CRLs) using :func:`~cryptography.x509.load_pem_x509_crl` and :func:`~cryptography.x509.load_der_x509_crl`. +* Add support for AES key wrapping with + :func:`~cryptography.hazmat.primitives.keywrap.aes_key_wrap` and + :func:`~cryptography.hazmat.primitives.keywrap.aes_key_unwrap`. 1.0.2 - 2015-09-27 ~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From 128567a49a673287541bce4b8175170e8afbbd26 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 17 May 2015 13:58:51 -0700 Subject: pep8! --- src/cryptography/hazmat/backends/openssl/backend.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cryptography/hazmat/backends/openssl/backend.py b/src/cryptography/hazmat/backends/openssl/backend.py index 4c3402f6..58587b94 100644 --- a/src/cryptography/hazmat/backends/openssl/backend.py +++ b/src/cryptography/hazmat/backends/openssl/backend.py @@ -41,7 +41,7 @@ from cryptography.hazmat.backends.openssl.x509 import ( _DISTPOINT_TYPE_FULLNAME, _DISTPOINT_TYPE_RELATIVENAME ) from cryptography.hazmat.bindings.openssl import binding -from cryptography.hazmat.primitives import hashes, keywrap, serialization +from cryptography.hazmat.primitives import hashes, serialization from cryptography.hazmat.primitives.asymmetric import dsa, ec, rsa from cryptography.hazmat.primitives.asymmetric.padding import ( MGF1, OAEP, PKCS1v15, PSS -- cgit v1.2.3 From 6f6cf005fbcc4ae8a45affd3baae4d0d701fe1e3 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 17 Jun 2015 19:58:10 -0600 Subject: add version added info and doc exception --- docs/hazmat/primitives/keywrap.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/hazmat/primitives/keywrap.rst b/docs/hazmat/primitives/keywrap.rst index 2ef6b798..1b49a4c5 100644 --- a/docs/hazmat/primitives/keywrap.rst +++ b/docs/hazmat/primitives/keywrap.rst @@ -10,6 +10,8 @@ encapsulate key material. .. function:: aes_key_wrap(wrapping_key, key_to_wrap, backend) + .. versionadded:: 1.1 + :param bytes wrapping_key: The wrapping key. :param bytes key_to_wrap: The key to wrap. @@ -23,6 +25,8 @@ encapsulate key material. .. function:: aes_key_unwrap(wrapping_key, wrapped_key, backend) + .. versionadded:: 1.1 + :param bytes wrapping_key: The wrapping key. :param bytes wrapped_key: The wrapped key. @@ -34,6 +38,9 @@ encapsulate key material. :return bytes: The unwrapped key as bytes. + :raises cryptography.hazmat.primitives.keywrap.InvalidUnwrap: This is + raised if the key is not successfully unwrapped. + Exceptions ~~~~~~~~~~ -- cgit v1.2.3 From cee3736564033cce48f39ab5653f3ba323da0e10 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 17 Oct 2015 09:40:05 -0500 Subject: make skip message more verbose --- tests/hazmat/primitives/test_keywrap.py | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/tests/hazmat/primitives/test_keywrap.py b/tests/hazmat/primitives/test_keywrap.py index f49cdade..b1cf5ed8 100644 --- a/tests/hazmat/primitives/test_keywrap.py +++ b/tests/hazmat/primitives/test_keywrap.py @@ -31,7 +31,8 @@ class TestAESKeyWrap(object): only_if=lambda backend: backend.cipher_supported( algorithms.AES("\x00" * 16), modes.ECB() ), - skip_message="Does not support AES key wrap (RFC 3394)", + skip_message="Does not support AES key wrap (RFC 3394) because AES-ECB" + " is unsupported", ) def test_wrap(self, backend, params): wrapping_key = binascii.unhexlify(params["k"]) @@ -51,7 +52,8 @@ class TestAESKeyWrap(object): only_if=lambda backend: backend.cipher_supported( algorithms.AES("\x00" * 16), modes.ECB() ), - skip_message="Does not support AES key wrap (RFC 3394)", + skip_message="Does not support AES key wrap (RFC 3394) because AES-ECB" + " is unsupported", ) def test_unwrap(self, backend, params): wrapping_key = binascii.unhexlify(params["k"]) @@ -69,7 +71,8 @@ class TestAESKeyWrap(object): only_if=lambda backend: backend.cipher_supported( algorithms.AES("\x00" * 16), modes.ECB() ), - skip_message="Does not support AES key wrap (RFC 3394)", + skip_message="Does not support AES key wrap (RFC 3394) because AES-ECB" + " is unsupported", ) def test_wrap_invalid_key_length(self, backend): with pytest.raises(ValueError): @@ -79,7 +82,8 @@ class TestAESKeyWrap(object): only_if=lambda backend: backend.cipher_supported( algorithms.AES("\x00" * 16), modes.ECB() ), - skip_message="Does not support AES key wrap (RFC 3394)", + skip_message="Does not support AES key wrap (RFC 3394) because AES-ECB" + " is unsupported", ) def test_unwrap_invalid_key_length(self, backend): with pytest.raises(ValueError): @@ -89,7 +93,8 @@ class TestAESKeyWrap(object): only_if=lambda backend: backend.cipher_supported( algorithms.AES("\x00" * 16), modes.ECB() ), - skip_message="Does not support AES key wrap (RFC 3394)", + skip_message="Does not support AES key wrap (RFC 3394) because AES-ECB" + " is unsupported", ) def test_wrap_invalid_key_to_wrap_length(self, backend): with pytest.raises(ValueError): @@ -98,12 +103,6 @@ class TestAESKeyWrap(object): with pytest.raises(ValueError): keywrap.aes_key_wrap(b"sixteen_byte_key", b"\x00" * 23, backend) - @pytest.mark.supported( - only_if=lambda backend: backend.cipher_supported( - algorithms.AES("\x00" * 16), modes.ECB() - ), - skip_message="Does not support AES key wrap (RFC 3394)", - ) def test_unwrap_invalid_wrapped_key_length(self, backend): with pytest.raises(ValueError): keywrap.aes_key_unwrap(b"sixteen_byte_key", b"\x00" * 16, backend) -- cgit v1.2.3 From 42e029b66000ace57246fcec4cb72a5e18652487 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 17 Oct 2015 09:52:04 -0500 Subject: expand keywrap intro docs --- docs/hazmat/primitives/keywrap.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/hazmat/primitives/keywrap.rst b/docs/hazmat/primitives/keywrap.rst index 1b49a4c5..429e8928 100644 --- a/docs/hazmat/primitives/keywrap.rst +++ b/docs/hazmat/primitives/keywrap.rst @@ -6,7 +6,10 @@ Key wrapping ============ Key wrapping is a cryptographic construct that uses symmetric encryption to -encapsulate key material. +encapsulate key material. Key wrapping algorithms are occasionally utilized +to protect keys at rest or transmit them over insecure networks. Many of the +protections offered by key wrapping are also offered by using authenticated +:doc:`symmetric encryption `. .. function:: aes_key_wrap(wrapping_key, key_to_wrap, backend) -- cgit v1.2.3 From 974e875492b750fbbb6505a761a0120f09ff34cc Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 22 Oct 2015 11:21:55 -0500 Subject: add info about the rfc --- docs/hazmat/primitives/keywrap.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/hazmat/primitives/keywrap.rst b/docs/hazmat/primitives/keywrap.rst index 429e8928..e4f9ffeb 100644 --- a/docs/hazmat/primitives/keywrap.rst +++ b/docs/hazmat/primitives/keywrap.rst @@ -15,6 +15,9 @@ protections offered by key wrapping are also offered by using authenticated .. versionadded:: 1.1 + This function performs AES key wrap (without padding) as specified in + :rfc:`3394`. + :param bytes wrapping_key: The wrapping key. :param bytes key_to_wrap: The key to wrap. @@ -30,6 +33,9 @@ protections offered by key wrapping are also offered by using authenticated .. versionadded:: 1.1 + This function performs AES key unwrap (without padding) as specified in + :rfc:`3394`. + :param bytes wrapping_key: The wrapping key. :param bytes wrapped_key: The wrapped key. -- cgit v1.2.3 From 5af3043b9f8ab5fa2b2e4aa16bba0c00d044055a Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 22 Oct 2015 11:31:20 -0500 Subject: update a comment --- src/cryptography/hazmat/primitives/keywrap.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/cryptography/hazmat/primitives/keywrap.py b/src/cryptography/hazmat/primitives/keywrap.py index 89925f3d..6e79ab6b 100644 --- a/src/cryptography/hazmat/primitives/keywrap.py +++ b/src/cryptography/hazmat/primitives/keywrap.py @@ -29,8 +29,9 @@ def aes_key_wrap(wrapping_key, key_to_wrap, backend): n = len(r) for j in range(6): for i in range(n): - # every encryption operation is a discrete 16 byte chunk so - # it is safe to reuse the encryptor for the entire operation + # every encryption operation is a discrete 16 byte chunk (because + # AES has a 128-bit block size) and since we're using ECB it is + # safe to reuse the encryptor for the entire operation b = encryptor.update(a + r[i]) # pack/unpack are safe as these are always 64-bit chunks a = struct.pack( -- cgit v1.2.3 From 68bab79cda9ce48d85e2611e9ada9d5f7f44321c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 22 Oct 2015 11:37:34 -0500 Subject: add comments on test cases to explain reasons a bit better --- tests/hazmat/primitives/test_keywrap.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tests/hazmat/primitives/test_keywrap.py b/tests/hazmat/primitives/test_keywrap.py index b1cf5ed8..f1238c9a 100644 --- a/tests/hazmat/primitives/test_keywrap.py +++ b/tests/hazmat/primitives/test_keywrap.py @@ -75,6 +75,7 @@ class TestAESKeyWrap(object): " is unsupported", ) def test_wrap_invalid_key_length(self, backend): + # The wrapping key must be of length [16, 24, 32] with pytest.raises(ValueError): keywrap.aes_key_wrap(b"badkey", b"sixteen_byte_key", backend) @@ -97,15 +98,19 @@ class TestAESKeyWrap(object): " is unsupported", ) def test_wrap_invalid_key_to_wrap_length(self, backend): + # Keys to wrap must be at least 16 bytes long with pytest.raises(ValueError): keywrap.aes_key_wrap(b"sixteen_byte_key", b"\x00" * 15, backend) + # Keys to wrap must be a multiple of 8 bytes with pytest.raises(ValueError): keywrap.aes_key_wrap(b"sixteen_byte_key", b"\x00" * 23, backend) def test_unwrap_invalid_wrapped_key_length(self, backend): + # Keys to unwrap must be at least 24 bytes with pytest.raises(ValueError): keywrap.aes_key_unwrap(b"sixteen_byte_key", b"\x00" * 16, backend) + # Keys to unwrap must be a multiple of 8 bytes with pytest.raises(ValueError): keywrap.aes_key_unwrap(b"sixteen_byte_key", b"\x00" * 27, backend) -- cgit v1.2.3