core-ciphers#

This project/library contains common elements related to ciphers…

Python Versions License Pipeline Status Docs Status Security

Documentation Contents#

Index:

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:

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:

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):

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:

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:

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:

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:

pip install core-ciphers
uv pip install core-ciphers  # Or using UV...

Setting Up Development Environment#

  1. Create and activate a virtual environment:

virtualenv --python=python3.12 .venv
source .venv/bin/activate

  1. Install with development dependencies:

pip install -e ".[dev]"

  1. Run tests and coverage:

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.

Support#

For questions or support, please open an issue on GitLab or contact the maintainers.

Authors#