Merge pull request #1970 from reaperhulk/aes-keywrap-python

AES keywrap support

2 files changed, 60 insertions, 0 deletions

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..e4f9ffeb
--- /dev/null
+++ b/docs/hazmat/primitives/keywrap.rst
@@ -0,0 +1,59 @@
+.. hazmat::
+
+.. module:: cryptography.hazmat.primitives.keywrap
+
+Key wrapping
+============
+
+Key wrapping is a cryptographic construct that uses symmetric encryption to
+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 </hazmat/primitives/symmetric-encryption>`.
+
+.. function:: aes_key_wrap(wrapping_key, key_to_wrap, backend)
+
+    .. 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.
+
+    :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)
+
+    .. 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.
+
+    :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.
+
+    :raises cryptography.hazmat.primitives.keywrap.InvalidUnwrap: This is
+        raised if the key is not successfully unwrapped.
+
+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.