# ahmed-ghadban/dilithium architecture

> Architecture diagram of the GitHub repository ahmed-ghadban/dilithium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmed-ghadban/dilithium
- Repository: https://github.com/ahmed-ghadban/dilithium

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["Dilithium-Signature.py"]:::ui
    end

    %% Cryptographic Core Modules
    subgraph "Cryptographic Core Modules"
        KG["Key Generation (key_gen.py)"]:::core
        S["Signing (sign.py)"]:::core
        V["Verification (verify.py)"]:::core
        D1["Primary Algorithm (dilithium.py)"]:::core
        D2["Alternative Algorithm (dili.py)"]:::core
    end

    %% Cryptographic Helper Modules
    subgraph "Cryptographic Helper Modules"
        DRBG["AES-256 CTR DRBG (aes256_ctr_drbg.py)"]:::helper
        NTT["NTT Helper (ntt_helper.py)"]:::helper
        Poly["Polynomial Math (polynomials.py)"]:::helper
        Shake["SHAKE Wrapper (shake_wrapper.py)"]:::helper
        Util["Utilities (utils.py)"]:::helper
        Mods["Modules (modules.py)"]:::helper
    end

    %% Testing & Benchmarking Modules
    subgraph "Testing & Benchmarking"
        Bench["Benchmarking (benchmark_dilithium.py)"]:::testing
        Test1["Test Module (test.py)"]:::testing
        Test2["Test Module (test_dilithium.py)"]:::testing
    end

    %% Assets and Test Vectors
    subgraph "Assets & Test Vectors"
        Assets["Assets (assets)"]:::assets
    end

    %% Connections: UI triggers core operations
    UI -->|"triggers"| KG
    UI -->|"triggers"| S
    UI -->|"triggers"| V

    %% Core Modules call the Primary Algorithm
    KG -->|"uses"| D1
    S -->|"uses"| D1
    V -->|"uses"| D1
    D1 -->|"alternatively_calls"| D2

    %% Primary Algorithm uses Cryptographic Helpers
    D1 -->|"calls"| DRBG
    D1 -->|"calls"| NTT
    D1 -->|"calls"| Poly
    D1 -->|"calls"| Shake
    D1 -->|"calls"| Util
    D1 -->|"calls"| Mods

    %% Testing & Benchmarking evaluate core operations
    Bench -->|"evaluates"| KG
    Bench -->|"evaluates"| S
    Bench -->|"evaluates"| V
    Test1 -->|"validates"| Assets
    Test2 -->|"validates"| Assets
    Test1 -->|"tests"| KG
    Test2 -->|"tests"| S
    Test2 -->|"tests"| V

    %% Click Events
    click UI "https://github.com/ahmed-ghadban/dilithium/blob/main/Dilithium-Signature.py"
    click KG "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/key_gen.py"
    click S "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/sign.py"
    click V "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/verify.py"
    click D1 "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/dilithium.py"
    click D2 "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/dili.py"
    click DRBG "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/aes256_ctr_drbg.py"
    click NTT "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/ntt_helper.py"
    click Poly "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/polynomials.py"
    click Shake "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/shake_wrapper.py"
    click Util "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/utils.py"
    click Mods "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/modules.py"
    click Bench "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/benchmark_dilithium.py"
    click Test1 "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/test.py"
    click Test2 "https://github.com/ahmed-ghadban/dilithium/blob/main/dilithium_py/test_dilithium.py"
    click Assets "https://github.com/ahmed-ghadban/dilithium/tree/main/dilithium_py/assets"

    %% Styles
    classDef ui fill:#ffcc00,stroke:#000,stroke-width:2px;
    classDef core fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef helper fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef testing fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef assets fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
