# ekaragoz77/kyber-arm64 architecture

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

- Interactive diagram: https://gitdiagram.com/ekaragoz77/kyber-arm64
- Repository: https://github.com/ekaragoz77/kyber-arm64

## Overview

##### Project type and purpose
- This is a highly optimized C/ARM-assembly implementation of the Kyber post-quantum key-encapsulation mechanism (KEM), targeting 64-bit ARMv8 (AArch64) CPUs.
- It is a standalone cryptographic library plus test/benchmark harness, not a web app or full-stack system.
- Purpose: provide compact, high-performance Kyber primitives for ARM Cortex-A processors and measure their performance.

##### File structure
- Top-level files:
- AUTHORS, LICENSE, README.md – metadata
- armv8/ – all source code (C and ARM64 assembly), headers, tests, and Makefile
- howtobuild.md – build instructions
- Under armv8/:
- Assembly modules (*.S, *.inc) for core operations (NTT, reduction, multiplication)
- C modules for fallback or glue logic (e.g., fips202.c, randombytes.c, kem.c, kex.c)
- Headers (*.h) define the API, parameters, and internal interfaces
- Test programs (test_kex.c, test_kyber.c, test_speed.c, test_vectors.c)
- Makefile orchestrates cross-compilation and linking

##### README for additional insights
- Confirms this is an ARM64-optimized variant of an existing reference Kyber implementation.
- Benchmarking on real devices (Pixel 3, iPad) and comparing clock cycles.

##### Main components
a. Source modules (grouped by function):
- Parameter definitions & API layer (params.h, api.h, kem.h, kex.h)
- Core arithmetic & NTT pipeline
– Assembly files: ntt-arm.S, inv-ntt-arm.S, basemul-arm.S, reduce-arm.S, add-arm.S, poly_macros-arm.S, cbd-arm.S
– C fallbacks: ntt.c, poly.c, polyvec.c, cbd.c, reduce.h, poly.h, polyvec.h
- Symmetric primitives
– SHA-2 (sha256.c/sha512.c, fips202.c), AES-CTR (aes256ctr.c)
– DRBG / randombytes (rng.c, randombytes.c)
- KEM operations (kem.c, kex.c, indcpa.c, verify.c)
- Utilities & benchmarks (cpucycles.c, speed_print.c)
b. Build system
- armv8/Makefile invokes cross‐compiler, assembles .S files, links object files into executables and static library
- howtobuild.md details environment setup
c. Test/benchmark harness
- test_kex, test_kyber: correctness of key‐gen, encaps, decaps
- test_speed: measure cycle counts via cpucycles
- test_vectors: verify against known vectors

##### Relationships and interactions
- The Makefile takes all source modules → compiles C and assembles ARM64 code → produces:
- Static library libkyber-arm64.a
- Test executables
- At runtime, test programs call into the library’s API (keypair, encaps, decaps)
- Inside library, high-level API calls into symmetric primitives and core NTT/arithmetic modules
- Benchmark harness invokes cpucycles around individual primitive calls

##### Architectural patterns and design principles
- Modular layering:
- API layer (uniform interface)
- Primitive abstraction (symmetric vs arithmetic)
- Architecture‐specific hand-tuned assembly modules
- Separation of concerns:
- Correctness (reference C code) vs performance (ASM)
- Testing harness separated from library code
- Cross‐platform build: unified Makefile controls architecture‐specific flags

##### Technologies, frameworks, libraries
- Language: C99 + GNU assembler (ARM64 syntax)
- Build: GNU Make, gcc-aarch64 (cross-compiler)
- No external dependencies beyond standard C library and assembler

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    subgraph "Build System"
        Makefile["armv8/Makefile"]:::build
        Howto["howtobuild.md"]:::build
    end
    Makefile -->|invokes| API_Layer
    Makefile -->|invokes| Arithmetic
    Makefile -->|invokes| Symmetric
    Makefile -->|invokes| KEM_Ops
    Makefile -->|invokes| Utilities

    %% Library Artifact
    libArtifact["libkyber-arm64.a"]:::artifact
    API_Layer -->|compiled into| libArtifact
    Arithmetic -->|compiled into| libArtifact
    Symmetric -->|compiled into| libArtifact
    KEM_Ops -->|compiled into| libArtifact
    Utilities -->|compiled into| libArtifact

    %% API Layer
    subgraph "Parameter Definitions & API Layer"
        direction TB
        API_Layer["KEM API & Params"]:::lib
        API_H1["api.h"] 
        API_H2["params.h"]
        API_H3["kem.h"]
        API_H4["kex.h"]
        API_Layer --> API_H1
        API_Layer --> API_H2
        API_Layer --> API_H3
        API_Layer --> API_H4
    end

    %% Core Arithmetic & NTT
    subgraph "Core Arithmetic & NTT Pipeline"
        direction TB
        Arithmetic["Core Arithmetic & NTT"]:::lib
        ASM1["ntt-arm.S"]
        ASM2["inv-ntt-arm.S"]
        ASM3["basemul-arm.S"]
        ASM4["reduce-arm.S"]
        ASM5["add-arm.S"]
        ASM6["poly_macros-arm.S"]
        ASM7["cbd-arm.S"]
        C1["ntt.c"]
        C2["ntt.h"]
        C3["poly.c"]
        C4["poly.h"]
        C5["polyvec.c"]
        C6["polyvec.h"]
        C7["cbd.c"]
        C8["cbd.h"]
        C9["reduce.h"]
        Arithmetic --> ASM1
        Arithmetic --> ASM2
        Arithmetic --> ASM3
        Arithmetic --> ASM4
        Arithmetic --> ASM5
        Arithmetic --> ASM6
        Arithmetic --> ASM7
        Arithmetic --> C1
        Arithmetic --> C2
        Arithmetic --> C3
        Arithmetic --> C4
        Arithmetic --> C5
        Arithmetic --> C6
        Arithmetic --> C7
        Arithmetic --> C8
        Arithmetic --> C9
    end

    %% Symmetric Primitives
    subgraph "Symmetric Primitives"
        direction TB
        Symmetric["Symmetric Primitives"]:::lib
        S1["fips202.c"]
        S2["fips202.h"]
        S3["sha256.c"]
        S4["sha512.c"]
        S5["sha2.h"]
        S6["aes256ctr.c"]
        S7["aes256ctr.h"]
        S8["randombytes.c"]
        S9["randombytes.h"]
        S10["rng.c"]
        S11["rng.h"]
        S12["symmetric-aes.c"]
        S13["symmetric-shake.c"]
        S14["symmetric.h"]
        Symmetric --> S1
        Symmetric --> S2
        Symmetric --> S3
        Symmetric --> S4
        Symmetric --> S5
        Symmetric --> S6
        Symmetric --> S7
        Symmetric --> S8
        Symmetric --> S9
        Symmetric --> S10
        Symmetric --> S11
        Symmetric --> S12
        Symmetric --> S13
        Symmetric --> S14
    end

    %% KEM Operations
    subgraph "KEM Operations"
        direction TB
        KEM_Ops["KEM Operations"]:::lib
        K1["kem.c"]
        K2["indcpa.c"]
        K3["kex.c"]
        K4["verify.c"]
        K5["indcpa.h"]
        K6["kex.h"]
        K7["verify.h"]
        K8["PQCgenKAT_kem.c"]
        KEM_Ops --> K1
        KEM_Ops --> K2
        KEM_Ops --> K3
        KEM_Ops --> K4
        KEM_Ops --> K5
        KEM_Ops --> K6
        KEM_Ops --> K7
        KEM_Ops --> K8
    end

    %% Utilities & Benchmark Helpers
    subgraph "Utilities & Benchmark Helpers"
        direction TB
        Utilities["Utilities & Benchmark"]:::lib
        U1["cpucycles.c"]
        U2["cpucycles.h"]
        U3["speed_print.c"]
        U4["speed_print.h"]
        Utilities --> U1
        Utilities --> U2
        Utilities --> U3
        Utilities --> U4
    end

    %% Test & Benchmark Harness
    subgraph "Test & Benchmark Harness"
        direction TB
        T1["test_kex.c"]:::test
        T2["test_kyber.c"]:::test
        T3["test_speed.c"]:::test
        T4["test_vectors.c"]:::test
        T1 -->|calls| API_Layer
        T2 -->|calls| API_Layer
        T4 -->|calls| API_Layer
        T3 -->|measures| Utilities
        T1 --> libArtifact
        T2 --> libArtifact
        T3 --> libArtifact
        T4 --> libArtifact
    end

    %% Hardware
    Hardware["ARM Cortex-A (AArch64)"]:::hw
    libArtifact -->|runs on| Hardware
    T1 -->|executes on| Hardware
    T2 -->|executes on| Hardware
    T3 -->|executes on| Hardware
    T4 -->|executes on| Hardware

    %% Click Events
    click API_H1 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/api.h"
    click API_H2 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/params.h"
    click API_H3 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/kem.h"
    click API_H4 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/kex.h"
    click ASM1 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/ntt-arm.S"
    click ASM2 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/inv-ntt-arm.S"
    click ASM3 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/basemul-arm.S"
    click ASM4 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/reduce-arm.S"
    click ASM5 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/add-arm.S"
    click ASM6 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/poly_macros-arm.S"
    click ASM7 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/cbd-arm.S"
    click C1 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/ntt.c"
    click C2 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/ntt.h"
    click C3 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/poly.c"
    click C4 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/poly.h"
    click C5 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/polyvec.c"
    click C6 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/polyvec.h"
    click C7 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/cbd.c"
    click C8 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/cbd.h"
    click C9 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/reduce.h"
    click S1 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/fips202.c"
    click S2 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/fips202.h"
    click S3 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/sha256.c"
    click S4 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/sha512.c"
    click S5 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/sha2.h"
    click S6 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/aes256ctr.c"
    click S7 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/aes256ctr.h"
    click S8 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/randombytes.c"
    click S9 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/randombytes.h"
    click S10 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/rng.c"
    click S11 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/rng.h"
    click S12 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/symmetric-aes.c"
    click S13 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/symmetric-shake.c"
    click S14 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/symmetric.h"
    click K1 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/kem.c"
    click K2 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/indcpa.c"
    click K3 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/kex.c"
    click K4 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/verify.c"
    click K5 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/indcpa.h"
    click K6 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/kex.h"
    click K7 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/verify.h"
    click K8 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/PQCgenKAT_kem.c"
    click U1 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/cpucycles.c"
    click U2 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/cpucycles.h"
    click U3 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/speed_print.c"
    click U4 "https://github.com/ekaragoz77/kyber-arm64/blob/main/armv8/speed_print.h"
    click Makefile "https://github.com/ekaragoz77/kyber-arm64/tree/main/armv8/Makefile"
    click Howto "https://github.com/ekaragoz77/kyber-arm64/blob/main/howtobuild.md"

    %% Styles
    classDef build fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef lib fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef test fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef artifact fill:#FFFF00,stroke:#000,stroke-width:1px;
    classDef hw fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
