Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
99 lines (62 sloc) 2.98 KB
.. 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`
        instance 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`
        instance 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.

.. function:: aes_key_wrap_with_padding(wrapping_key, key_to_wrap, backend)

    .. versionadded:: 2.2

    This function performs AES key wrap with padding as specified in
    :rfc:`5649`.

    :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`
        instance that supports
        :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`.

    :return bytes: The wrapped key as bytes.

.. function:: aes_key_unwrap_with_padding(wrapping_key, wrapped_key, backend)

    .. versionadded:: 2.2

    This function performs AES key unwrap with padding as specified in
    :rfc:`5649`.

    :param bytes wrapping_key: The wrapping key.

    :param bytes wrapped_key: The wrapped key.

    :param backend: A
        :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
        instance 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

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.