aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/hazmat/primitives/index.rst1
-rw-r--r--docs/hazmat/primitives/keywrap.rst59
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.