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 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 docs/hazmat/primitives/keywrap.rst (limited to 'docs') 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. -- 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(+) (limited to 'docs') 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 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(-) (limited to 'docs') 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(+) (limited to 'docs') 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