core-ciphers

This project/library contains common elements related to 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.

Installation

Install from PyPI using pip:

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

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

pip install core-ciphers
uv pip install core-ciphers  # Or using UV...
pip install -e ".[dev]"    # For development...

pip install --upgrade pip
pip install virtualenv

virtualenv --python=python3.12 .venv

source .venv/bin/activate

pip install .
pip install -e ".[dev]"

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