# smuellerdd/acvpparser architecture

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

- Interactive diagram: https://gitdiagram.com/smuellerdd/acvpparser
- Repository: https://github.com/smuellerdd/acvpparser

## Overview

##### Project type and purpose
- This is a standalone, data-driven, command-line JSON parser for the NIST ACVP (Automated Cryptographic Validation Program) protocol.
- It reads pre-downloaded ACVP test vector JSON files, invokes a chosen cryptographic backend to run the tests, and emits response JSON suitable for upload by a separate ACVP Proxy tool.

##### File structure
Top-level artifacts
- Makefile, backends.mk – orchestrate build and select the active backend (openssl, openssh, leancrypto, protobuf, linux_kernel, etc.).
- README*.md / LICENSE* / CHANGES.md / TODO – documentation and legal.
Three main code areas (layers):
A. Parser Core (folder “parser/”)
– JSON-C library (parser/json-c/) + parser.c + parser_*.c modules (each registers handlers for a specific ACVP test family).
– Implements data-driven parsing: definitions in parser_common.h drive interpretation of input JSON.
B. Protocol Output (“proto/”)
– proto.c, proto_*.c, proto_frontend_app_stdio.c – build the JSON response from the parser’s internal data structures.
C. Backends (folder “backends/” + “backend_interfaces/”)
– backends/backend_*.c – glue code to call each crypto implementation.
– backend_interfaces/ – companion code required for certain backends (e.g. Linux kernel module under kcapi_lrng, Protobuf interface code under protobuf/, OpenSSH interface under openssh/).
Helper scripts
- helper/exec_*.sh – batch and regression test runners.

##### README for additional insights
- Three-layer architecture is spelled out:
1. parser.c – registration and dispatching based on cipher identifier
2. parser_*.c – JSON parse logic, populating data structures, invoking backends
3. backend_*.c – calls into real crypto implementations (OpenSSL, Kernel, leanCrypto, etc.)
- Build instructions show how backends are selected via make targets.
- Backend-specific hints for kernel, Libreswan, Strongswan, OpenSSH confirm external dependencies.

- Annotations for dynamic registration points (constructor macros), and build-time backend selection (Makefile).

##### Detail checklist
- CLI entry point and how parser.c registers/dispatches parser modules.
- Actual backend_*.c implementations and external crypto engine or kernel interfaces.
- Helper scripts as an auxiliary component that drives repeated runs.
- Optionally, annotate build-time configuration (Makefile target selects a backend).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Components
    subgraph "CLI Frontend"
        CLI["acvp-parser\n(executable)"]:::cli
    end

    subgraph "Parser Core Layer"
        Core["Parser Core"]:::parser
    end

    subgraph "JSON Library"
        JSONC["JSON-C Library"]:::library
    end

    subgraph "Parser Plugins"
        Plugins["Parser Modules"]:::parser
    end

    subgraph "Protocol Output Layer"
        Proto["Protocol Output"]:::proto
    end

    subgraph "Backend Abstraction"
        Abstr["Backend Abstraction"]:::backend
    end

    subgraph "Backend Implementations"
        Impl["Backend Implementations"]:::backend
    end

    subgraph "Backend Interfaces"
        Interfaces["Backend Interface Companion Code"]:::backend
    end

    subgraph "External Crypto/Kernels"
        External["External Crypto / Kernel Integration"]:::external
    end

    subgraph "Build Orchestration"
        Build["Build Orchestration"]:::build
    end

    subgraph "Helper Scripts"
        Helper["Helper Scripts"]:::helper
    end

    %% Data flows
    CLI -->|"reads testvector JSON"| JSONC
    CLI -->|"invokes parser"| Core
    Core -->|"parses JSON"| JSONC
    Core -->|"dispatches based on cipher ID"| Plugins
    Plugins -->|"populate structs & call"| Abstr
    Abstr -->|"invoke crypto glue"| Impl
    Impl -->|"uses interface code"| Interfaces
    Interfaces -->|"calls external APIs"| External
    External -->|"crypto response"| Abstr
    Abstr -->|"return results"| Plugins
    Plugins -->|"pass data"| Proto
    Proto -->|"emit response JSON"| CLI

    %% Orchestration & scripts
    Build -->|"select backend & build"| CLI
    Build -->|"configure backends"| Impl
    Helper -->|"batch/regression invokes"| CLI

    %% Click Events
    click CLI "https://github.com/smuellerdd/acvpparser/blob/master/parser/parser.c"
    click CLI "https://github.com/smuellerdd/acvpparser/blob/master/proto/proto_frontend_app_stdio.c"
    click Core "https://github.com/smuellerdd/acvpparser/blob/master/parser/parser.c"
    click Core "https://github.com/smuellerdd/acvpparser/blob/master/parser/parser.h"
    click Core "https://github.com/smuellerdd/acvpparser/blob/master/parser/common.h"
    click Core "https://github.com/smuellerdd/acvpparser/blob/master/parser/parser_common.c"
    click Core "https://github.com/smuellerdd/acvpparser/blob/master/parser/parser_common.h"
    click Core "https://github.com/smuellerdd/acvpparser/blob/master/parser/read_json.c"
    click Core "https://github.com/smuellerdd/acvpparser/blob/master/parser/read_json.h"
    click JSONC "https://github.com/smuellerdd/acvpparser/tree/master/parser/json-c/"
    click Plugins "https://github.com/smuellerdd/acvpparser/blob/master/parser/parser_*.c"
    click Plugins "https://github.com/smuellerdd/acvpparser/blob/master/parser/parser_*.h"
    click Proto "https://github.com/smuellerdd/acvpparser/blob/master/proto/proto.c"
    click Proto "https://github.com/smuellerdd/acvpparser/blob/master/proto/proto.h"
    click Proto "https://github.com/smuellerdd/acvpparser/blob/master/proto/proto_*.c"
    click Abstr "https://github.com/smuellerdd/acvpparser/blob/master/backends/backend_common.h"
    click Impl "https://github.com/smuellerdd/acvpparser/blob/master/backends/backend_*.c"
    click Impl "https://github.com/smuellerdd/acvpparser/blob/master/backends/backend_*.h"
    click Interfaces "https://github.com/smuellerdd/acvpparser/tree/master/backend_interfaces/kcapi_lrng/"
    click Interfaces "https://github.com/smuellerdd/acvpparser/tree/master/backend_interfaces/leancrypto/"
    click Interfaces "https://github.com/smuellerdd/acvpparser/tree/master/backend_interfaces/openssh/"
    click Interfaces "https://github.com/smuellerdd/acvpparser/tree/master/backend_interfaces/protobuf/"
    click External "https://github.com/smuellerdd/acvpparser/tree/master/linux_kernel/"
    click Build "https://github.com/smuellerdd/acvpparser/tree/master/Makefile"
    click Build "https://github.com/smuellerdd/acvpparser/blob/master/backends.mk"
    click Helper "https://github.com/smuellerdd/acvpparser/tree/master/helper/"

    %% Styling
    classDef cli fill:#d0e1f9,stroke:#0366d6,color:#0366d6;
    classDef parser fill:#cfe2d4,stroke:#2e8b57,color:#2e8b57;
    classDef library fill:#f0ead6,stroke:#d4a373,color:#8b5e3c;
    classDef proto fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00;
    classDef backend fill:#d1ecf1,stroke:#20c997,color:#20c997;
    classDef external fill:#f8d7da,stroke:#dc3545,color:#dc3545;
    classDef build fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef helper fill:#f5f5f5,stroke:#adb5bd,color:#495057;
```
