How fortanix/rust-sgx works
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/”.