# coreboot/vboot architecture

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

- Interactive diagram: https://gitdiagram.com/coreboot/vboot
- Repository: https://github.com/coreboot/vboot

## Overview

##### Project type and purpose
- This is an open-source reference implementation of Chrome OS verified-boot, delivered as C libraries and command-line tools.
- It provides:
- A firmware module (for BIOS secure-boot verification)
- User-land utilities (futility, cgpt, dumpRSAPublicKey, etc.)
- Support libraries (host code for user-land, cgpt library, TPM stubs)
- Scripts for key generation and signing workflows
- Rust language bindings

##### File structure
- firmware/        → BIOS-side secure-boot code
- cgpt/            → GPT-partition CLI and library
- host/            → shared C library for host utilities
- futility/        → “firmware utility” CLI for creating/signing/verifying images
- utility/         → misc CLI tools (dumpRSAPublicKey, tpm-related utilities)
- scripts/         → shell & Python scripts orchestrating keygen, image signing
- rust/            → Rust FFI bindings to vboot_reference C APIs
- tests/           → test harness and data (exercising all of the above)
- Build/deploy:
- Makefile & Android.bp drive compilation
- Use of external dependencies: OpenSSL (for RSA), standard C toolchain

##### README for additional insights
- README explains:
- The role of each module
- How firmware/ is the only code the BIOS includes
- How futility/ uses host/ & firmware/ to sign and validate images
- How scripts/ wrap CLI tools for secure key workflows

– BIOS firmware module (firmware/)
– CGPT tool & library (cgpt/)
– Host utility library (host/)
– Futility CLI (futility/)
– Misc utilities (utility/)
– Scripts orchestrator (scripts/)
– Rust bindings (rust/)
– External dependencies (OpenSSL, OS, C toolchain)
– Tests harness (tests/)

– futility → host lib (links)
– futility → firmware lib (links for validation routines)
– futility → cgpt lib (when manipulating GPT)
– utility tools → host lib / firmware lib (as needed)
– scripts → invoke CLI tools (futility, cgpt, dumpRSAPublicKey)
– rust bindings → call into host & firmware C APIs via FFI
– BIOS ← firmware module (final output)
– OpenSSL → key generation & signing primitives used by host/firmware libs

c. Architectural patterns & principles
– Modular C libraries for reuse (host/, cgptlib, TPM stubs)
– Thin CLI front-ends (futility/, cgpt/)
– Clear separation BIOS-side vs. user-land code
– Scripts orchestrate high-level workflows without embedding crypto

d. Key technologies
– C99 code compiled via Make/Soong (Android.bp)
– OpenSSL for RSA operations
– Shell & Python scripts for build-time workflows
– Rust FFI for language bindings

##### Elements
- Blue for libraries
- Green for CLI tools
- Orange for scripts
- Grey for external dependencies

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Modules
    firmware["firmware/ (C Library)"]:::lib
    host["host/ (C Library)"]:::lib
    cgpt["cgpt/ (CLI & Library)"]:::cli
    futility["futility/ (CLI)"]:::cli
    utility["utility/ (CLI)"]:::cli
    scripts["scripts/ (Shell & Python)"]:::script
    rust["rust/ (Rust FFI Bindings)"]:::lib
    tests["tests/ (Test Harness)"]:::ext
    Makefile["Makefile"]:::ext
    AndroidBP["Android.bp"]:::ext
    OpenSSL["OpenSSL"]:::ext
    CToolchain["C Toolchain"]:::ext
    BIOS["BIOS Image"]:::ext

    %% Relationships
    futility -->|"links to"| host
    futility -->|"links to"| firmware
    futility -->|"uses GPT lib"| cgpt

    utility -->|"uses lib APIs"| host
    utility -->|"uses validation"| firmware

    scripts -->|"invokes CLI"| futility
    scripts -->|"invokes CLI"| cgpt
    scripts -->|"invokes CLI"| utility

    rust -->|"FFI calls"| host
    rust -->|"FFI calls"| firmware

    firmware -->|"bundled into"| BIOS

    tests -->|"tests modules"| firmware
    tests -->|"tests modules"| host
    tests -->|"tests modules"| cgpt
    tests -->|"tests modules"| futility
    tests -->|"tests modules"| utility
    tests -->|"tests modules"| scripts
    tests -->|"tests modules"| rust

    Makefile -->|"builds"| firmware
    Makefile -->|"builds"| host
    Makefile -->|"builds"| cgpt
    Makefile -->|"builds"| futility
    Makefile -->|"builds"| utility
    Makefile -->|"builds"| rust

    AndroidBP -->|"configures build"| Makefile

    OpenSSL -->|"crypto ops"| host
    OpenSSL -->|"crypto ops"| firmware

    CToolchain -->|"compiles C"| firmware
    CToolchain -->|"compiles C"| host

    %% Click Events
    click firmware "https://github.com/coreboot/vboot/tree/main/firmware/"
    click cgpt "https://github.com/coreboot/vboot/tree/main/cgpt/"
    click host "https://github.com/coreboot/vboot/tree/main/host/"
    click futility "https://github.com/coreboot/vboot/tree/main/futility/"
    click utility "https://github.com/coreboot/vboot/tree/main/utility/"
    click scripts "https://github.com/coreboot/vboot/tree/main/scripts/"
    click rust "https://github.com/coreboot/vboot/tree/main/rust/"
    click tests "https://github.com/coreboot/vboot/tree/main/tests/"
    click Makefile "https://github.com/coreboot/vboot/tree/main/Makefile"
    click AndroidBP "https://github.com/coreboot/vboot/blob/main/Android.bp"

    %% Styles
    classDef lib fill:#cce5ff,stroke:#1f77b4,stroke-width:1px;
    classDef cli fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef script fill:#fff3cd,stroke:#e0a800,stroke-width:1px;
    classDef ext fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;
```
