# rhboot/shim architecture

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

- Interactive diagram: https://gitdiagram.com/rhboot/shim
- Repository: https://github.com/rhboot/shim

## Overview

##### Project Type and Purpose
- The project is a UEFI bootloader (“shim”) that is designed as a first-stage loader. Its purpose is to load and validate a subsequent bootloader or application using UEFI’s standard LoadImage() and StartImage() calls.
- It adds additional security steps: when a binary is not already signed for Secure Boot, it validates the binary using built-in certificates and then, if successful, relocates and runs it.
- The project also installs a protocol to let the second-stage bootstrap perform similar validations, and on systems with a TPM chip, it will extend various PCRs with digests of the targets it loads.

##### Analyzing the File Structure
- The top-level directories include many source directories organized by functionality. For example:
- “Cryptlib” contains the cryptography implementation (cipher, hash, HMAC, etc.). It also mirrors an OpenSSL-like structure with subdirectories (such as crypto/asn1, crypto/bn, crypto/evp, etc.) – indicating its role as a cryptographic library used for signature verification and encryption operations.
- “include” houses header files that define interfaces for UEFI, TPM, signing, binaries, and configuration.
- “lib” contains utility routines and implementations that support bootloader functions (console, execute, security policy, etc.).
- There is a set of test files and test data (e.g., in test-data, test-*.c files) that facilitate testing various aspects of the firmware loader.
- Build files, Makefiles, and configuration scripts support the build system and customizing options (like specifying a vendor certificate).

##### Main Components
- UEFI Firmware Interface:
- Shim EFI Application (Main Bootloader):
- This is the core application (the “shim”) that receives control from the firmware.
- It attempts to load the secondary bootloader via standard EFI routines (LoadImage() and StartImage()).
- If these calls fail (for instance, due to signature issues when Secure Boot is enabled), it falls back on its built-in certificate validation.
- Certificate & Binary Verification Module:
- Represents the built-in certificate checking mechanism. This module reads the DER-encoded certificate file (provided optionally via VENDOR_CERT_FILE).
- It interacts with the cryptographic library for operations like hashing, signature verification, and cipher decryption.
- Cryptographic Library (Cryptlib):
- A detailed component that consists of several subcomponents (e.g., Cipher, Hash, HMAC). These are used for data encryption and integrity checks.
- TPM Integration Module:
- This module handles the extension of TPM PCRs with digests of the binaries that are loaded.
- It interacts with the UEFI firmware’s TPM interface and may be represented as a helper module used by shim.
- Installed Bootloader Protocol for Second-stage Bootloader:
- This element represents the UEFI protocol that shim installs to allow the second-stage bootloader to use similar binary validation.
- This as an interface block that exposes a function (with note about the SysV ABI on 64-bit systems).

##### Relationship and Interactions
- Data Flow:
- The Certificate & Binary Verification Module then calls upon the Cryptographic Library for cryptographic functions.
- Additionally, highlight the installation of the “Validation Protocol” that exposes functions to the second-stage bootloader.
- Architectural Patterns / Design Principles:
- Layered approach: the shim sits atop UEFI, then branches into cryptographic checks and TPM functionality.
- There is a clear separation of concerns with a dedicated cryptographic layer (Cryptlib) and separate modules for executing EFI image loading versus validating signatures.
- Modular design for extensibility (e.g., the protocol that can be used by other bootloaders).

##### Final Recommendations
- Both normal operation (successful EFI loads) and alternative paths (failure and fallback to built-in certificate validation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["UEFI Firmware"]:::firmware
    B["Shim Bootloader"]:::bootloader
    C["LoadImage()/StartImage() Service"]:::system
    I["Secondary Bootloader"]:::bootloader
    D["Certificate & Binary Verification Module"]:::validation
    E["Crypto Engine (Cryptlib)"]:::crypto
    F["TPM Integration Module"]:::tpm
    G["Installed Bootloader Protocol"]:::protocol
    HD["Mok Headers"]:::validation
    HT["TPM Headers"]:::tpm
    LPH["Loader Protocol Headers"]:::protocol

    A -->|"triggers"| B
    B -->|"LoadImage()_call"| C
    C -->|"loads"| I
    B -->|"fallback_validation"| D
    D -->|"crypto_operation"| E
    D -->|"includes"| HD
    B -->|"TPM_PCR_extension"| F
    F -->|"uses"| HT
    B -->|"install_protocol"| G
    G -->|"exposes"| LPH

    click B "https://github.com/rhboot/shim/blob/main/shim.c"
    click D "https://github.com/rhboot/shim/blob/main/MokManager.c"
    click E "https://github.com/rhboot/shim/tree/main/Cryptlib/"
    click F "https://github.com/rhboot/shim/blob/main/tpm.c"
    click G "https://github.com/rhboot/shim/blob/main/loader-proto.c"
    click HD "https://github.com/rhboot/shim/blob/main/include/mok.h"
    click HT "https://github.com/rhboot/shim/blob/main/include/tpm.h"
    click LPH "https://github.com/rhboot/shim/blob/main/include/loader-proto.h"

    classDef firmware fill:#b3d9ff,stroke:#1a75ff,stroke-width:2px;
    classDef bootloader fill:#d9ffb3,stroke:#33cc33,stroke-width:2px;
    classDef system fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef validation fill:#ffdb99,stroke:#ff9933,stroke-width:2px;
    classDef crypto fill:#ffd1dc,stroke:#ff69b4,stroke-width:2px;
    classDef tpm fill:#e6e6fa,stroke:#9370db,stroke-width:2px;
    classDef protocol fill:#fcd5ce,stroke:#e07a5f,stroke-width:2px;
```
