How legrandin/pycryptodome works
Project Type and Purpose
• PyCryptodome is a self-contained, multilanguage crypto library (Python + C).
• It exposes low-level cryptographic primitives (cipher, hash, public key, protocol, RNG).
• Performance-critical algorithms are implemented in C or bundled C libraries (libtomcrypt); the rest is pure Python.
File Structure Analysis
• Top-level “lib/Crypto”: pure-Python package modules (Cipher, Hash, IO, Math, Protocol, PublicKey, Random, Signature, Util, SelfTest).
• Top-level “src”: C source files for block ciphers, hash functions, ECC, big-integer arithmetic, plus embedded libtomcrypt subtree.
• “test_vectors” and “lib/Crypto/SelfTest”: automated test suites.
• “Doc”: Sphinx documentation source.
• Build/config files: setup.py, pyproject.toml, setup.cfg, Makefile (in src), .github workflows.
Key Architecture Insights from README
• Python modules import either other Python modules or compiled C extensions.
• C code is compiled into one or more Python extension modules via setuptools.
• External dependency: optional GMP library for faster public-key ops.
• CI pipelines run unit tests, C tests, and integration tests.
Main Components
a. Python Layer
• Pure-Python packages under lib/Crypto (modules grouped by functionality).
• SelfTest framework invoking module tests.
b. Native Layer
• C extension modules (built from src/*.c).
• Embedded libtomcrypt (src/libtom).
c. Build & Packaging
• setup.py / pyproject.toml → compiler toolchain → .so/.pyd extension artifacts.
• pip installer.
d. Documentation
• Doc/ sources → Sphinx → HTML/PDF.
e. Testing
• Python SelfTest (lib/Crypto/SelfTest).
• C test harness (src/test).
• Test vectors (test_vectors).
f. CI/CD
• GitHub Actions workflows (.github/workflows/*).
Relationships and Data Flow
• Python modules “Crypto” import C extension methods for performance.
• C extensions link against embedded libtomcrypt and optionally GMP.
• Build step compiles C sources into dynamic libraries, then packaging bundles both Python and compiled artifacts.
• Tests drive both Python and C code through normalized API.
• Docs render API from Python code (autodoc) and include high-level design.
Architectural Patterns & Design Principles
• Layered modular architecture: Util & Math → cipher/hash primitives → protocol/public-key stacks → user-facing API.
• Extension pattern: fall back to pure Python if C extension absent (where feasible).
• Self-containment: embedded libtomcrypt provides cryptographic kernels rather than relying on OpenSSL.
• Test-driven: bundled test vectors validate cross-language correctness.
Technologies & Frameworks
• Python 2.7+ / 3.7+, setuptools, C compiler toolchain (GCC/Clang on Unix; MSVC on Windows), GMP (optional).
• Sphinx for documentation.
• GitHub Actions for CI.