# cisco/libacvp architecture

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

- Interactive diagram: https://gitdiagram.com/cisco/libacvp
- Repository: https://github.com/cisco/libacvp

## Overview

Based on our review of the file tree and README, this project is a cryptographic testing client library (libacvp) that implements the client-side of the ACVP protocol. It is not a full-blown full-stack web application but rather a C library (with an accompanying sample application, acvp_app) that validates cryptographic modules by interacting with an ACVP server. The overall design emphasizes modularity, layered cryptographic services, and flexible build configurations to support different platforms (UNIX, Windows, cross-compiles) and dependency choices (using Curl by default, with an experimental “murl” alternative).

##### Main Components
- ACVP Client Library (libacvp): The core component residing in the “src” directory (with its supporting header files in “include”). This layer handles processing of test vectors, invoking cryptographic routines (in files like acvp_aes.c, acvp_dsa.c, etc.), managing transport, and session handling.
- Sample Application (acvp_app) in the “app” directory: This component exemplifies how to integrate the library with a cryptographic module (DUT) and acts as the “glue” between the crypto backend (and OpenSSL/FIPS modules) and the ACVP protocol.
- Transport/Network Component: Either via libcurl (default) or the experimental murl module (in the “murl” directory). This layer is responsible for sending REST calls (over TLS) to the ACVP server.
- TLS and Cryptographic Dependencies: External libraries such as OpenSSL (and associated providers for FIPS or non-FIPS operations) and Curl. Represent that these dependencies are external but critical, with special notes on version support (OpenSSL ≥ 1.1.1 and recommendations to move to 3.X).
- JSON Parsing Layer: The project includes Parson (located in the “src” directory) to parse and generate JSON used in communicating with the ACVP server.
- Testing Framework: The “test” directory houses unit tests (using libcriterion) to validate library functionality and processing of test vectors.
- Supporting Infrastructure: Build and configuration tools such as autotools (configure.ac, Makefile.am/in, m4 scripts), Docker files (for containerized builds or tests), Visual Studio projects (in “ms”), and additional scripts (in “scripts”) to set up the environment and test sessions.

##### Relationships and Data Flow
- The sample application (acvp_app) calls into libacvp, which internally uses the JSON parser to format requests and parse responses.
- libacvp sends HTTP/HTTPS (using Curl or murl) calls to the remote ACVP server with the help of transport abstraction. This communication is secured by TLS—using certificates from the “certs” directory.
- Build and configuration components are “supporting” layers that feed into compilation and integration for multiple platforms.

##### Architectural Patterns and Design Principles
- Layered/Modular Architecture: Clearly separate the responsibilities between the library core (crypto routines, JSON processing, session management), the application layer (providing the runtime and “glue”), and external integrations (transport, TLS, and build configuration).
- Abstraction of Dependencies: Notice how the project offers alternatives for the transport layer (murl vs. curl) and has compile-time configuration switching for dependencies such as FIPS modules and different versions of OpenSSL. Illustrate these as interchangeable modules.
- Testability: The presence of an extensive “test” directory indicates a design that promotes unit testing; represent this as an external test harness that interacts with both the sample application and library core.

##### Additional Details to Emphasize
- Notes that the library supports many cryptographic and algorithm-specific test vectors (as reflected by the extensive JSON files in “test/json”) and that the vector processing flow is central to the library’s operation.
- Dual build targets (Linux/Unix autotools and Windows Visual Studio projects in “ms”) as parallel paths, which give insight into the cross-platform design considerations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Layer
    subgraph "Core Library"
        LIBACVP["ACVP Client Library (libacvp)"]:::core
        JSON["JSON Parsing (Parson)"]:::core
    end

    %% Application Layer
    subgraph "Application Layer"
        ACVP_APP["Sample Application (acvp_app)"]:::app
    end

    %% Transport Layer
    subgraph "Transport Layer"
        CURL["Transport: libcurl"]:::transport
        MURL["Transport: murl (Experimental)"]:::transport
        TLS["TLS & Certificates"]:::transport
    end

    %% External Services
    subgraph "External ACVP Server"
        SERVER["ACVP Server (External)"]:::external
    end

    %% Testing and Build Infrastructure
    subgraph "Testing & Build Infrastructure"
        TEST["Testing Framework (Unit Tests)"]:::test
        BUILD["Build & Configuration (autotools, m4)"]:::infra
        DOCKER["Container Builds (Docker)"]:::infra
        WINDOWS["Windows Projects (Visual Studio)"]:::infra
        SCRIPTS["Additional Scripts"]:::infra
    end

    %% Connections
    ACVP_APP -->|"calls"| LIBACVP
    LIBACVP -->|"processes_JSON"| JSON

    LIBACVP -->|"sendsReqs"| CURL
    LIBACVP -->|"sendsReqs"| MURL

    CURL -->|"securedBy"| TLS
    MURL -->|"securedBy"| TLS
    TLS -->|"connectsTo"| SERVER

    BUILD -->|"builds"| LIBACVP
    BUILD -->|"builds"| ACVP_APP

    DOCKER -->|"assistsBuild"| BUILD
    WINDOWS -->|"assistsBuild"| BUILD
    SCRIPTS -->|"assistsBuild"| BUILD

    TEST -->|"tests"| LIBACVP
    TEST -->|"tests"| ACVP_APP

    %% Click Events
    click LIBACVP "https://github.com/cisco/libacvp/tree/main/src"
    click JSON "https://github.com/cisco/libacvp/blob/main/src/parson.c"
    click ACVP_APP "https://github.com/cisco/libacvp/tree/main/app"
    click CURL "https://github.com/cisco/libacvp/blob/main/configure.ac"
    click MURL "https://github.com/cisco/libacvp/tree/main/murl"
    click TLS "https://github.com/cisco/libacvp/tree/main/certs"
    click TEST "https://github.com/cisco/libacvp/tree/main/test"
    click BUILD "https://github.com/cisco/libacvp/blob/main/configure.ac"
    click DOCKER "https://github.com/cisco/libacvp/tree/main/docker"
    click WINDOWS "https://github.com/cisco/libacvp/tree/main/ms"
    click SCRIPTS "https://github.com/cisco/libacvp/tree/main/scripts"

    %% Class Definitions
    classDef core fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef app fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef transport fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef external fill:#43aa8b,stroke:#333,stroke-width:2px;
    classDef infra fill:#577590,stroke:#333,stroke-width:2px;
    classDef test fill:#a2d2ff,stroke:#333,stroke-width:2px;
```
