Add MODE_KWP (KeyWrap with Padding) for AES

Author: Legrandin

Changelog.rst

@@ -4,6 +4,11 @@ Changelog
 Under development
 ++++++++++++++++++++++++++
 
+New features
+---------------
+* Added cipher modes Key Wrap (KW, RFC3394) and Key Wrap with Padding (KWP, RFC5649).
+  Both are defined also in NIST SP 800-38F.
+
 Resolved issues
 ---------------
 * GH#862: For HashEdDSA and Ed448, sign() and verify() modified the state of the XOF.

Doc/index.rst

@@ -3,7 +3,7 @@ Welcome to PyCryptodome's documentation
 
 .. toctree::
    :maxdepth: 3
-   
+
    src/introduction
    src/features
    src/installation
@@ -12,6 +12,5 @@ Welcome to PyCryptodome's documentation
    src/examples
    src/faq
    src/contribute_support
-   src/future
    src/changelog
    src/license

Doc/src/cipher/modern.rst

@@ -28,7 +28,7 @@ This is the state machine for a cipher object:
 .. figure:: aead.png
     :align: center
     :figwidth: 80%
-    
+
     Generic state diagram for a AEAD cipher mode
 
 Beside the usual :meth:`encrypt()` and :meth:`decrypt()` already
@@ -550,3 +550,106 @@ Example (decryption with multiple chunks)::
     >>> except (ValueError, KeyError):
     >>>     print("Incorrect decryption")
 
+.. _kw_mode:
+
+KW mode
+--------
+`Key Wrapping <https://datatracker.ietf.org/doc/html/rfc3394>`_ 
+(or `NIST SP 800-38F <https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>`_)
+is an ad-hoc authenticated cipher mode designed to wrap cryptographic keys,
+and not other types of data.
+It is deterministic (it doesn't use nonces or IVs) and
+only works with ciphers with a block size of 128 bits (like AES).
+
+The cryptographic key to wrap must have a length multiple of 8.
+
+There is no reason to prefer this ad-hoc  mode to one like SIV.
+
+The :func:`new` function at the module level under ``Crypto.Cipher`` instantiates
+a new KW cipher object for the relevant base algorithm.
+In the following definition, ``<algorithm>`` can only be ``AES`` today:
+
+.. function:: Crypto.Cipher.<algorithm>.new(key, <algorithm>.MODE_KW)
+
+  Create a new Key Wrapping (KW) cipher object,
+  using <algorithm> as the base block cipher.
+
+  :param bytes key: the cryptographic key
+  :return: a KW cipher object
+
+The cipher object has one read-only attribute :attr:`block_size`,
+and two methods (``seal`` and ``unseal``).
+
+Example of encryption::
+
+    >>> from Crypto.Cipher import AES
+    >>> from Crypto.Random import get_random_bytes
+    >>>
+    >>> key_to_wrap = b"1234567890123456"
+    >>> wrapping_key = get_random_bytes(16)
+    >>> cipher = AES.new(wrapping_key, AES.MODE_KW)
+    >>> ciphertext = cipher.seal(key_to_wrap)
+
+Example of decryption::
+
+    >>> from Crypto.Cipher import AES
+    >>> from Crypto.Random import get_random_bytes
+    >>>
+    >>> wrapping_key = get_random_bytes(16)
+    >>> cipher = AES.new(wrapping_key, AES.MODE_KW)
+    >>> try:
+    >>>     unwrapped_key = cipher.unseal(ciphertext)
+    >>> except ValueError:
+    >>>     print("Invalid decryption")
+
+.. _kwp_mode:
+
+KWP mode
+--------
+`Key Wrapping with Padding <https://datatracker.ietf.org/doc/html/rfc5649>`_ 
+(or `NIST SP 800-38F <https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf>`_)
+is an ad-hoc authenticated cipher mode designed to wrap cryptographic keys,
+and not other types of data.
+It is deterministic (it doesn't use nonces or IVs) and
+only works with ciphers with a block size of 128 bits (like AES).
+
+The cryptographic key to wrap can have any length.
+
+There is no reason to prefer this ad-hoc  mode to one like SIV.
+
+The :func:`new` function at the module level under ``Crypto.Cipher`` instantiates
+a new KWP cipher object for the relevant base algorithm.
+In the following definition, ``<algorithm>`` can only be ``AES`` today:
+
+.. function:: Crypto.Cipher.<algorithm>.new(key, <algorithm>.MODE_KWP)
+
+  Create a new Key Wrapping with Padding (KWP) cipher object,
+  using <algorithm> as the base block cipher.
+
+  :param bytes key: the cryptographic key
+  :return: a KWP cipher object
+
+The cipher object has one read-only attribute :attr:`block_size`,
+and two methods (``seal`` and ``unseal``).
+
+Example of encryption::
+
+    >>> from Crypto.Cipher import AES
+    >>> from Crypto.Random import get_random_bytes
+    >>>
+    >>> key_to_wrap = b"1234567890123456"
+    >>> wrapping_key = get_random_bytes(16)
+    >>> cipher = AES.new(wrapping_key, AES.MODE_KWP)
+    >>> ciphertext = cipher.seal(key_to_wrap)
+
+Example of decryption::
+
+    >>> from Crypto.Cipher import AES
+    >>> from Crypto.Random import get_random_bytes
+    >>>
+    >>> wrapping_key = get_random_bytes(16)
+    >>> cipher = AES.new(wrapping_key, AES.MODE_KWP)
+    >>> try:
+    >>>     unwrapped_key = cipher.unseal(ciphertext)
+    >>> except ValueError:
+    >>>     print("Invalid decryption")

README.rst

@@ -44,7 +44,7 @@ For faster public key operations in Unix, you should install `GMP`_ in your syst
 PyCryptodome is a fork of PyCrypto. It brings the following enhancements
 with respect to the last official version of PyCrypto (2.6.1):
 
-* Authenticated encryption modes (GCM, CCM, EAX, SIV, OCB)
+* Authenticated encryption modes (GCM, CCM, EAX, SIV, OCB, KW, KWP)
 * Hybrid Public Key Encryption (HPKE)
 * Accelerated AES on Intel platforms via AES-NI
 * First class support for PyPy

lib/Crypto/Cipher/AES.py

@@ -41,8 +41,8 @@
 MODE_SIV = 10       #: Synthetic Initialization Vector (:ref:`siv_mode`)
 MODE_GCM = 11       #: Galois Counter Mode (:ref:`gcm_mode`)
 MODE_OCB = 12       #: Offset Code Book (:ref:`ocb_mode`)
-MODE_KW = 13        #: Key Wrap
-MODE_KWP = 14       #: Key Wrap with Padding
+MODE_KW = 13        #: Key Wrap (:ref:`kw_mode`)
+MODE_KWP = 14       #: Key Wrap with Padding (:ref:`kwp_mode`)
 
 _cproto = """
         int AES_start_operation(const uint8_t key[],

lib/Crypto/Cipher/__init__.py

@@ -81,6 +81,9 @@ def _create_cipher(factory, key, mode, *args, **kwargs):
         elif mode == 13:
             from Crypto.Cipher._mode_kw import _create_kw_cipher
             res = _create_kw_cipher(factory, **kwargs)
+        elif mode == 14:
+            from Crypto.Cipher._mode_kwp import _create_kwp_cipher
+            res = _create_kwp_cipher(factory, **kwargs)
 
     if res is None:
         raise ValueError("Mode not supported")

lib/Crypto/Cipher/_mode_kw.py

@@ -71,6 +71,7 @@ def __init__(self,
 
         self._factory = factory
         self._cipher = factory.new(key, factory.MODE_ECB)
+        self._done = False
 
     def seal(self, plaintext: Union[bytes, bytearray]) -> bytes:
         """Encrypt and authenticate (wrap) a cryptographic key.
@@ -85,13 +86,20 @@ def seal(self, plaintext: Union[bytes, bytearray]) -> bytes:
             The wrapped key.
         """
 
+        if self._done:
+            raise ValueError("The cipher cannot be used more than once")
+
         if len(plaintext) % 8:
             raise ValueError("The plaintext must have length multiple of 8 bytes")
 
         if len(plaintext) < 16:
             raise ValueError("The plaintext must be at least 16 bytes long")
 
+        if len(plaintext) >= 2**32:
+            raise ValueError("The plaintext is too long")
+
         res = W(self._cipher, b'\xA6\xA6\xA6\xA6\xA6\xA6\xA6\xA6' + plaintext)
+        self._done = True
         return res
 
     def unseal(self, ciphertext: Union[bytes, bytearray]) -> bytes:
@@ -110,6 +118,8 @@ def unseal(self, ciphertext: Union[bytes, bytearray]) -> bytes:
            If the ciphertext or the key are not valid.
         """
 
+        if self._done:
+            raise ValueError("The cipher cannot be used more than once")
 
         if len(ciphertext) % 8:
             raise ValueError("The ciphertext must have length multiple of 8 bytes")
@@ -121,6 +131,7 @@ def unseal(self, ciphertext: Union[bytes, bytearray]) -> bytes:
 
         if pt[:8] != b'\xA6\xA6\xA6\xA6\xA6\xA6\xA6\xA6':
             raise ValueError("Incorrect integrity check value")
+        self._done = True
 
         return pt[8:]
 

lib/Crypto/Cipher/_mode_kwp.py

@@ -0,0 +1,135 @@
+import struct
+
+from types import ModuleType
+from typing import Union
+
+from ._mode_kw import W, W_inverse
+
+
+class KWPMode(object):
+    """Key Wrap with Padding (KWP) mode.
+
+    This is a deterministic Authenticated Encryption (AE) mode
+    for protecting cryptographic keys. See `NIST SP800-38F`_.
+
+    It provides both confidentiality and authenticity, and it designed
+    so that any bit of the ciphertext depends on all bits of the plaintext.
+
+    This mode is only available for ciphers that operate on 128 bits blocks
+    (e.g., AES).
+
+    .. _`NIST SP800-38F`: http://csrc.nist.gov/publications/nistpubs/800-38F/SP-800-38F.pdf
+
+    :undocumented: __init__
+    """
+
+    def __init__(self,
+                 factory: ModuleType,
+                 key: Union[bytes, bytearray]):
+
+        self.block_size = factory.block_size
+        if self.block_size != 16:
+            raise ValueError("Key Wrap with Padding mode is only available for ciphers"
+                             " that operate on 128 bits blocks")
+
+        self._factory = factory
+        self._cipher = factory.new(key, factory.MODE_ECB)
+        self._done = False
+
+    def seal(self, plaintext: Union[bytes, bytearray]) -> bytes:
+        """Encrypt and authenticate (wrap) a cryptographic key.
+
+        Args:
+          plaintext:
+            The cryptographic key to wrap.
+
+        Returns:
+            The wrapped key.
+        """
+
+        if self._done:
+            raise ValueError("The cipher cannot be used more than once")
+
+        if len(plaintext) == 0:
+            raise ValueError("The plaintext must be at least 1 byte")
+
+        if len(plaintext) >= 2 ** 32:
+            raise ValueError("The plaintext is too long")
+
+        padlen = (8 - len(plaintext)) % 8
+        padded = plaintext + b'\x00' * padlen
+
+        AIV = b'\xA6\x59\x59\xA6' + struct.pack('>I', len(plaintext))
+
+        if len(padded) == 8:
+            res = self._cipher.encrypt(AIV + padded)
+        else:
+            res = W(self._cipher, AIV + padded)
+
+        return res
+
+    def unseal(self, ciphertext: Union[bytes, bytearray]) -> bytes:
+        """Decrypt and authenticate (unwrap) a cryptographic key.
+
+        Args:
+          ciphertext:
+            The cryptographic key to unwrap.
+            It must be at least 16 bytes long, and its length
+            must be a multiple of 8.
+
+        Returns:
+            The original key.
+
+        Raises: ValueError
+           If the ciphertext or the key are not valid.
+        """
+
+        if self._done:
+            raise ValueError("The cipher cannot be used more than once")
+
+        if len(ciphertext) % 8:
+            raise ValueError("The ciphertext must have length multiple of 8 bytes")
+
+        if len(ciphertext) < 16:
+            raise ValueError("The ciphertext must be at least 24 bytes long")
+
+        if len(ciphertext) == 16:
+            S = self._cipher.decrypt(ciphertext)
+        else:
+            S = W_inverse(self._cipher, ciphertext)
+
+        if S[:4] != b'\xA6\x59\x59\xA6':
+            raise ValueError("Incorrect decryption")
+
+        Plen = struct.unpack('>I', S[4:8])[0]
+
+        padlen = len(S) - 8 - Plen
+        if padlen < 0 or padlen > 7:
+            raise ValueError("Incorrect decryption")
+
+        if S[len(S) - padlen:] != b'\x00' * padlen:
+            raise ValueError("Incorrect decryption")
+
+        return S[8:len(S) - padlen]
+
+
+def _create_kwp_cipher(factory: ModuleType,
+                       **kwargs: Union[bytes, bytearray]) -> KWPMode:
+    """Create a new block cipher in Key Wrap with Padding mode.
+
+    Args:
+      factory:
+        A block cipher module, taken from `Crypto.Cipher`.
+        The cipher must have block length of 16 bytes, such as AES.
+
+    Keywords:
+      key:
+        The secret key to use to seal or unseal.
+    """
+
+    try:
+        key = kwargs["key"]
+    except KeyError as e:
+        raise TypeError("Missing parameter:" + str(e))
+
+    return KWPMode(factory, key)