.. core-ciphers documentation master file, created by sphinx-quickstart on Mon Mar 31 15:52:47 2025. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. core-ciphers =============================================================================== This project/library contains common elements related to ciphers... =============================================================================== .. image:: https://img.shields.io/pypi/pyversions/core-ciphers.svg :target: https://pypi.org/project/core-ciphers/ :alt: Python Versions .. image:: https://img.shields.io/badge/license-MIT-blue.svg :target: https://gitlab.com/bytecode-solutions/core/core-ciphers/-/blob/main/LICENSE :alt: License .. image:: https://gitlab.com/bytecode-solutions/core/core-ciphers/badges/release/pipeline.svg :target: https://gitlab.com/bytecode-solutions/core/core-ciphers/-/pipelines :alt: Pipeline Status .. image:: https://readthedocs.org/projects/core-ciphers/badge/?version=latest :target: https://readthedocs.org/projects/core-ciphers/ :alt: Docs Status .. image:: https://img.shields.io/badge/security-bandit-yellow.svg :target: https://github.com/PyCQA/bandit :alt: Security Documentation Contents ------------------------------------------------------------------------------- .. toctree:: :maxdepth: 1 :caption: Index: encryption_guide ciphers Security - Cryptographic Library ------------------------------------------------------------------------------- This project uses **``pycryptodome``** (version >=3.21.0) for cryptographic operations, not the deprecated ``pycrypto`` library. **Important Note:** Security scanners like ``bandit`` may report false positives (B413 warnings) when scanning this codebase. This occurs because both ``pycrypto`` (deprecated) and ``pycryptodome`` (actively maintained) use the same ``Crypto`` import namespace, causing scanners to incorrectly flag the imports as deprecated. **Verification:** - Check ``pyproject.toml`` dependencies: ``pycryptodome>=3.21.0``. - ``pycryptodome`` is actively maintained and regularly updated. - It is the recommended drop-in replacement for the deprecated ``pycrypto``. The B413 bandit warnings can be safely ignored as they are false positives. Features ------------------------------------------------------------------------------- **Core Components:** * **ICipher Interface** - Abstract base class for implementing custom cipher algorithms. * **AESCipher** - Advanced Encryption Standard (AES) implementation with multiple cipher modes. **AES Cipher Capabilities:** * **Key Sizes:** Support for 128, 192, and 256-bit encryption keys (MODE_SIV requires a double-length key: 32, 48, or 64 bytes) * **Authenticated Encryption Modes:** - MODE_GCM (Galois/Counter Mode) - Default, recommended for most use cases - MODE_EAX (EAX Mode) - MODE_CCM (Counter with CBC-MAC) - MODE_SIV (Synthetic Initialization Vector) - MODE_OCB (Offset Codebook Mode) * **Block Cipher Modes:** - MODE_ECB (Electronic Code Book) - MODE_CBC (Cipher Block Chaining) * **Stream Cipher Modes:** - MODE_CFB (Cipher Feedback) - MODE_OFB (Output Feedback) - MODE_CTR (Counter Mode) **Additional Features:** * Automatic key generation if not provided. * Automatic padding for modes that require it (ECB, CBC). * Authentication tag generation and verification for authenticated modes. * Configurable character encoding (default: UTF-8). * Hex-encoded output for easy serialization. * Built on **pycryptodome** for secure, actively maintained cryptographic operations. Quick Start ------------------------------------------------------------------------------- **Default mode (GCM), auto-generated key:** .. code-block:: python from core_ciphers.aes_cipher import AESCipher cipher = AESCipher() encrypted = cipher.encrypt("Hello, World!") # {'ciphertext': '...', 'tag': '...', 'nonce': '...'} plaintext = cipher.decrypt(encrypted) # 'Hello, World!' **Explicit key and mode:** .. code-block:: python from Crypto.Cipher import AES from Crypto.Random import get_random_bytes from core_ciphers.aes_cipher import AESCipher key = get_random_bytes(16) # 128-bit key cipher = AESCipher(key=key, mode=AES.MODE_CBC) encrypted = cipher.encrypt("Hello, World!") # {'ciphertext': '...', 'iv': '...'} plaintext = cipher.decrypt(encrypted) # 'Hello, World!' **Cross-instance decryption (share the key):** .. code-block:: python from Crypto.Random import get_random_bytes from core_ciphers.aes_cipher import AESCipher key = get_random_bytes(16) encryptor = AESCipher(key=key) decryptor = AESCipher(key=key) encrypted = encryptor.encrypt("Hello, World!") plaintext = decryptor.decrypt(encrypted) # 'Hello, World!' **SIV mode, requires a 32-byte (or larger) key:** .. code-block:: python from Crypto.Cipher import AES from core_ciphers.aes_cipher import AESCipher cipher = AESCipher(mode=AES.MODE_SIV) # auto-generates a 32-byte key encrypted = cipher.encrypt("Hello, World!") # {'ciphertext': '...', 'tag': '...'} plaintext = cipher.decrypt(encrypted) # 'Hello, World!' **Tamper detection, authenticated modes raise on modified data:** .. code-block:: python from core_ciphers.aes_cipher import AESCipher cipher = AESCipher() # GCM by default encrypted = cipher.encrypt("Hello, World!") # Simulate an attacker flipping a byte in the ciphertext ct = bytearray(bytes.fromhex(encrypted["ciphertext"])) ct[0] ^= 0xFF encrypted["ciphertext"] = ct.hex() try: cipher.decrypt(encrypted) except ValueError: print("Tampered data detected, decryption aborted.") **Stream cipher mode (CTR), no padding, no authentication tag:** .. code-block:: python from Crypto.Cipher import AES from Crypto.Random import get_random_bytes from core_ciphers.aes_cipher import AESCipher key = get_random_bytes(16) cipher = AESCipher(key=key, mode=AES.MODE_CTR) encrypted = cipher.encrypt("Hello, World!") # {'ciphertext': '...', 'nonce': '...'} decryptor = AESCipher(key=key, mode=AES.MODE_CTR) plaintext = decryptor.decrypt(encrypted) # 'Hello, World!' Installation ------------------------------------------------------------------------------- Install from PyPI: .. code-block:: bash pip install core-ciphers uv pip install core-ciphers # Or using UV... Setting Up Development Environment ------------------------------------------------------------------------------- 1. Create and activate a virtual environment: .. code-block:: bash virtualenv --python=python3.12 .venv source .venv/bin/activate 2. Install with development dependencies: .. code-block:: bash pip install -e ".[dev]" 3. Run tests and coverage: .. code-block:: bash python manager.py run-tests python manager.py run-coverage Contributing ------------------------------------------------------------------------------- Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Write tests for new functionality 4. Ensure all tests pass: ``python -m unittest discover -s tests -p "tests_*.py"`` 5. Run linting: ``pylint core_ciphers`` 6. Run security checks: ``bandit -r core_ciphers`` 7. Submit a pull request License ------------------------------------------------------------------------------- This project is licensed under the MIT License. See the LICENSE file for details. Links ------------------------------------------------------------------------------- * **Documentation:** https://core-ciphers.readthedocs.io/en/latest/ * **Repository:** https://gitlab.com/bytecode-solutions/core/core-ciphers * **Issues:** https://gitlab.com/bytecode-solutions/core/core-ciphers/-/issues * **Changelog:** https://gitlab.com/bytecode-solutions/core/core-ciphers/-/blob/master/CHANGELOG.md * **PyPI:** https://pypi.org/project/core-ciphers/ Support ------------------------------------------------------------------------------- For questions or support, please open an issue on GitLab or contact the maintainers. Authors ------------------------------------------------------------------------------- * **Alejandro Cora González** - *Initial work* - alek.cora.glez@gmail.com