# secworks/aes architecture

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

- Interactive diagram: https://gitdiagram.com/secworks/aes
- Repository: https://github.com/secworks/aes

## Overview

##### Project type and purpose
- This is an open-source hardware IP core implementing the AES symmetric block cipher (FIPS-197) in Verilog.
- It provides a reusable “aes” core that can be integrated into ASIC or FPGA designs, supports key expansion (128/256-bit), separate encipher/decipher datapaths, and is built/tested via FuseSoC and OpenLane/sky130 flows.

##### File structure
- Top-level files: LICENSE, README.md, .github/ci.yml for CI.
- src/model/python: reference Python implementation of AES for functional verification.
- src/rtl: Verilog sources:
- aes.v – top-level wrapper (register interface, control/status, key & data ports)
- aes_core.v – core FSM, control logic
- aes_encipher_block.v, aes_decipher_block.v – datapaths
- aes_key_mem.v – round-key storage
- aes_key_gen.v (key expansion)
- src/tb: individual block and full-core testbenches.
- data/sky130.tcl + toolruns/Makefile: ASIC build scripts for SKY130 PDK with OpenLane.

##### README for insights
- Shows supported variants (on-the-fly keygen, dual-keys, CMT-SBOX).
- FuseSoC integration for simulation/linting.

##### Elements
- Clear component labels (e.g., “Control FSM”, “Key Mem”, “Encipher Block”)
- Key_in → Control FSM → Key Gen → Key Mem → Encipher/Decipher
- Data_in → Encipher/Decipher → Data_out
- Blue blocks = control logic
- Green blocks = datapaths
- Orange blocks = memory
- Gray blocks = external interfaces or test models
- Interface signals at block boundaries with widths (e.g., [127:0])

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    subgraph "External Interfaces" 
        direction TB
        KeyIn["Key_in[127:0], Key_len"]:::external
        DataIn["Data_in[127:0], Control_in"]:::external
        DataOut["Data_out[127:0], Status_out"]:::external
    end

    %% AES Core Wrapper
    subgraph "AES Core" 
        direction TB
        Wrapper["AES Wrapper (Register-Interface)"]:::control
        FSM["Control FSM & Config/Status"]:::control
        subgraph "Key Expansion & Memory"
            direction TB
            KeyGen["Key Expansion Engine"]:::control
            KeyMem["Round-Key Memory"]:::memory
        end
        subgraph "Datapaths"
            direction TB
            EncBlock["Encipher Datapath"]:::datapath
            DecBlock["Decipher Datapath"]:::datapath
        end
        subgraph "Shared S-Boxes"
            direction TB
            Sbox["S-Box Lookup"]:::datapath
            InvSbox["Inverse S-Box Lookup"]:::datapath
        end
    end

    %% Verification & Reference Models
    subgraph "Verification & Reference" 
        direction TB
        PyAES["Python Golden-Reference AES Model"]:::external
        PyKeyGen["Python Rcon & KeyGen Model"]:::external
        TBFull["Full-Core Testbench"]:::external
        TBCore["Core FSM Testbench"]:::external
        TBEnc["Encipher Block Testbench"]:::external
        TBDec["Decipher Block Testbench"]:::external
        TBMem["Key Memory Testbench"]:::external
    end

    %% Build Flow
    subgraph "Build & CI Flow" 
        direction TB
        FuseSoC["FuseSoC Core File"]:::external
        CI["Continuous Integration Workflow"]:::external
        ASICScript["ASIC Build Script (OpenLane/SKY130)"]:::external
        ASICMake["ASIC Toolrun Makefile"]:::external
    end

    %% Connections
    KeyIn -->|writes| Wrapper
    DataIn --> Wrapper
    Wrapper -->|control| FSM
    FSM -->|start key gen| KeyGen
    KeyGen -->|write round-keys| KeyMem
    FSM -->|fetch round-key| KeyMem
    KeyMem -->|round-key| EncBlock
    KeyMem -->|round-key| DecBlock
    EncBlock -->|uses S-Box| Sbox
    DecBlock -->|uses Inv S-Box| InvSbox
    FSM -->|process data| EncBlock
    FSM -->|process data| DecBlock
    EncBlock --> DataOut
    DecBlock --> DataOut

    PyAES -->|compare results| FSM
    PyKeyGen -->|model keygen| KeyGen
    TBFull --> Wrapper
    TBCore --> FSM
    TBEnc --> EncBlock
    TBDec --> DecBlock
    TBMem --> KeyMem

    Wrapper --> FuseSoC
    FuseSoC --> CI
    CI --> ASICScript
    ASICScript --> ASICMake

    %% Click Events
    click Wrapper "https://github.com/secworks/aes/blob/master/src/rtl/aes.v"
    click FSM "https://github.com/secworks/aes/blob/master/src/rtl/aes_core.v"
    click KeyGen "https://github.com/secworks/aes/blob/master/src/model/python/aes_key_gen.py"
    click KeyMem "https://github.com/secworks/aes/blob/master/src/rtl/aes_key_mem.v"
    click EncBlock "https://github.com/secworks/aes/blob/master/src/rtl/aes_encipher_block.v"
    click DecBlock "https://github.com/secworks/aes/blob/master/src/rtl/aes_decipher_block.v"
    click Sbox "https://github.com/secworks/aes/blob/master/src/rtl/aes_sbox.v"
    click InvSbox "https://github.com/secworks/aes/blob/master/src/rtl/aes_inv_sbox.v"
    click PyAES "https://github.com/secworks/aes/blob/master/src/model/python/aes.py"
    click PyKeyGen "https://github.com/secworks/aes/blob/master/src/model/python/rcon.py"
    click TBFull "https://github.com/secworks/aes/blob/master/src/tb/tb_aes.v"
    click TBCore "https://github.com/secworks/aes/blob/master/src/tb/tb_aes_core.v"
    click TBEnc "https://github.com/secworks/aes/blob/master/src/tb/tb_aes_encipher_block.v"
    click TBDec "https://github.com/secworks/aes/blob/master/src/tb/tb_aes_decipher_block.v"
    click TBMem "https://github.com/secworks/aes/blob/master/src/tb/tb_aes_key_mem.v"
    click FuseSoC "https://github.com/secworks/aes/blob/master/aes.core"
    click CI "https://github.com/secworks/aes/blob/master/.github/workflows/ci.yml"
    click ASICScript "https://github.com/secworks/aes/blob/master/data/sky130.tcl"
    click ASICMake "https://github.com/secworks/aes/tree/master/toolruns/Makefile"

    %% Styles
    classDef control fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef datapath fill:#A9DFBF,stroke:#27AE60,color:#145A32
    classDef memory fill:#F9E79F,stroke:#B9770E,color:#7D6608
    classDef external fill:#D5D8DC,stroke:#566573,color:#1B2631
```
