# open-quantum-safe/oqs-provider architecture

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

- Interactive diagram: https://gitdiagram.com/open-quantum-safe/oqs-provider
- Repository: https://github.com/open-quantum-safe/oqs-provider

## Overview

##### Main Components
- Provider Core:
- Core implementation found in the “oqsprov” folder. This is where the provider shared library is implemented. Note the key source files (e.g., oqsprov.c, oqsprov_capabilities.c) that implement the OpenSSL provider interface.
- “oqs-template” directory which appears to be used as a basis for generating provider or algorithm-specific code. It contains scripts (Python and shell) to generate algorithm tables and configuration fragments.
- OpenSSL Integration:
- How the provider is loaded by OpenSSL’s provider interface. Indicate that OpenSSL communicates with the provider to expose the available quantum-safe algorithms.
- Mention the dependency on OpenSSL 3.x and its evolving provider model that allows external providers to be dynamically registered.
- Underlying Cryptography (liboqs):
- A component representing liboqs, which supplies the underlying quantum-safe cryptographic algorithms. The provider depends on liboqs at build time to determine which algorithms to expose.
- Build & Configuration Infrastructure:
- CMake build system (with CMakeLists.txt at the top level as well as in “oqsprov”), which is used to build and install the provider.
- Configuration and pre-build scripts (e.g., CONFIGURE.md instructions) as well as CI/CD configurations from “.circleci”, “.github/workflows”, and build/testing scripts from the “scripts” folder.
- Testing & Examples:
- “examples” folder as representing sample usage of the provider.

##### Relationships and Data Flow
- Provider with liboqs, showing that the provider translates calls from OpenSSL into calls to liboqs (or uses liboqs internals when available).
- Build system as an external process that compiles the provider and links it against both OpenSSL and liboqs.
- CI/CD pipelines (from GitHub Actions and CircleCI) that trigger builds, format checks, tests, and release steps—pointing toward the build system and test suite.

##### Architectural Patterns and Design Principles
- Provider/Plugin Pattern:
- That the design follows the OpenSSL provider model, so mark the provider component as a plugin that adheres to the dynamically loadable “provider” pattern.
- Modular Code Generation and Configuration:
- That the “oqs-template” scripts and fragments are used to dynamically generate parts of the provider based on enabled algorithms. This reflects a modular, data-driven approach.
- Continuous Integration/Continuous Delivery (CI/CD):
- Robust CI/CD pipeline setup through various configuration files (e.g., circleci/config.yml, GitHub workflows) ensuring code quality, cross-platform builds, and tests.

##### Technologies, Frameworks, and Tools
- CMake for build configuration and compilation.
- The OpenSSL provider API (and dynamic loading) as the integration point.
- liboqs as the dependency providing quantum-safe cryptographic routines.
- Shell scripts, Python scripts, and CI configurations to automate testing, formatting, and releases.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Dependencies
    subgraph "External Dependencies"
        OpenSSL["OpenSSL 3.x (Provider Consumer)"]:::external
        liboqs["liboqs (Quantum-Safe Algorithms)"]:::external
    end

    %% Core Provider Implementation
    subgraph "Core Provider Implementation"
        ProviderCore["oqsprovider (Provider Core)"]:::provider
        OpenSSLInt["OpenSSL Integration (oqsprov/oqsprov.c)"]:::provider
        CodeGen["oqs-template (Code Generation & Templates)"]:::provider
    end

    %% Support Infrastructure
    subgraph "Support Infrastructure"
        BuildTop["CMakeLists.txt (root)"]:::build
        BuildOqsprov["oqsprov/CMakeLists.txt"]:::build
        Configure["CONFIGURE.md (Configuration)"]:::build
        CMakeDir[".CMake (Toolchain Configs)"]:::build
        BuildScripts["scripts (Build Scripts)"]:::build
        CI_Circle[".circleci (CircleCI Config)"]:::ci
        CI_GitHub[".github/workflows (GitHub Actions)"]:::ci
    end

    %% Testing & Examples
    subgraph "Testing & Examples"
        Testing["test (Test Cases)"]:::test
        Examples["examples (Usage Examples)"]:::test
    end

    %% Relationships and Data Flow

    %% Runtime integration: OpenSSL loads provider using the integration interface
    OpenSSL -->|"loads"| OpenSSLInt
    OpenSSLInt -->|"implements"| ProviderCore

    %% Provider Core communicates with liboqs for algorithms
    ProviderCore -->|"delegates"| liboqs

    %% Code Generation support for provider core
    CodeGen -->|"generates code for"| ProviderCore

    %% Build system compiles and configures provider
    BuildTop -->|"builds"| ProviderCore
    BuildOqsprov -->|"builds"| ProviderCore
    Configure -->|"configures"| ProviderCore
    CMakeDir -->|"configures"| ProviderCore
    BuildScripts -->|"executes build steps for"| ProviderCore
    BuildScripts -->|"executes build steps for"| CodeGen

    %% CI/CD pipelines trigger build and tests
    CI_Circle -->|"triggers build"| BuildTop
    CI_GitHub -->|"triggers build"| BuildTop
    CI_Circle -->|"triggers test"| Testing
    CI_GitHub -->|"triggers test"| Testing

    %% Testing and Examples validate the provider functionality
    Testing -->|"validates"| ProviderCore
    Examples -->|"demonstrates usage of"| ProviderCore

    %% Click Events
    click ProviderCore "https://github.com/open-quantum-safe/oqs-provider/tree/main/oqsprov"
    click OpenSSLInt "https://github.com/open-quantum-safe/oqs-provider/blob/main/oqsprov/oqsprov.c"
    click CodeGen "https://github.com/open-quantum-safe/oqs-provider/tree/main/oqs-template"
    click BuildTop "https://github.com/open-quantum-safe/oqs-provider/blob/main/CMakeLists.txt"
    click BuildOqsprov "https://github.com/open-quantum-safe/oqs-provider/blob/main/oqsprov/CMakeLists.txt"
    click Configure "https://github.com/open-quantum-safe/oqs-provider/blob/main/CONFIGURE.md"
    click CMakeDir "https://github.com/open-quantum-safe/oqs-provider/blob/main/.CMake"
    click BuildScripts "https://github.com/open-quantum-safe/oqs-provider/tree/main/scripts"
    click CI_Circle "https://github.com/open-quantum-safe/oqs-provider/blob/main/.circleci"
    click CI_GitHub "https://github.com/open-quantum-safe/oqs-provider/tree/main/.github/workflows"
    click Testing "https://github.com/open-quantum-safe/oqs-provider/tree/main/test"
    click Examples "https://github.com/open-quantum-safe/oqs-provider/tree/main/examples"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px,color:#000;
    classDef provider fill:#F8C471,stroke:#333,stroke-width:2px,color:#000;
    classDef build fill:#82E0AA,stroke:#333,stroke-width:2px,color:#000;
    classDef ci fill:#AED6F1,stroke:#333,stroke-width:2px,color:#000;
    classDef test fill:#F1948A,stroke:#333,stroke-width:2px,color:#000;
```
