# stefanberger/swtpm architecture

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

- Interactive diagram: https://gitdiagram.com/stefanberger/swtpm
- Repository: https://github.com/stefanberger/swtpm

## Overview

##### Main components
- Core TPM Emulator Engine: Represented by the contents in src/swtpm. This is the heart of the emulator that implements the TPM functionalities.
- Interface Modules: Include components in src/swtpm_io, src/swtpm_bios, src/swtpm_ioctl, and src/swtpm_localca. These modules handle different methods of delivering TPM services (e.g., CUSE for device files, socket interfaces, or BIOS emulation).
- TPM Tools and Utilities: The various tool directories (src/swtpm_cert, src/swtpm_setup, and scripts in samples/) are responsible for creating certificates, simulating TPM manufacturing, and configuring the emulator.
- Configuration and Build System: The autogen.sh, configure.ac, Makefile.am files and the include directories indicate how the project is built and configured.
- Testing Framework: The tests directory contains extensive tests and sample states that validate various TPM operations.
- Deployment/CI Infrastructure: The .github workflows, Dockerfile, docker-compose.yml, and CI-related configurations show how the project is integrated into a CI/CD pipeline.
- External dependencies: Although not directly visible in a dedicated dependency file, documentation and build scripts hint at integration with libtpms and possibly OpenSSL for cryptographic needs.

##### Relationships and interactions
- The Core TPM Emulator Engine interacts directly with the underlying libtpms library and also serves as the backend for various front-end interfaces.
- Different interface modules (e.g., syscall interfaces, CUSE, socket-based interfaces) receive incoming communication (from applications expecting a real TPM) and translate them to core TPM engine commands.
- The TPM tools (certificate creation, TPM setup/management utilities) interface with the core engine to generate TPM state, Extended Keys (EKs), and other related artifacts.
- The build, configuration, and CI components orchestrate the build process and continuous testing/deployment workflows.
- The tests exercise all these interactions by simulating various TPM operations and states.

##### Architectural patterns and design principles
- Modularization: Each folder (for example, swtpm, swtpm_localca, swtpm_setup) represents a distinct module encapsulating specific functionality.
- Separation of concerns: The architecture separates the TPM emulation core from the multiple interface mechanisms, and from the administrative tooling.
- Extensibility: The use of Makefile.am, autogen.sh, and configuration files suggests that the project is designed to be built and extended on various systems, ensuring compatibility with different deployment scenarios (e.g., Linux distributions, CI systems).

- Main Node: TPM Emulator (the core engine from src/swtpm).
- Tooling Nodes: Group nodes for certificate generation (swtpm_cert), local certification authority (swtpm_localca), TPM setup tools (swtpm_setup), and utility components.
- Auxiliary components: CI/CD pipeline (GitHub Actions, Travis CI, Docker configurations) and testing frameworks from tests/.
- Data/Configuration Flow: If appropriate, show how configuration files (like swtpm_setup.conf, swtpm_localca.conf) and persistent state (TPM state files under tests/data) are used to bootstrap or restore TPM sessions.
- External Dependencies: Represent libtpms and any cryptographic libraries (e.g., OpenSSL) that interact with the emulator.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Core Components
    subgraph "Core Components"
        tpmi("TPM Emulator Core"):::core
    end

    %% Interface Modules
    subgraph "Interface Modules"
        sock("TCP/Unix Socket Interface"):::interface
        cuse("CUSE Interface Module"):::interface
        bios("BIOS Emulation Interface"):::interface
        ioctl("IOCTL Interface Module"):::interface
    end

    %% Tools and Utilities
    subgraph "Tools and Utilities"
        localca("Local Certification Authority Module"):::tool
        certificate("Certificate Tool"):::tool
        setup("TPM Setup/Manufacturing Simulation Tool"):::tool
    end

    %% Infrastructure & Build
    subgraph "Infrastructure & Build"
        config("Configuration & Build System"):::infra
        tests("Testing Framework"):::infra
        ci("Deployment/CI Infrastructure"):::infra
        
        %% Build Configuration Files (vertical grouping)
        a("autogen.sh"):::configfile
        conf("configure.ac"):::configfile
        mf("Makefile.am"):::configfile
        imf("include/Makefile.am"):::configfile
        config --> a
        config --> conf
        config --> mf
        config --> imf
        
        %% CI/CD Files
        gh(".github"):::ciIcon
        df("Dockerfile"):::ciIcon
        dcy("docker-compose.yml"):::ciIcon
        ci --> gh
        ci --> df
        ci --> dcy
    end

    %% External Dependencies
    subgraph "External Dependencies"
        lib("libtpms"):::external
        openssl("OpenSSL"):::external
    end

    %% Connections between Interface Modules and Core
    sock -->|"receives_requests"| tpmi
    cuse -->|"receives_requests"| tpmi
    bios -->|"receives_requests"| tpmi
    ioctl -->|"receives_requests"| tpmi

    %% Tools interacting with Core
    localca ---|"configures"| tpmi
    certificate ---|"generates_certificates_for"| tpmi
    setup ---|"simulates_manufacturing_for"| tpmi

    %% Infrastructure interactions with Core
    config ---|"builds/configures"| tpmi
    tests ---|"validates"| tpmi
    ci ---|"deploys/monitors"| tpmi

    %% External dependencies used by Core
    tpmi ---|"utilizes"| lib
    tpmi ---|"utilizes"| openssl

    %% Class Definitions
    classDef core fill:#ffcccc,stroke:#000,stroke-width:2px;
    classDef interface fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef tool fill:#ccccff,stroke:#000,stroke-width:2px;
    classDef infra fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef external fill:#ffccff,stroke:#000,stroke-width:2px;
    classDef configfile fill:#e0e0e0,stroke:#000,stroke-dasharray: 5 5;
    classDef ciIcon fill:#d0e0ff,stroke:#000,stroke-dasharray: 3 3;

    %% Click Events
    click tpmi "https://github.com/stefanberger/swtpm/tree/master/src/swtpm"
    click sock "https://github.com/stefanberger/swtpm/blob/master/src/swtpm/swtpm_io.c"
    click cuse "https://github.com/stefanberger/swtpm/blob/master/src/swtpm/cuse_tpm.c"
    click bios "https://github.com/stefanberger/swtpm/blob/master/src/swtpm_bios/tpm_bios.c"
    click ioctl "https://github.com/stefanberger/swtpm/blob/master/src/swtpm_ioctl/tpm_ioctl.c"
    click localca "https://github.com/stefanberger/swtpm/blob/master/src/swtpm_localca/swtpm_localca.c"
    click certificate "https://github.com/stefanberger/swtpm/blob/master/src/swtpm_cert/ek-cert.c"
    click setup "https://github.com/stefanberger/swtpm/blob/master/src/swtpm_setup/swtpm_setup.c"
    click a "https://github.com/stefanberger/swtpm/blob/master/autogen.sh"
    click conf "https://github.com/stefanberger/swtpm/blob/master/configure.ac"
    click mf "https://github.com/stefanberger/swtpm/blob/master/Makefile.am"
    click imf "https://github.com/stefanberger/swtpm/blob/master/include/Makefile.am"
    click tests "https://github.com/stefanberger/swtpm/tree/master/tests"
    click gh "https://github.com/stefanberger/swtpm/blob/master/.github"
    click df "https://github.com/stefanberger/swtpm/tree/master/Dockerfile"
    click dcy "https://github.com/stefanberger/swtpm/blob/master/docker-compose.yml"
```
