# sandbox-quantum/pqc-fido2-impl architecture

> Architecture diagram of the GitHub repository sandbox-quantum/pqc-fido2-impl, 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/sandbox-quantum/pqc-fido2-impl
- Repository: https://github.com/sandbox-quantum/pqc-fido2-impl

## Overview

Based on our analysis of the file tree and README, this project is a specialized FIDO2 implementation that upgrades the existing protocol with post-quantum cryptographic algorithms. The project’s purpose is to demonstrate a full FIDO2 ecosystem—comprising an authenticator (hardware firmware and its companion software), a browser with integrated support, and a Java-based authentication server—enhanced with PQC capabilities (specifically, Dilithium3 and Kyber768).

##### Main Components
- Authenticator: This layer is twofold. It includes:
- The Rust-based implementation (found in the authenticator-rs directory) running on the device.
- The hardware firmware on Nitrokey 3 (contained within the nitrokey-3-firmware directory) and its related submodules (like trussed, fido-authenticator, ctap-types, usbd-ctaphid, and cosey).
- Browser: Illustrated as the Firefox browser, which has been modified (per the docs and instructions in docs/firefox.md) to work with the PQC authenticator.
- Server: Represented by the Java WebAuthn Server (in the java-webauthn-server directory), which makes use of additional dependencies (notably liboqs-java) for handling the post-quantum cryptography operations.
- Supporting Libraries & Tools: Include liboqs-java which acts as the Java wrapper for liboqs. This is built separately (as indicated in the README) and is critical to the cryptographic operations in the server.

- Hardware Link: Within the authenticator block, clearly illustrate the connection between the firmware (nitrokey-3-firmware) and its companion software layers (authenticator-rs and the supporting modules like trussed, cosey, etc.) that run on/with the Nitrokey 3 device.

##### Architectural Patterns and Design Principles
- Modular Architecture: Stress that each component (authenticator, browser, server) is developed and maintained as separate units. Emphasize the integration via well-defined protocols (WebAuthn, CTAP2).
- Extensibility: Note that the project forks several repositories, demonstrating a design that leverages modular, interchangeable components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Browser Layer"
        B["Firefox with PQC Authenticator Support"]:::web
        BDocs["(See docs/firefox.md & docs/firefox.diff)"]:::web
    end

    %% Server Layer
    subgraph "Server Layer"
        S["Java WebAuthn Server"]:::web
        C["liboqs-java (PQC Library)"]:::crypto
        S -->|"uses_crypto"| C
    end

    %% Authenticator Layer
    subgraph "Authenticator"
        R["authenticator-rs (Rust Implementation)"]:::firmware
        F["Nitrokey-3 Firmware & Modules"]:::firmware
        FN["(Includes: trussed, fido-authenticator, ctap-types, usbd-ctaphid, cosey)"]:::firmware
        F --> FN
    end

    %% Build Processes (Side Box)
    BP["Build Processes: Maven(liboqs-java), Gradle(Java Server), Make(Firmware)"]:::note

    %% Interactions
    B -->|"WebAuthn_Protocol"| S
    S -->|"CTAP2_Challenge"| R
    S -->|"CTAP2_Challenge"| F
    R -->|"CTAP2_Response"| S
    F -->|"CTAP2_Response"| S

    %% Build Dependencies linking
    BP --- S
    BP --- C
    BP --- F

    %% Click Events
    click R "https://github.com/sandbox-quantum/pqc-fido2-impl/tree/main/authenticator-rs"
    click F "https://github.com/sandbox-quantum/pqc-fido2-impl/tree/main/nitrokey-3-firmware"
    click B "https://github.com/sandbox-quantum/pqc-fido2-impl/blob/main/docs/firefox.md"
    click BDocs "https://github.com/sandbox-quantum/pqc-fido2-impl/blob/main/docs/firefox.diff"
    click S "https://github.com/sandbox-quantum/pqc-fido2-impl/tree/main/java-webauthn-server"
    click C "https://github.com/sandbox-quantum/pqc-fido2-impl/tree/main/liboqs-java"

    %% Styles
    classDef web fill:#88C0D0,stroke:#2E3440,stroke-width:2px;
    classDef crypto fill:#A3BE8C,stroke:#2E3440,stroke-width:2px;
    classDef firmware fill:#EBCB8B,stroke:#2E3440,stroke-width:2px;
    classDef note fill:#D8DEE9,stroke:#4C566A,stroke-width:1px,stroke-dasharray: 5, 5;
    classDef firmwareNote fill:#FFEBCB,stroke:#2E3440,stroke-width:1px,stroke-dasharray: 5, 5;
```
