pyaescbc 0.1.0__py3-none-any.whl

pyaescbc/__init__.py

@@ -0,0 +1,64 @@
+# Copyright 2025 Artezaru
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .__version__ import __version__
+
+from .decrypt_AES_CBC import decrypt_AES_CBC
+from .derive_key import derive_key
+from .encrypt_AES_CBC import encrypt_AES_CBC
+
+from .cleardata_to_encrypted_bundle import cleardata_to_encrypted_bundle
+encrypt = cleardata_to_encrypted_bundle
+from .encrypted_bundle_to_cleardata import encrypted_bundle_to_cleardata
+decrypt = encrypted_bundle_to_cleardata
+
+from .create_encrypted_bundle import create_encrypted_bundle
+from .extract_cryptography_components import extract_cryptography_components
+
+from .generate_random_iterations import generate_random_iterations
+from .generate_pin_iterations import generate_pin_iterations
+
+from .random_bytearray import random_bytearray
+from .random_iv import random_iv
+from .random_salt import random_salt
+
+from .create_hmac import create_hmac
+from .check_hmac import check_hmac
+from .auth_error import AuthError
+
+from .delete_bytearray import delete_bytearray
+
+__all__ = [
+    "__version__",
+    "decrypt_AES_CBC",
+    "derive_key",
+    "encrypt_AES_CBC",
+    "cleardata_to_encrypted_bundle",
+    "encrypt",
+    "encrypted_bundle_to_cleardata",
+    "decrypt",
+    "create_encrypted_bundle",
+    "extract_cryptography_components",
+    "generate_random_iterations",
+    "generate_pin_iterations",
+    "random_bytearray",
+    "random_iv",
+    "random_salt",
+    "create_hmac",
+    "check_hmac",
+    "AuthError",
+    "delete_bytearray",
+]
+
+

pyaescbc/__main__.py

@@ -0,0 +1,40 @@
+# Copyright 2025 Artezaru
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+def __main__() -> None:
+    r"""
+    Main entry point of the package.
+
+    This method contains the script to run if the user enter the name of the package on the command line. 
+
+    .. code-block:: console
+
+        pyaescbc
+        
+    """
+    raise NotImplementedError("The main entry point is not implemented yet.")
+
+def __main_gui__() -> None:
+    r"""
+    Graphical user interface entry point of the package.
+
+    This method contains the script to run if the user enter the name of the package on the command line with the ``gui`` extension.
+
+    .. code-block:: console
+    
+        pyaescbc-gui
+        
+    """
+    raise NotImplementedError("The graphical user interface entry point is not implemented yet.")
+

pyaescbc/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pyaescbc/auth_error.py

@@ -0,0 +1,50 @@
+# Copyright 2025 Artezaru
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Optional
+
+class AuthError(Exception):
+    """
+    Exception raised for errors related to the decryption key in ``pyaescbc``.
+
+    This exception is typically raised when the provided password or key
+    is incorrect.
+
+    The display message will be shown in the following format if a code is provided:
+
+    .. code-block:: console
+
+        AuthError: [<code>] <message>
+
+    Parameters
+    ----------
+    message : str, optional
+        The error message to be displayed. Default is ""
+    code : Optional[int], optional
+        An optional error code associated with the exception. Default is None.
+
+    Notes
+    -----
+    You can raise this exception when the HMAC verification fails
+    during decryption, which usually means the wrong key was used (if the data were not 
+    """
+    def __init__(self, message: str = "", code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+    def __str__(self):
+        if self.code is not None:
+            return f"[{self.code}] {self.message}"
+        return self.message

pyaescbc/check_hmac.py

@@ -0,0 +1,56 @@
+# Copyright 2025 Artezaru
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import hmac
+
+def check_hmac(given_hmac: bytearray, expected_hmac: bytearray) -> bool:
+    """
+    Verifies if the derived 32-byte given HMAC matches the expected HMAC.
+
+    Parameters
+    ----------
+    given_hmac : bytearray
+        The 32-byte long HMAC to verify.
+
+    expected_hmac : bytearray
+        The 32-byte long expected HMAC.
+
+    Returns
+    -------
+    bool
+        True if the HMACs match, False otherwise.
+    
+    Raises
+    ------
+    TypeError
+        If any argument is not a `bytearray` instance.
+    ValueError
+        If the given_hmac or expected_hmac isn't 32 bytes.
+    """
+    # Check the types of the parameters
+    if not isinstance(given_hmac, bytearray):
+        raise TypeError('Parameter given_hmac is not bytearray instance.')
+    if not isinstance(expected_hmac, bytearray):
+        raise TypeError('Parameter expected_hmac is not bytearray instance.')
+
+    # Check the value of the parameters
+    if len(given_hmac) != 32:
+        raise ValueError(f'{given_hmac=} is not 32 bytes long.') 
+    if len(expected_hmac) != 32:
+        raise ValueError(f'{expected_hmac=} is not 32 bytes long.') 
+
+    # Compare the HMACs
+    result = hmac.compare_digest(given_hmac, expected_hmac)
+
+    return result

pyaescbc/cleardata_to_encrypted_bundle.py

@@ -0,0 +1,124 @@
+# Copyright 2025 Artezaru
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Optional
+
+from .random_salt import random_salt
+from .random_iv import random_iv
+from .derive_key import derive_key
+from .encrypt_AES_CBC import encrypt_AES_CBC
+from .create_hmac import create_hmac
+from .create_encrypted_bundle import create_encrypted_bundle
+from .delete_bytearray import delete_bytearray
+
+def cleardata_to_encrypted_bundle(
+    cleardata: bytearray, 
+    password: bytearray, 
+    iterations: int,
+    authdata: Optional[bytearray] = None,
+    delete_keys: bool = True
+) -> bytearray: 
+    """
+    cleardata_to_encrypted_bundle encrypts the clear data to generate the encrypted bundle.
+
+    The number of iterations can be generated using the function :func:`pyaescbc.generate_random_iterations` or :func:`pyaescbc.generate_pin_iterations`.
+
+    .. note::
+        
+        The cleardata, the password and the authdata are deleted from memory at the end of the function if delete_keys is True.
+        Otherwise, they need to be deleted after dealing with Exception.
+
+    .. note::
+
+        An alias for this function is ``encrypt``
+
+        .. code-block:: python
+
+            import pyaescbc as aes
+
+            cleardata = bytearray("Hello, World!", 'utf-8')
+            password = bytearray("password", 'utf-8')
+            iterations = aes.generate_random_iterations()
+            encrypted_bundle = aes.encrypt(cleardata, password, iterations, delete_keys=True)
+            # Or use : encrypted_bundle = aes.cleardata_to_encrypted_bundle(cleardata, password, iterations, delete_keys=True)
+
+    Parameters
+    ----------
+    cleardata : bytearray
+        The clear message to encrypt using AES in CBC mode.
+
+    password : bytearray
+        The user password. It must not be empty.
+
+    iterations : int
+        The number of iterations for PBKDF2. It must be a strictly positive integer.
+
+    authdata : Optional[bytearray]
+        The authentication data to use in the HMAC. Default is None.
+        If not None, it will be used to create the HMAC. 
+
+    delete_keys : bool
+        Delete the cleardata, the password and authdata from memory at the end of the function. Default is True.
+
+    Returns
+    -------
+    encrypted_bundle : bytearray
+        The encrypted bundle. 
+
+    Raises
+    ------
+    TypeError
+        If an argument is of the wrong type.
+    ValueError
+        If password is empty or if iterations is not a strictly positive integer.
+    """
+    # Check the types of the parameters
+    if (not isinstance(cleardata, bytearray)) or (not isinstance(password, bytearray)):
+        raise TypeError("Parameters cleardata or password is not bytearray")
+    if not isinstance(iterations, int):
+        raise TypeError("Parameter iterations is not integer")
+    if (authdata is not None) and (not isinstance(authdata, bytearray)):
+        raise TypeError("Parameter authdata is not bytearray")
+    if not isinstance(delete_keys, bool):
+        raise TypeError("Parameter delete_keys is not a boolean.")
+
+    # Encryption
+    try:
+        salt = random_salt()
+        iv = random_iv()
+        derived_key = derive_key(password, salt, iterations)
+        aes_key = derived_key[:32]  # AES key is the first 32 bytes of the derived key
+        hmac_key = derived_key[32:]  # HMAC key is the last 32 bytes of the derived key
+        cipherdata = encrypt_AES_CBC(cleardata, aes_key, iv)
+        expected_hmac = create_hmac(hmac_key, iv, cipherdata, authdata=authdata)
+        encrypted_bundle = create_encrypted_bundle(iv, salt, expected_hmac, cipherdata)
+    except Exception as e:
+        raise e
+    finally:
+        # Deleting from memory all critical data for security (in the order of their creation to avoid memory leaks)
+        if delete_keys:
+            delete_bytearray(cleardata)
+            delete_bytearray(password)
+            if authdata is not None:
+                delete_bytearray(authdata)
+        delete_bytearray(salt)
+        delete_bytearray(iv)
+        delete_bytearray(derived_key)
+        delete_bytearray(aes_key)
+        delete_bytearray(hmac_key)
+        delete_bytearray(cipherdata)
+        delete_bytearray(expected_hmac)
+
+    # Return the encrypted bundle
+    return encrypted_bundle

pyaescbc/create_encrypted_bundle.py

@@ -0,0 +1,70 @@
+# Copyright 2025 Artezaru
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+def create_encrypted_bundle(iv: bytearray, salt: bytearray, expected_hmac: bytearray, cipherdata: bytearray) -> bytearray:
+    """
+    Creates a bytearray containing all the information needed to decrypt the data.
+
+    The encrypted bundle is composed by the initialization vector (IV), the salt, the expected HMAC and the cipherdata.
+
+    .. seealso::
+
+        - function :func:`pyaescbc.extract_cryptography_components` to extract the components from the encrypted bundle.
+
+    Parameters
+    ----------
+    iv : bytearray
+        The 16-byte initialization vector used for encryption.
+
+    salt : bytearray
+        The 32-byte salt used to generate the derived key.
+
+    expected_hmac : bytearray
+        The 32-byte expected HMAC.
+
+    cipherdata : bytearray
+        The encrypted message.
+
+    Returns
+    -------
+    encrypted_bundle : bytearray
+        The concatenated bytearray containing `iv + salt + expected_hmac + cipherdata`.
+
+    Raises
+    ------
+    TypeError
+        If any argument is not a `bytearray` instance.
+    ValueError
+        If any of the components (salt, iv, hmac) are not the correct length.
+    """
+    # Check the types of the parameters
+    if not isinstance(iv, bytearray):
+        raise TypeError('Parameter iv is not bytearray instance.')
+    if not isinstance(salt, bytearray):
+        raise TypeError('Parameter salt is not bytearray instance.')
+    if not isinstance(expected_hmac, bytearray):
+        raise TypeError('Parameter expected_hmac is not bytearray instance.')
+    if not isinstance(cipherdata, bytearray):
+        raise TypeError('Parameter cipherdata is not bytearray instance.')
+    
+    # Check the values of the parameters
+    if len(iv) != 16:
+        raise ValueError(f'{iv=} is not 16 bytes long.') 
+    if len(salt) != 32:
+        raise ValueError(f'{salt=} is not 32 bytes long.') 
+    if len(expected_hmac) != 32:
+        raise ValueError(f'{expected_hmac=} is not 32 bytes long.')
+
+    # Create the encrypted bundle
+    return iv + salt + expected_hmac + cipherdata

pyaescbc/create_hmac.py

@@ -0,0 +1,81 @@
+# Copyright 2025 Artezaru
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import hmac
+import hashlib
+from typing import Optional
+
+def create_hmac(hmac_key: bytearray, iv: bytearray, cipherdata: bytearray, authdata: Optional[bytearray] = None) -> bytearray:
+    """
+    Creates the expected HMAC using the hmac_key on the iv, cipherdata, and optional auth_data.
+    The HMAC is created using the SHA-256 hash function. The HMAC is used to verify the integrity of the encrypted message.
+    The hmac_key is extracted from the derived key, which is created using PBKDF2HMAC.
+
+    .. code-block:: console
+
+        HMAC = HMAC(key, SHA256(iv + cipherdata + authdata))
+
+    .. seealso::
+
+        -function :func:`pyaescbc.derive_key` to create the derived key.
+
+    Parameters
+    ----------
+    hmac_key : bytearray
+        The 32-byte long key used to create the HMAC. It is extracted from the derived key.
+
+    iv : bytearray
+        The 16-byte long initialization vector used for encryption.
+
+    cipherdata : bytearray
+        The encrypted message.
+
+    authdata : Optional[bytearray]
+        Optional additional authentication data. If provided, it is prepended to the HMAC input.
+
+    Returns
+    -------
+    expected_hmac : bytearray
+        The 32-byte expected HMAC value.
+
+    Raises
+    ------
+    TypeError
+        If any argument is not a `bytearray` instance.
+
+    ValueError
+        If the hmac_key isn't 32 bytes, the IV isn't 16 bytes.
+    """
+    # Check the types of the parameters
+    if not isinstance(hmac_key, bytearray):
+        raise TypeError('Parameter hmac_key is not bytearray instance.')
+    if not isinstance(iv, bytearray):
+        raise TypeError('Parameter iv is not bytearray instance.')
+    if not isinstance(cipherdata, bytearray):
+        raise TypeError('Parameter cipherdata is not bytearray instance.')
+    if authdata is not None and not isinstance(authdata, bytearray):
+        raise TypeError('Parameter authdata is not bytearray instance.')
+    
+    # Check the value of the parameters
+    if len(hmac_key) != 32:
+        raise ValueError(f'{hmac_key=} is not 32 bytes long.') 
+    if len(iv) != 16:
+        raise ValueError(f'{iv=} is not 16 bytes long.')
+
+    # Create the HMAC
+    if authdata is None:
+        authdata = bytearray()
+    expected_hmac = bytearray(hmac.new(hmac_key, iv + cipherdata + authdata, hashlib.sha256).digest())
+
+    return expected_hmac

pyaescbc/decrypt_AES_CBC.py

@@ -0,0 +1,78 @@
+# Copyright 2025 Artezaru
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from cryptography.hazmat.primitives import padding, ciphers
+from cryptography.hazmat.backends import default_backend
+
+def decrypt_AES_CBC(cipherdata: bytearray, aes_key: bytearray, iv: bytearray) -> bytearray:
+    """
+    Decrypts a cipherdata message using AES in CBC mode.
+
+    The data is unpadded using PKCS7 padding and then decrypted using AES in CBC mode.
+    The aes_key is the first 32 bytes of the derived key, and the iv is the initialization vector.
+
+    .. seealso::
+
+        function :func:`pyaescbc.derive_key` to create the derived key.
+
+    .. note::
+
+        The cipherdata, aes_key and iv must be bytearrays.
+
+    Parameters
+    ----------
+    cipherdata : bytearray
+        The encrypted message to decrypt using AES in CBC mode.
+
+    aes_key : bytearray
+        The 32-byte AES key derived from the password, salt and iterations.
+
+    iv : bytearray
+        The 16-byte initialization vector (IV) to use in AES-CBC mode.
+
+    Returns
+    -------
+    cleardata : bytearray
+        The decrypted clear message.
+
+    Raises
+    ------
+    TypeError
+        If a given argument is not a `bytearray` instance.
+    ValueError
+        If the `aes_key` isn't 32 bytes long or the `iv` isn't 16 bytes long.
+    """
+    # Check the types of the parameters
+    if not isinstance(cipherdata, bytearray):
+        raise TypeError('Parameter cipherdata is not bytearray instance.')
+    if not isinstance(aes_key, bytearray):
+        raise TypeError('Parameter aes_key is not bytearray instance.')
+    if not isinstance(iv, bytearray):
+        raise TypeError('Parameter iv is not bytearray instance.')
+
+    # Check the values of the parameters
+    if len(aes_key) != 32:
+        raise ValueError(f'{aes_key=} is not 64 bytes long.') 
+    if len(iv) != 16:
+        raise ValueError(f'{iv=} is not 16 bytes long.')
+    
+    # Decrypt the data using AES in CBC mode
+    cipher = ciphers.Cipher(ciphers.algorithms.AES(aes_key), ciphers.modes.CBC(iv), backend=default_backend())
+    decryptor = cipher.decryptor()
+    unpadder = padding.PKCS7(128).unpadder()  
+    decrypted_data = decryptor.update(cipherdata) + decryptor.finalize() 
+    unpadded_data = bytearray(unpadder.update(decrypted_data) + unpadder.finalize())
+
+    # Returning the decrypted clear data
+    return unpadded_data

pyaescbc/delete_bytearray.py

@@ -0,0 +1,49 @@
+# Copyright 2025 Artezaru
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+
+def delete_bytearray(barray: bytearray) -> None:
+    r"""
+    Securely overwrites the contents of a bytearray and deletes the object from memory.
+
+    .. code-block:: python
+
+        import pyaescbc as aes
+        import os
+
+        # Create a bytearray
+        barray = bytearray(os.urandom(32))  # Example: 32 random bytes
+
+        # Securely delete the bytearray
+        aes.delete_bytearray(barray)
+
+    Parameters
+    ----------
+    barray : bytearray
+        The bytearray to securely delete from memory.
+
+    Raises
+    ------
+    TypeError
+        If the given argument is not a `bytearray` instance.
+    """
+    # Check if the input is a bytearray
+    if not isinstance(barray, bytearray):
+        raise TypeError('Parameter barray is not bytearray instance.')
+    
+    # Delete the bytearray by overwriting its contents with random data
+    for index in range(len(barray)):
+        barray[index] = os.urandom(1)[0]  # Overwrite with random data
+    barray.clear()  # Clear contents