• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. hazmat::
2
3.. module:: cryptography.hazmat.primitives.keywrap
4
5Key wrapping
6============
7
8Key wrapping is a cryptographic construct that uses symmetric encryption to
9encapsulate key material. Key wrapping algorithms are occasionally utilized
10to protect keys at rest or transmit them over insecure networks. Many of the
11protections offered by key wrapping are also offered by using authenticated
12:doc:`symmetric encryption </hazmat/primitives/symmetric-encryption>`.
13
14.. function:: aes_key_wrap(wrapping_key, key_to_wrap, backend)
15
16    .. versionadded:: 1.1
17
18    This function performs AES key wrap (without padding) as specified in
19    :rfc:`3394`.
20
21    :param bytes wrapping_key: The wrapping key.
22
23    :param bytes key_to_wrap: The key to wrap.
24
25    :param backend: A
26        :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
27        instance that supports
28        :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`.
29
30    :return bytes: The wrapped key as bytes.
31
32.. function:: aes_key_unwrap(wrapping_key, wrapped_key, backend)
33
34    .. versionadded:: 1.1
35
36    This function performs AES key unwrap (without padding) as specified in
37    :rfc:`3394`.
38
39    :param bytes wrapping_key: The wrapping key.
40
41    :param bytes wrapped_key: The wrapped key.
42
43    :param backend: A
44        :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
45        instance that supports
46        :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`.
47
48    :return bytes: The unwrapped key as bytes.
49
50    :raises cryptography.hazmat.primitives.keywrap.InvalidUnwrap: This is
51        raised if the key is not successfully unwrapped.
52
53.. function:: aes_key_wrap_with_padding(wrapping_key, key_to_wrap, backend)
54
55    .. versionadded:: 2.2
56
57    This function performs AES key wrap with padding as specified in
58    :rfc:`5649`.
59
60    :param bytes wrapping_key: The wrapping key.
61
62    :param bytes key_to_wrap: The key to wrap.
63
64    :param backend: A
65        :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
66        instance that supports
67        :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`.
68
69    :return bytes: The wrapped key as bytes.
70
71.. function:: aes_key_unwrap_with_padding(wrapping_key, wrapped_key, backend)
72
73    .. versionadded:: 2.2
74
75    This function performs AES key unwrap with padding as specified in
76    :rfc:`5649`.
77
78    :param bytes wrapping_key: The wrapping key.
79
80    :param bytes wrapped_key: The wrapped key.
81
82    :param backend: A
83        :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
84        instance that supports
85        :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`.
86
87    :return bytes: The unwrapped key as bytes.
88
89    :raises cryptography.hazmat.primitives.keywrap.InvalidUnwrap: This is
90        raised if the key is not successfully unwrapped.
91
92Exceptions
93~~~~~~~~~~
94
95.. class:: InvalidUnwrap
96
97    This is raised when a wrapped key fails to unwrap. It can be caused by a
98    corrupted or invalid wrapped key or an invalid wrapping key.
99