Merge branch 'key_wrap'

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,7 +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 (: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

@@ -22,45 +22,10 @@
 #
 # where mode_state is a a pointer to base_cipher_state plus mode-specific data.
 
-import os
-
-from Crypto.Cipher._mode_ecb import _create_ecb_cipher
-from Crypto.Cipher._mode_cbc import _create_cbc_cipher
-from Crypto.Cipher._mode_cfb import _create_cfb_cipher
-from Crypto.Cipher._mode_ofb import _create_ofb_cipher
-from Crypto.Cipher._mode_ctr import _create_ctr_cipher
-from Crypto.Cipher._mode_openpgp import _create_openpgp_cipher
-from Crypto.Cipher._mode_ccm import _create_ccm_cipher
-from Crypto.Cipher._mode_eax import _create_eax_cipher
-from Crypto.Cipher._mode_siv import _create_siv_cipher
-from Crypto.Cipher._mode_gcm import _create_gcm_cipher
-from Crypto.Cipher._mode_ocb import _create_ocb_cipher
-
-_modes = { 1:_create_ecb_cipher,
-           2:_create_cbc_cipher,
-           3:_create_cfb_cipher,
-           5:_create_ofb_cipher,
-           6:_create_ctr_cipher,
-           7:_create_openpgp_cipher,
-           9:_create_eax_cipher
-           }
-
-_extra_modes = { 8:_create_ccm_cipher,
-                10:_create_siv_cipher,
-                11:_create_gcm_cipher,
-                12:_create_ocb_cipher
-                }
-
 def _create_cipher(factory, key, mode, *args, **kwargs):
 
     kwargs["key"] = key
 
-    modes = dict(_modes)
-    if kwargs.pop("add_aes_modes", False):
-        modes.update(_extra_modes)
-    if not mode in modes:
-        raise ValueError("Mode not supported")
-
     if args:
         if mode in (8, 9, 10, 11, 12):
             if len(args) > 1:
@@ -76,4 +41,51 @@ def _create_cipher(factory, key, mode, *args, **kwargs):
         elif mode == 1:
             raise TypeError("IV is not meaningful for the ECB mode")
 
-    return modes[mode](factory, **kwargs)
+    res = None
+    extra_modes = kwargs.pop("add_aes_modes", False)
+
+    if mode == 1:
+        from Crypto.Cipher._mode_ecb import _create_ecb_cipher
+        res = _create_ecb_cipher(factory, **kwargs)
+    elif mode == 2:
+        from Crypto.Cipher._mode_cbc import _create_cbc_cipher
+        res = _create_cbc_cipher(factory, **kwargs)
+    elif mode == 3:
+        from Crypto.Cipher._mode_cfb import _create_cfb_cipher
+        res = _create_cfb_cipher(factory, **kwargs)
+    elif mode == 5:
+        from Crypto.Cipher._mode_ofb import _create_ofb_cipher
+        res = _create_ofb_cipher(factory, **kwargs)
+    elif mode == 6:
+        from Crypto.Cipher._mode_ctr import _create_ctr_cipher
+        res = _create_ctr_cipher(factory, **kwargs)
+    elif mode == 7:
+        from Crypto.Cipher._mode_openpgp import _create_openpgp_cipher
+        res = _create_openpgp_cipher(factory, **kwargs)
+    elif mode == 9:
+        from Crypto.Cipher._mode_eax import _create_eax_cipher
+        res = _create_eax_cipher(factory, **kwargs)
+    elif extra_modes:
+        if mode == 8:
+            from Crypto.Cipher._mode_ccm import _create_ccm_cipher
+            res = _create_ccm_cipher(factory, **kwargs)
+        elif mode == 10:
+            from Crypto.Cipher._mode_siv import _create_siv_cipher
+            res = _create_siv_cipher(factory, **kwargs)
+        elif mode == 11:
+            from Crypto.Cipher._mode_gcm import _create_gcm_cipher
+            res = _create_gcm_cipher(factory, **kwargs)
+        elif mode == 12:
+            from Crypto.Cipher._mode_ocb import _create_ocb_cipher
+            res = _create_ocb_cipher(factory, **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")
+
+    return res