# fortanix/rust-sgx architecture

> Architecture diagram of the GitHub repository fortanix/rust-sgx, 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/fortanix/rust-sgx
- Repository: https://github.com/fortanix/rust-sgx

## Overview

##### Project’s Main Purpose and Components
- The project is a development platform for creating, testing, and running Intel SGX enclaves using Rust.
- Its main purpose is to provide a complete toolchain for developers to write, build, and run SGX enclaves.
- Key features include a set of runtime tools (for signing, loading, and attesting enclaves), a library ecosystem (several crates that implement SGX APIs and protocols), and multiple examples that show usage (e.g., “hello-world”, TLS enclaves, attestation verification tools, AWS Nitro enclaves support).

##### Break Down the Architecture into Logical Layers and Domains
a. Core Toolkit and Libraries:
– Em-App Crate: Located under “em-app/”, it implements common functions, error handling, and platform-specific support for platforms like Nitro and SGX.
– Intel-SGX Family: A large portion of the repository is devoted to the “intel-sgx” directory that contains sub-components such as:
- Aesm-Client (interface for communication with the SGX AESM service)
- Async-Usercalls (handling asynchronous usercalls in enclaves)
- DCAP-related tools (dcap-artifact-retrieval, dcap-provider, dcap-ql, dcap-retrieve-pckid)
- Enclave Runner: A related component for loading and running enclaves.
- IAS (Intel Attestation Service interface)
- SGX ISA, SGX PKIX, and sgxs-loaders – these provide low-level support for SGX-specific operations.
– Fortanix-VME: Provides support and tooling for AWS Nitro Enclaves, including eif-tools and related test suites.
– Other libraries:
- IPC-Queue: For asynchronous/synchronous inter-process communication.
- rs-libc: A reimplementation/provision of C standard library components in Rust for SGX.

b. Example Applications:
– The “examples” directory shows various sample usages—from basic “hello-world” type applications to more complex examples involving TLS, crypto mining, and usercall extensions.
– Furthermore, each example demonstrates different aspects of enclave communication, attestation, and runtime behavior.

c. Infrastructure and CI/CD:
– The “.github” directory contains workflows for building docker images, publishing crates (release process), and automated testing.
– Build and configuration scripts (e.g., Cargo.toml files in each crate, build scripts in “intel-sgx/enclave-runner/build.rs”, etc.) indicate a unified build-chain using Cargo and CI automation for testing and deploying components.

d. Documentation and Developer Guidelines:
– The “doc” folder provides detailed technical documentation about the SGX ABI, build instructions, and guides.
– The README itself serves to provide quick-start instructions and contributes to orientation about how one might build and run enclaves.

##### Relationships and Interactions
– The platform sits at the center, with the core Rust libraries interacting with the Intel SGX hardware APIs.
– The enclave runner and associated libraries (for signing, attestation, loading) form the runtime system that receives enclave binaries, validates signatures, and sets up secure execution.
– CLI tools (such as sgx-detect, ftxsgx-runner-cargo, and fortanix-sgx-tools) are built on top of these libraries to provide command-line interactions and automation.
– Examples are “clients” of the libraries – they invoke libraries to build a complete SGX enclave application, which is then signed, loaded, and attested in the runtime environment.
– Integration with external services (the IAS for attestation, AWS Nitro enclaves support) adds additional dimensions to communication flows.

##### Architectural Patterns and Key Design Choices
– “Separation of Concerns”: Components are organized based on functionality (e.g., attestation, runtime loading, IPC, low-level crypto/ABI support), making it easier to update or replace parts.
– “Modular Architecture”: Each crate/sub-project handles a specific aspect, which is then leveraged by example applications and the overall EDP.
– “CI/CD Integration”: Automated workflows ensure that changes propagate through their corresponding tooling, examples, and libraries.
– “Cross-Platform Considerations”: Given platforms like SGX, Nitro, and support for both Intel and Fortanix-specific variants, the system is designed for portability with platform-specific modules under directories like “em-app/src/platform/”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Toolkit and Libraries"
        EA("em-app Library"):::core
        IS("Intel SGX Low-Level Libraries"):::core
        P("IPC-Queue"):::auxiliary
        RSL("rs-libc"):::auxiliary
        F("AWS Nitro Enclaves / Fortanix-VME"):::core
    end

    subgraph "Enclave Tools and Runtime"
        ER("Enclave Runner & Loader"):::runner
    end

    subgraph "Attestation & Verification"
        IAS("IAS Interface"):::attestation
        DCAP("DCAP Modules"):::attestation
        PKIX("SGX PKIX"):::attestation
    end

    subgraph "Example Applications"
        EX("Examples Directory"):::examples
        EMA("Em-App Examples"):::examples
    end

    subgraph "CI/CD & Documentation"
        CICD("CI/CD Workflows"):::ci
        DOC("Documentation"):::ci
    end

    subgraph "External Entities"
        SGX("Intel SGX Hardware"):::external
    end

    %% Relationships
    EX -->|"uses"| EA
    EX -->|"uses"| IS
    EMA -->|"uses"| EA

    EA -->|"builds"| ER
    IS -->|"supports"| ER
    EA -->|"links_to"| P
    IS -->|"links_to"| RSL

    ER -->|"executes_on"| SGX

    ER -->|"attests"| IAS
    ER -->|"attests"| DCAP
    ER -->|"attests"| PKIX

    IAS -->|"communicates_with"| SGX
    DCAP -->|"retrievesPCKID"| SGX
    PKIX -->|"verifies"| SGX

    CICD -->|"automates"| EA
    CICD -->|"automates"| IS
    CICD -->|"tests"| EX
    DOC -->|"guides"| EA
    DOC -->|"guides"| IS
    DOC -->|"guides"| ER
    DOC -->|"guides"| EX

    F -->|"integrates_with"| EA
    F -->|"integrates_with"| ER

    %% Click Events
    click EA "https://github.com/fortanix/rust-sgx/tree/master/em-app/"
    click IS "https://github.com/fortanix/rust-sgx/tree/master/intel-sgx/"
    click ER "https://github.com/fortanix/rust-sgx/tree/master/intel-sgx/enclave-runner/"
    click IAS "https://github.com/fortanix/rust-sgx/tree/master/intel-sgx/ias/"
    click DCAP "https://github.com/fortanix/rust-sgx/tree/master/intel-sgx/dcap-artifact-retrieval/"
    click PKIX "https://github.com/fortanix/rust-sgx/tree/master/intel-sgx/sgx_pkix/"
    click F "https://github.com/fortanix/rust-sgx/tree/master/fortanix-vme/"
    click EX "https://github.com/fortanix/rust-sgx/tree/master/examples/"
    click EMA "https://github.com/fortanix/rust-sgx/tree/master/em-app/examples/"
    click CICD "https://github.com/fortanix/rust-sgx/tree/master/.github/"
    click DOC "https://github.com/fortanix/rust-sgx/tree/master/doc/"
    click P "https://github.com/fortanix/rust-sgx/tree/master/ipc-queue/"
    click RSL "https://github.com/fortanix/rust-sgx/tree/master/rs-libc/"

    %% Styles
    classDef core fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef runner fill:#ffa07a,stroke:#000,stroke-width:1px;
    classDef attestation fill:#ffdead,stroke:#000,stroke-width:1px;
    classDef examples fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef ci fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef auxiliary fill:#e6e6fa,stroke:#000,stroke-width:1px;
    classDef external fill:#ffe4e1,stroke:#000,stroke-width:1px;
```
