How ahmed-ghadban/dilithium works
Main Components
• User Interface / Entry Point:
• Dilithium-Signature.py: Acts as the main entry point which likely initializes the application and interfaces with the user (or terminal) to trigger the signature operations.
• Core Cryptographic Modules:
• key_gen.py: Handles generation of cryptographic keys.
• sign.py and verify.py: Implement the core logic for digital signatures and their validation.
• dilithium.py (and possibly dili.py): Likely to contain the primary Dilithium algorithm implementation.
• modules.py: Could encapsulate helper routines or logically group several cryptographic or mathematical operations.
• Mathematical and Cryptographic Helpers:
• aes256_ctr_drbg.py: Provides deterministic random bit generation using AES-256 in CTR mode.
• ntt_helper.py and polynomials.py: These are likely used for Number Theoretic Transform (NTT) and polynomial arithmetic, which are common in lattice-based cryptography.
• shake_wrapper.py: Wraps around the SHAKE function, another cryptographic primitive vital in the Dilithium scheme.
• utils.py: Contains utility functions for common tasks.
• Testing and Benchmarking:
• benchmark_dilithium.py: Benchmarks and measures performance metrics (e.g., signing, key generation, and verification times).
• test.py and test_dilithium.py: Modules dedicated to unit testing or functional tests to ensure the implementations work as expected.
• Assets and Test Vectors:
• The assets folder includes response files (e.g., PQCsignKAT_Dilithium2.rsp) that serve as Known Answer Tests (KATs) for validating signature correctness.
Relationships and Data Flow
• The User Interface entry point (Dilithium-Signature.py) initiates the process.
• It orchestrates calls to the core cryptographic modules (key_gen.py, sign.py, verify.py) to generate keys, sign messages, and verify signatures.
• The dilithium.py (or dili.py) module likely integrates or coordinates various submodules performing the Dilithium algorithm steps.
• Mathematical helpers (ntt_helper.py, polynomials.py, and shake_wrapper.py) support the core algorithms by providing necessary operations and cryptographic primitives.
• The generated signatures and keys may be validated against reference test vectors located inside the assets folder.
• Benchmarking and testing modules run performance evaluations and correctness tests, providing metrics and validation feedback.
• Utility functions in utils.py and helper modules in modules.py are used across different parts of the system to maintain clean, reusable code.
Architectural Patterns and Design Principles
• Modular Design: The system is clearly segmented into discrete modules that each handle a specific aspect of the signature process (key generation, signing, verifying, and testing).
• Layered Abstraction: There is a separation of concerns between the user-facing script, the core cryptographic functionality, the mathematical operations, and the performance testing utilities.
• Test-Driven Approach: With dedicated test and benchmark modules, the project emphasizes correctness and performance evaluation.
• Maintainability: The use of utility modules and helpers indicates an architecture designed for maintainability and extensibility.
Technologies, Frameworks, and Libraries
• Python: The entire implementation is in Python, suitable for rapid development and portability on embedded systems like Raspberry Pi.
• Cryptographic Primitives: Built-in implementations of AES, SHAKE, and NTT represent custom or wrapped implementations for lattice-based cryptography.
• Hardware-Specific Considerations: The performance evaluation is tailored to Raspberry Pi hardware constraints (limited RAM, SSD usage).
Elements
• Main Entry Point (Dilithium-Signature.py)
• Core Modules:
• Key Generation (key_gen.py)
• Signing (sign.py)
• Verification (verify.py)
• Primary Algorithm (dilithium.py, dili.py)
• Cryptographic Helpers:
• AES-256 CTR DRBG (aes256_ctr_drbg.py)
• NTT and Polynomial Computation (ntt_helper.py, polynomials.py)
• SHAKE Function (shake_wrapper.py)
• Utility functions (utils.py, modules.py)
• Testing and Benchmarking:
• Benchmark module (benchmark_dilithium.py)
• Test modules (test.py, test_dilithium.py)
• Assets for Test Vectors (inside the assets directory)
• Data Flow: