diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index 6bbfc61..15f6e7b 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -132,12 +132,24 @@ export function getSidebar() { ], }, { - text: 'TEE Technology', + text: '🔒 TEE Technology', collapsed: true, items: [ { - text: 'Intel SGX Technology Overview', - link: '/get-started/protocol/tee/intel-sgx-technology', + text: 'Introduction to TEE Technologies', + link: '/get-started/protocol/tee/introduction', + }, + { + text: 'Intel SGX Technology', + link: '/get-started/protocol/tee/intel-sgx', + }, + { + text: 'Intel TDX Technology', + link: '/get-started/protocol/tee/intel-tdx', + }, + { + text: 'SGX vs TDX Comparison', + link: '/get-started/protocol/tee/sgx-vs-tdx', }, ], }, @@ -181,10 +193,7 @@ export function getSidebar() { text: 'Inputs and Outputs', link: '/guides/build-iapp/inputs-and-outputs', }, - { - text: 'Using TDX', - link: '/guides/build-iapp/using-tdx', - }, + { text: 'Debugging', link: '/guides/build-iapp/debugging', diff --git a/README.md b/README.md index 3b6ca9b..82e2cd8 100644 --- a/README.md +++ b/README.md @@ -230,7 +230,8 @@ for input parameters: - Add link to the new explorer feature Asset_Types in the guide => `handle-schemas-dataset-types` - Add link to remix for deploying whitelist -- SGX vs TDX need review +- complete `use-iapp` section +- Maybe split input and output in two diff sub section in build your iapp guide - Explorer l'intégration de codeSpace - Add a Development workflow section (1 - ProtectData, 2- ...) - Update context7 when doc will be deployed (Martin) @@ -246,10 +247,15 @@ for input parameters: - migrate pay-per-task page into a guide - check pages (introduction & getting-started) for use-iapp guide - Schema what is iexec to do and implement -- explain TDX vs SGX - Give recap of Workerpool address fo chains - Talk about ENS on Bellecour(it's not supported on arbitrum) -- Rework Advanced iApp building guides. (from "old" protocol doc) +- Rework Advanced iApp building guides. (from "old" protocol doc) <<<<<<< HEAD +- Talk about encrypting results in use-iapp +- Refactor "advanced" section in build-iapp +- Rework src\get-started\protocol\iexec-doracle.md (transfer to guide or + rewrite) +- Talk about encrypting results in use-iapp +- Refactor "advanced" section in build-iapp - Rework src\get-started\protocol\oracle.md (transfer to guide or rewrite) - Talk about iApp secret - Improve Guide in build-iapp section - be more clear for builder ( how to diff --git a/src/get-started/protocol/tee/intel-sgx-technology.md b/src/get-started/protocol/tee/intel-sgx-technology.md deleted file mode 100644 index bd508f7..0000000 --- a/src/get-started/protocol/tee/intel-sgx-technology.md +++ /dev/null @@ -1,84 +0,0 @@ -# Overview - -**Confidential Computing** (or **Trusted Execution Environments -** **'TEE'**) -ensures computation confidentiality through mechanisms of memory encryption at -the hardware level. Applications being executed and data being processed are -safeguarded against even the most privileged access levels (OS, Hypervisor...). -Only authorized code can run inside this protected area and manipulate its data. - -In some cases, ensuring that code runs correctly without any third party -altering the execution, is even more important than hiding the computation's -data. This concept is called **Trusted Computing.** - -These guarantees are critical for a decentralized cloud where code is being -executed on a remote machine, that is not controlled by the requester. They are -also required to prevent leakage while monetizing data sets. - -## Intel® Software Guard Extension (Intel® SGX) - -[Intel® SGX](https://software.intel.com/en-us/sgx) is a technology that enables -**Trusted Computing** and **Confidential Computing**. At its core, it relies on -the creation of a special zone in the memory called an “enclave”. This enclave -can be considered as a vault, to which only the CPU can have access. Neither -privileged access-levels such as root, nor the operating system itself is -capable of inspecting the content of this region. The code, as well as the data -inside the protected zone, is totally unreadable and unalterable from the -outside. This guarantees non-disclosure of data as well as tamper-proof -execution of the code. - -An application's code can be separated into "trusted" and "untrusted" parts -where sensitive data is manipulated inside the protected area. - -## Confidential Computing with iExec - -Here is a general overview of how a TEE application runs on iExec: - -```mermaid -graph TD - Req[Requester] --> |1 . Buy task| Chain - Chain[Blockchain] --> |2 . Notify task to compute| Worker[Worker/Workerpool] - Worker --> |3 . Launch TEE application| App[TEE application pre-starting] - App --> |4 . Send report containing integrity information of the enclave| SMS{SMS Is integrity and authenticity
of the requesting enclave valid?} - SMS --> |No| AppFailed[TEE application run aborted] - SMS --> |Yes| AppStarted[TEE application started] - - style AppFailed color:red - style AppStarted color:green -``` - -To build such Confidential Computing (TEE) application, a developer would need -to use the Intel® SGX SDK. With iExec, you don't need to manipulate it. Instead -iExec supports the high-level Scone framework. - -At a high-level, Scone protects the confidentiality and integrity of the data -and the code without needing to modify or recompile the application. With native -Intel® SGX technology, the OS is not a part of the Trusted Computing Base (TCB) -hence system calls and kernel services are not available from an Intel® SGX -enclave. This can be limiting as the application will not be able to use File -System and sockets directly from the code running inside the enclave. The -[Scone](https://scontain.com/) framework resolves this and reduces the burden of -porting the application to Intel® SGX. - -More precisely, Scone provides a C standard library interface to container -processes. System calls are executed outside of the enclave, but they are -shielded by transparently encrypting/decrypting application data. Files stored -outside of the enclave are therefore encrypted, and network communication is -protected by Transport Layer Security (TLS). - -For a deeper understanding, you can have a look to the official -[Scone documentation](https://sconedocs.github.io/). - -## Let's build - -::: warning - -Following steps will show you how to build a Confidential Computing application. -The environment you are about to use is a "develop" environment: - -- which can be reset at any time -- where configurations and secrets might be inspected (debug enclaves) - -When your developer discovery journey is complete, please reach the -[production section](/guides/build-iapp/build-&-test#go-to-production). - -::: diff --git a/src/get-started/protocol/tee/intel-sgx.md b/src/get-started/protocol/tee/intel-sgx.md new file mode 100644 index 0000000..125ef5e --- /dev/null +++ b/src/get-started/protocol/tee/intel-sgx.md @@ -0,0 +1,148 @@ +--- +title: Intel SGX Technology +description: + Learn about Intel Software Guard Extensions (SGX) - the first-generation TEE + technology +--- + +# 🛡️ Intel SGX Technology + +**Intel® Software Guard Extensions (Intel® SGX)** is the first-generation TEE +technology that enables **Trusted Computing** and **Confidential Computing**. On +the iExec platform, SGX is the **production-ready, widely-supported TEE +technology** that powers secure, privacy-preserving applications in the +decentralized cloud. + +## What is Intel SGX? + +[Intel® SGX](https://software.intel.com/en-us/sgx) creates a special secure +zone in memory called an "enclave" - think of it as a vault that only the CPU +can access. Neither the operating system nor any other software can see what's +happening inside this protected area. Your code and data are completely private +and secure. + +## SGX: The "Application-Level" Security + +**Intel SGX** is like having a **small, specialized safe** inside your office +for specific valuable items. It protects individual applications or parts of +applications. + +### Key Characteristics + +- **Scope**: Protects specific parts of your application +- **Memory**: Limited secure memory (like a small safe) +- **Code Changes**: Requires modifications to your application +- **Use Case**: Perfect for focused, lightweight applications + +**Analogy**: SGX is like installing a small, specialized safe inside your office +for specific valuable items. + +### Visual Representation + +```mermaid +graph TB + OS[Operating System
Can see everything] + App[Regular Application
Visible & Vulnerable] + Enclave[🔒 SGX Enclave
Protected] + Data[Sensitive Code & Data
Encrypted] + OS --> App + App --> Enclave + Enclave --> Data + style Enclave fill:#ffffff,stroke:#0000ff,stroke-width:2px,color:#000000 + style Data fill:#ffffff,stroke:#00ff00,stroke-width:2px,color:#000000 +``` + +## SGX Technology Details + +### How SGX Works + +1. **Enclave Creation**: SGX creates a secure memory region (enclave) that only + the CPU can access +2. **Code Isolation**: Sensitive code runs inside the enclave, isolated from the + rest of the system +3. **Memory Encryption**: All data in the enclave is automatically encrypted +4. **Integrity Protection**: The enclave can prove it's running the correct, + unmodified code + +### SGX Limitations + +With native Intel® SGX technology, the OS is not a part of the Trusted +Computing Base (TCB), hence system calls and kernel services are not available +from an Intel® SGX enclave. This can be limiting as the application will not be +able to use File System and sockets directly from the code running inside the +enclave. + +### iExec's SGX Infrastructure + +iExec provides a complete SGX ecosystem that includes: + +- **🔐 Secret Management Service (SMS)**: Secure storage for encryption keys and + secrets +- **🛡️ SGX Workers**: Computing nodes with SGX hardware support +- **📋 Task Verification**: Proof of contribution system that verifies SGX + execution +- **🔗 Blockchain Integration**: Decentralized coordination and payment +- **📦 Scone Framework**: High-level development framework for SGX applications + +### Why iExec Uses Scone + +To build Confidential Computing (TEE) applications with SGX, iExec uses the +high-level **Scone framework** instead of requiring developers to manipulate the +Intel® SGX SDK directly. + +#### Scone Framework Benefits + +At a high-level, Scone protects the confidentiality and integrity of the data +and the code without needing to modify or recompile the application. The +[Scone](https://scontain.com/) framework resolves the limitations of native SGX +and reduces the burden of porting the application to Intel® SGX. + +#### How Scone Works + +More precisely, Scone provides a C standard library interface to container +processes. System calls are executed outside of the enclave, but they are +shielded by transparently encrypting/decrypting application data. Files stored +outside of the enclave are therefore encrypted, and network communication is +protected by Transport Layer Security (TLS). + +For a deeper understanding, you can have a look to the official +[Scone documentation](https://sconedocs.github.io/). + +### iExec SGX Workflow + +```mermaid +graph TD + Dev[Developer] + Build[Build with Scone] + Deploy[Deploy to iExec] + Worker[SGX Worker Selected] + Enclave[SGX Enclave Created] + Execute[Secure Execution] + Proof[Proof of Contribution] + Result[Results] + Dev --> Build + Build --> Deploy + Deploy --> Worker + Worker --> Enclave + Enclave --> Execute + Execute --> Proof + Proof --> Result + style Enclave fill:#ffffff,stroke:#0000ff,stroke-width:2px,color:#000000 + style Execute fill:#ffffff,stroke:#0000ff,stroke-width:2px,color:#000000 +``` + +## What's Next? + +**Learn about the next generation**: + +- **[Intel TDX Technology](/get-started/protocol/tee/intel-tdx)** - + Next-generation VM-level TEE technology +- **[SGX vs TDX Comparison](/get-started/protocol/tee/sgx-vs-tdx)** - Detailed + comparison of both technologies + +**Ready to build with SGX?** Check out the practical guides: + +- **[Build & Deploy](/guides/build-iapp/build-&-deploy)** - Create your first + SGX application +- **[Advanced SGX Development](/guides/build-iapp/advanced/create-your-first-sgx-app)** - + Deep dive into SGX development diff --git a/src/get-started/protocol/tee/intel-tdx.md b/src/get-started/protocol/tee/intel-tdx.md new file mode 100644 index 0000000..d7e2fb4 --- /dev/null +++ b/src/get-started/protocol/tee/intel-tdx.md @@ -0,0 +1,148 @@ +--- +title: Intel TDX Technology +description: + Learn about Intel Trust Domain Extensions (TDX) - the next-generation TEE + technology +--- + +# 🛡️ Intel TDX Technology + +**Intel TDX (Trust Domain Extensions)** is Intel's next-generation confidential +computing technology, representing the evolution from application-level to +virtual machine-level protection. On the iExec platform, TDX is an +**experimental technology** that offers advanced capabilities for +memory-intensive workloads and legacy application migration. + +## What is Intel TDX? + +**TDX (Trust Domain Extensions)** is Intel's newer confidential computing +technology that provides VM-level protection, allowing entire virtual machines +to run in secure, isolated environments. + +### Key TDX Benefits + +1. **🔄 Lift-and-Shift Compatibility**: Run existing applications with minimal + changes +2. **💾 Large Memory Support**: Handle memory-intensive workloads (AI, + databases) +3. **🛡️ VM-Level Protection**: Protect entire virtual machines, not just + applications +4. **⚡ Better Performance**: Optimized for complex workloads + +## TDX: The "Virtual Machine-Level" Security + +**Intel TDX** is like having an **entire secure building** where you can move +your existing operations without major renovations. It protects entire virtual +machines. + +### Key Characteristics + +- **Scope**: Protects entire virtual machines +- **Memory**: Large secure memory space (like a large vault) +- **Code Changes**: Minimal changes needed - "lift and shift" approach +- **Use Case**: Ideal for complex applications, legacy systems, and AI workloads + +**Analogy**: TDX is like moving your entire office into a secure building where +everything is protected. + +### Visual Representation + +```mermaid +graph TB + Hypervisor[Hypervisor
Cannot see inside TDX] + TrustDomain[🔒 TDX Trust Domain
Entire VM Protected] + App[Your Complete Application
All Protected] + Data[OS, Libraries, Data
All Encrypted] + Hypervisor --> TrustDomain + TrustDomain --> App + App --> Data + style TrustDomain fill:#ffffff,stroke:#0000ff,stroke-width:2px,color:#000000 + style Data fill:#ffffff,stroke:#00ff00,stroke-width:2px,color:#000000 +``` + +## TDX Technology Details + +### How TDX Works + +1. **Trust Domain Creation**: TDX creates secure virtual machines called "trust + domains" +2. **VM-Level Isolation**: Entire virtual machines run in isolated, secure + environments +3. **Large Memory Support**: Significantly larger secure memory space compared + to SGX +4. **Legacy Compatibility**: Existing applications can run with minimal + modifications + +### TDX Advantages + +- **Larger Memory**: Multi-GB+ secure memory space vs limited SGX memory +- **Easier Migration**: "Lift and shift" approach for existing applications +- **Better Performance**: Optimized for complex, memory-intensive workloads +- **VM-Level Security**: Protects entire virtual machines, not just applications + +## TDX with iExec + +iExec is actively exploring TDX technology to expand the platform's capabilities +and prepare for the future of confidential computing. + +### iExec's TDX Infrastructure + +iExec provides experimental TDX support through: + +- **🔬 Experimental Worker Pools**: Limited TDX-enabled workers for testing +- **📦 TDX Technology Support**: Integration with Intel TDX technology +- **🔐 Secret Management Service**: SMS support for TDX applications +- **📋 Task Verification**: Proof of contribution for TDX executions +- **🔗 Blockchain Integration**: Decentralized coordination and payment + +### iExec TDX Workflow + +```mermaid +graph TD + Dev[Developer] + Build[Build TDX App] + Deploy[Deploy to iExec] + Worker[TDX Worker Selected] + TrustDomain[TDX Trust Domain Created] + Execute[Secure Execution] + Proof[Proof of Contribution] + Result[Results] + Dev --> Build + Build --> Deploy + Deploy --> Worker + Worker --> TrustDomain + TrustDomain --> Execute + Execute --> Proof + Proof --> Result + style TrustDomain fill:#ffffff,stroke:#0000ff,stroke-width:2px,color:#000000 + style Execute fill:#ffffff,stroke:#0000ff,stroke-width:2px,color:#000000 +``` + +## When to Use TDX + +**TDX is ideal for**: + +- 💾 Working with memory-intensive applications +- 🔄 Running existing applications with minimal changes +- 🚀 Running complex workloads with VM-level protection + +## What's Next? + +**Learn about the foundation**: + +- **[Intel SGX Technology](/get-started/protocol/tee/intel-sgx)** - + First-generation application-level TEE technology +- **[SGX vs TDX Comparison](/get-started/protocol/tee/sgx-vs-tdx)** - Detailed + comparison of both technologies + +**Ready to experiment with TDX?** Check out the practical guides: + +- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/create-your-first-tdx-app)** - + Build TDX applications with traditional deployment and iApp Generator +- **[Create Your First TDX App](/guides/build-iapp/advanced/create-your-first-tdx-app)** - + Build TDX applications + +**For production applications, use SGX**: + +- **[Build & Deploy](/guides/build-iapp/build-&-deploy)** - Create + production-ready SGX applications diff --git a/src/get-started/protocol/tee/introduction.md b/src/get-started/protocol/tee/introduction.md new file mode 100644 index 0000000..d3c35b0 --- /dev/null +++ b/src/get-started/protocol/tee/introduction.md @@ -0,0 +1,125 @@ +--- +title: Introduction to TEE Technologies +description: + Learn the fundamentals of Trusted Execution Environments and Confidential + Computing +--- + +# 🛡️ Introduction to TEE Technologies + +**Trusted Execution Environments (TEE)** are the foundation of confidential +computing, providing hardware-level security for sensitive applications and data +processing. On the iExec platform, TEE technologies enable secure, +privacy-preserving computation in a decentralized environment. + +## What is Confidential Computing? + +**Confidential Computing** ensures that your data and code are protected even +when running on computers you don't control. Think of it as having a secure +vault inside any computer where your sensitive operations happen privately. + +**Key Benefits:** + +- 🔒 **Data Privacy**: Your data stays encrypted and private during processing +- 🛡️ **Hardware Security**: Special CPU features keep your data safe +- 🌐 **Trust Anywhere**: Run securely on remote computers + +## Understanding TEE: The Foundation + +### What is TEE (Trusted Execution Environment)? + +Think of a **TEE** as a **secure vault inside your computer** where sensitive +operations happen. It's like having a private room that only authorized code can +enter, and once inside, everything is protected from the outside world. + +**Real-world analogy**: Imagine a bank vault inside a regular building. The +building (your computer) can be accessed by many people, but the vault (TEE) has +special security measures that keep its contents completely private and secure. + +### TEE vs Regular Computing + +| **Regular Computing** | **TEE Computing** | +| ------------------------------- | -------------------------------------- | +| Code and data visible to OS | Code and data encrypted and hidden | +| Vulnerable to system attacks | Protected even from privileged access | +| No hardware security guarantees | Hardware-level security protection | +| Like working in a public space | Like working in a secure, private room | + +### Visual Representation + +**Regular Computing:** + +```mermaid +graph TB + OS1[Operating System
Can see everything] + App1[Your Application
Visible & Vulnerable] + Data1[Sensitive Data
Exposed] + OS1 --> App1 + App1 --> Data1 + style Data1 fill:#ffffff,stroke:#ff0000,stroke-width:2px,color:#000000 + style OS1 fill:#ffffff,stroke:#000000,stroke-width:1px,color:#000000 + style App1 fill:#ffffff,stroke:#000000,stroke-width:1px,color:#000000 +``` + +**TEE Computing:** + +```mermaid +graph TB + OS2[Operating System
Cannot see inside TEE] + App2[Regular Application Parts] + TEE[🔒 TEE Enclave
Protected] + Data2[Sensitive Code & Data
Encrypted] + OS2 --> App2 + App2 --> TEE + TEE --> Data2 + style TEE fill:#ffffff,stroke:#0000ff,stroke-width:2px,color:#000000 + style Data2 fill:#ffffff,stroke:#00ff00,stroke-width:2px,color:#000000 + style OS2 fill:#ffffff,stroke:#000000,stroke-width:1px,color:#000000 + style App2 fill:#ffffff,stroke:#000000,stroke-width:1px,color:#000000 +``` + +## How TEE Works + +### Core Principles + +1. **Hardware Protection**: Special CPU features create isolated, secure areas +2. **Memory Encryption**: All data in the secure area is automatically encrypted +3. **Access Control**: Only authorized code can enter the secure area +4. **Integrity Verification**: The system can prove it's running the correct + code + +## TEE Technology Evolution + +TEE technologies have evolved to address different use cases: + +### First Generation: Application-Level Protection (Intel SGX) + +- **Focus**: Protecting specific parts of applications +- **Memory**: Limited secure memory +- **Use Cases**: Lightweight applications +- **iExec Support**: ✅ Production-ready + +### Second Generation: Virtual Machine-Level Protection (Intel TDX) + +- **Focus**: Protecting entire virtual machines +- **Memory**: Large secure memory space +- **Use Cases**: Complex applications, AI workloads +- **iExec Support**: 🔬 Experimental + +## What's Next? + +**Learn about specific TEE technologies**: + +- **[Intel SGX Technology](/get-started/protocol/tee/intel-sgx)** - + First-generation application-level TEE +- **[Intel TDX Technology](/get-started/protocol/tee/intel-tdx)** - + Next-generation VM-level TEE +- **[SGX vs TDX Comparison](/get-started/protocol/tee/sgx-vs-tdx)** - + Side-by-side technology comparison + +**Ready to build with TEE?** Check out the practical guides: + +- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/create-your-first-tdx-app)** - + Build TDX applications with traditional deployment and iApp Generator +- **[Build & Deploy](/guides/build-iapp/build-&-deploy)** - Create your first + TEE application diff --git a/src/get-started/protocol/tee/sgx-vs-tdx.md b/src/get-started/protocol/tee/sgx-vs-tdx.md new file mode 100644 index 0000000..43d28ab --- /dev/null +++ b/src/get-started/protocol/tee/sgx-vs-tdx.md @@ -0,0 +1,85 @@ +--- +title: SGX vs TDX Comparison +description: + Comprehensive comparison of Intel SGX and Intel TDX TEE technologies +--- + +# 🛡️ SGX vs TDX: Technology Comparison + +**Intel SGX and Intel TDX are both TEE technologies, but they solve the security +problem differently.** On the iExec platform, SGX is the **production-ready, +widely-supported technology**, while TDX is the **experimental, next-generation +technology** for advanced use cases. + +## Quick Overview + +| Aspect | Intel SGX | Intel TDX | +| ----------------------- | ------------------------------- | ------------------------- | +| **Release Year** | 2015 | 2023 | +| **Protection Scope** | Application level | Trusted domain level | +| **Memory Size** | Limited | Extensive (multi-GB+) | +| **Code Changes** | ❌ Significant changes required | ✅ Minimal changes needed | +| **iExec Status** | ✅ Production ready | 🔬 Experimental | +| **Worker Availability** | ✅ Widely supported | ❌ Limited availability | +| **iExec Use Cases** | Lightweight applications | Complex workloads | +| **Platform Support** | Full iExec ecosystem | Experimental workerpools | + +## Key Differences + +### 🎯 **Protection Scope** + +| Aspect | [Intel SGX](/get-started/protocol/tee/intel-sgx) | [Intel TDX](/get-started/protocol/tee/intel-tdx) | +| -------------------- | ------------------------------------------------------------ | -------------------------------------------------------------- | +| **What it protects** | Individual applications or parts of applications | Trusted domains (secure virtual machines) | +| **Scope** | Small, focused secure areas within larger applications | Multiple trusted domains can run on a single TDX machine | +| **Analogy** | Like installing a small, specialized safe inside your office | Like having multiple secure offices within one secure building | + +### 💾 **Memory and Performance** + +| Aspect | Intel SGX | Intel TDX | +| -------------------------- | --------------------------------------------------- | -------------------------------------------------- | +| **Memory** | Limited secure memory (typically 1-2GB) | Large secure memory space (multi-GB+) | +| **Performance** | Optimized for lightweight applications | Optimized for complex, memory-intensive workloads | +| **Limitations/Advantages** | Memory constraints can limit application complexity | Can handle large datasets and complex applications | + +### 🔧 **Development and Integration** + +| Aspect | Intel SGX | Intel TDX | +| ------------------ | ---------------------------------------------------- | -------------------------------------------------- | +| **Code Changes** | Requires significant modifications to applications | Minimal changes needed - "lift and shift" approach | +| **Integration** | Higher complexity, more development work | Lower complexity, easier migration | +| **Frameworks** | Uses Scone framework on iExec for easier development | Works with standard development practices | +| **Learning Curve** | Steeper learning curve for developers | Familiar development experience | + +## When to Use Each Technology + +### Use SGX When: + +- ✅ Building production applications +- ✅ Need proven, stable technology +- ✅ Working with lightweight applications +- ✅ Require maximum worker availability +- ✅ Need focused security for specific application parts + +### Use TDX When: + +- 🔬 Experimenting with next-generation technology +- 💾 Working with memory-intensive applications +- 🔄 Running existing applications with minimal changes +- 🚀 Running complex workloads with VM-level protection + +## What's Next? + +**Learn about specific TEE technologies**: + +- **[Intel SGX Technology](/get-started/protocol/tee/intel-sgx)** - + First-generation application-level TEE +- **[Intel TDX Technology](/get-started/protocol/tee/intel-tdx)** - + Next-generation VM-level TEE + +**Ready to build with TEE?** Check out the practical guides: + +- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/create-your-first-tdx-app)** - + Build TDX applications with traditional deployment and iApp Generator +- **[Build & Deploy](/guides/build-iapp/build-&-deploy)** - Create your first + TEE application diff --git a/src/guides/build-iapp/advanced/create-your-first-sgx-app.md b/src/guides/build-iapp/advanced/create-your-first-sgx-app.md index 161c84f..0b06260 100644 --- a/src/guides/build-iapp/advanced/create-your-first-sgx-app.md +++ b/src/guides/build-iapp/advanced/create-your-first-sgx-app.md @@ -17,7 +17,7 @@ Before going any further, make sure you managed to - [iExec SDK](https://www.npmjs.com/package/iexec) 8.0.0 or higher. [Install the iExec SDK](./quick-start-for-developers.md#install-the-iexec-sdk) - Familiarity with the basic concepts of - [Intel® SGX](/get-started/protocol/tee/intel-sgx-technology) and + [Intel® SGX](/get-started/protocol/tee/intel-sgx) and [SCONE](https://scontain.com) framework. ::: diff --git a/src/guides/build-iapp/advanced/create-your-first-tdx-app.md b/src/guides/build-iapp/advanced/create-your-first-tdx-app.md index 93956d8..92040ca 100644 --- a/src/guides/build-iapp/advanced/create-your-first-tdx-app.md +++ b/src/guides/build-iapp/advanced/create-your-first-tdx-app.md @@ -1,7 +1,25 @@ -# Build Intel TDX app +# 🛡️ Build Intel TDX App (Experimental) In this tutorial, you will learn how to build and run a Confidential Computing -application with the TDX framework. +application with Intel TDX technology using both traditional deployment and the +iApp Generator. + +:::danger ⚠️ EXPERIMENTAL FEATURE + +**TDX support is currently experimental and should NOT be used in production.** +This feature is provided for testing and development purposes only. Expect +instabilities, limited compatibility, and potential outages. + +::: + +:::info Understanding TDX Concepts + +Before implementing TDX, make sure you understand the foundational concepts and +differences between TEE technologies. Check out our +**[Intel TDX Technology](/get-started/protocol/tee/intel-tdx)** guide for +comprehensive explanations of TDX technology and its benefits. + +::: ::: info @@ -25,6 +43,15 @@ application with the TDX framework. - [iExec SDK 8.13.0-tdx](https://github.com/aimen-djari/iexec-sdk/tree/feature/tdx). Contact us to have this special release. +## Choose Your Approach + +This tutorial covers two methods for building TDX applications: + +1. **[Traditional Deployment](#build-your-application)** - Manual configuration + with `chain.json` and `iexec.json` +2. **[iApp Generator](#using-iapp-generator)** - Simplified deployment using the + iApp Generator tool + ## Build your application Thanks to **Intel TDX**, neither the source code or the binaries of your @@ -32,7 +59,7 @@ application need to be changed in order to run securely in a TEE. Only two files need to be changed compared to the usual SGX workflow: `chain.json` and `iexec.json`. -iApp for the TDX framework follow the same format as non-TEE applications; +iApps using Intel TDX technology follow the same format as non-TEE applications; follow the instructions on [Build your first application](./your-first-app) to create and Dockerize your iApp. @@ -110,3 +137,175 @@ Remember, you can access task and app logs by following the instructions on page [Debug your tasks](/guides/build-iapp/debugging). ::: + +## Using iApp Generator + +The iApp Generator provides a simplified way to deploy and run TDX applications +with minimal configuration. + +### Enabling TDX in iApp Generator + +#### Environment Variable Method + +**Enable TDX for deployment and execution**: + +```bash +# Set the experimental flag +export EXPERIMENTAL_TDX_APP=true + +# Deploy and run with TDX +iapp deploy +iapp run +``` + +:::warning Environment Variable Declaration + +The syntax for setting environment variables differs between operating systems: + +- **Mac/Linux**: `export EXPERIMENTAL_TDX_APP=true` +- **Windows**: `set EXPERIMENTAL_TDX_APP=true` + +::: + +#### Per-Command Method + +**Enable TDX for specific commands**: + +```bash +# Deploy TDX-enabled iApp +EXPERIMENTAL_TDX_APP=true iapp deploy + +# Run with TDX +EXPERIMENTAL_TDX_APP=true iapp run + +# Debug TDX execution +EXPERIMENTAL_TDX_APP=true iapp debug +``` + +#### Verification + +**Check if TDX is enabled**: + +```bash +# Your deployed iApp should show TDX-related tags +iexec app show +``` + +### DataProtector SDK Configuration + +⚠️ **To use** the iExec DataProtector SDK with TDX support, you must configure +the SDK with the right SMS endpoint. + +```jsx +const dataProtector = new IExecDataProtector(web3Provider, { + iexecOptions: { + smsURL: 'https://sms.labs.iex.ec', + }, +}); +``` + +⚠️**You need** to change the default worker pool in your protected Data +declaration + +```jsx +await dataProtector.core.processProtectedData({ + protectedData: protectedData.address, + workerpool: 'tdx-labs.pools.iexec.eth', + app: '0x1919ceb0c6e60f3B497936308B58F9a6aDf071eC', +}); +``` + +### Protected Data Compatibility + +:::warning Protected Data Requirements + +**TDX iApps may require TDX-compatible protected data.** Check compatibility +before using protected data with TDX iApps. + +::: + +**Important**: The exact process for creating TDX-compatible protected data may +differ from standard protected data creation. Consult the latest DataProtector +documentation for TDX-specific requirements. + +### Development Workflow + +#### 1. **Local Testing** + +```bash +# Test locally (same as regular iApps) +iapp test --protectedData "mock_name" + +# TDX only affects remote deployment/execution +``` + +#### 2. **Deployment** + +```bash +# Deploy TDX iApp +EXPERIMENTAL_TDX_APP=true iapp deploy +``` + +#### 3. **Execution** + +```bash +# Run with TDX +EXPERIMENTAL_TDX_APP=true iapp run +``` + +## Current Limitations + +:::danger Production Warnings + +- **🚫 NOT for production use** +- **🚫 Limited worker availability** +- **🚫 Unstable execution** environment +- **🚫 Breaking changes** without notice + +::: + +## What's Next? + +### 🔧 **Continue with TDX Development** + +**Enhance your TDX application**: + +- **[Debugging Your iApp](/guides/build-iapp/debugging)** - Troubleshoot + execution issues and TDX-specific problems +- **[Inputs and Outputs](/guides/build-iapp/inputs-and-outputs)** - Handle data + in TEE environment with TDX +- **[App Access Control and Pricing](/guides/build-iapp/manage-access)** - + Configure access control for your TDX applications + +### 📚 **Learn More About TEE Technologies** + +**Deepen your understanding**: + +- **[Intel TDX Technology](/get-started/protocol/tee/intel-tdx)** - + Comprehensive guide to TDX technology and benefits +- **[SGX vs TDX Comparison](/get-started/protocol/tee/sgx-vs-tdx)** - Understand + the differences between TEE technologies +- **[Introduction to TEE Technologies](/get-started/protocol/tee/introduction)** - + Foundation concepts of TEE technologies + +### 🚀 **Production Considerations** + +**For production applications**: + +- **⚠️ TDX is experimental**: Consider using + **[Intel SGX Technology](/get-started/protocol/tee/intel-sgx)** for production +- **[Create Your First SGX App](/guides/build-iapp/advanced/create-your-first-sgx-app)** - + Build production-ready SGX applications +- **[Build & Deploy](/guides/build-iapp/build-&-deploy)** - Standard iApp + deployment guide + +### 🔗 **Related Resources** + +**Explore the iExec ecosystem**: + +- **[iApp Generator Reference](/references/iapp-generator)** - Complete iApp + Generator documentation +- **[DataProtector SDK](/references/dataProtector)** - Work with protected data + in TDX +- **[Advanced iApp Building](/guides/build-iapp/advanced/overview)** - Advanced + development techniques diff --git a/src/guides/build-iapp/advanced/end-to-end-encryption.md b/src/guides/build-iapp/advanced/end-to-end-encryption.md index 13d0944..5f7f19b 100644 --- a/src/guides/build-iapp/advanced/end-to-end-encryption.md +++ b/src/guides/build-iapp/advanced/end-to-end-encryption.md @@ -1,11 +1,11 @@ # Protect the result In previous tutorials, we saw how to build -[Confidential Computing applications](/get-started/protocol/tee/intel-sgx-technology) -that run securely inside enclaves and combine them with confidential assets to -get the most out of confidential computing advantages. In this chapter, we will -push things further to protect the workflow in an end to end mode. That means -the next step would be encrypting results. +[Confidential Computing applications](/get-started/protocol/tee/intel-sgx) that +run securely inside enclaves and combine them with confidential assets to get +the most out of confidential computing advantages. In this chapter, we will push +things further to protect the workflow in an end to end mode. That means the +next step would be encrypting results. ::: warning @@ -21,7 +21,7 @@ Before going any further, make sure you managed to - [iExec SDK](https://www.npmjs.com/package/iexec) 8.0.0 or higher. [Install the iExec SDK](./quick-start-for-developers.md#install-the-iexec-sdk) - Familiarity with the basic concepts of - [Intel® SGX](/get-started/protocol/tee/intel-sgx-technology) and + [Intel® SGX](/get-started/protocol/tee/intel-sgx) and [SCONE](https://scontain.com) framework. ::: @@ -37,9 +37,9 @@ Assuming your application is deployed (if not please check how to do it [with Scone](create-your-first-sgx-app.md#deploy-the-tee-app-on-iexec)), before triggering an execution you need to generate an RSA key-pair, then push the public key to the -[Secret Management Service](/get-started/protocol/tee/intel-sgx-technology). The -latter, in turn, will provide it, at runtime, to the enclave running your -Confidential Computing application. +[Secret Management Service](/get-started/protocol/tee/intel-sgx). The latter, in +turn, will provide it, at runtime, to the enclave running your Confidential +Computing application. To generate the key-pair, go to `~/iexec-projects` and use the following SDK command: diff --git a/src/guides/build-iapp/advanced/overview.md b/src/guides/build-iapp/advanced/overview.md index da77666..995a531 100644 --- a/src/guides/build-iapp/advanced/overview.md +++ b/src/guides/build-iapp/advanced/overview.md @@ -24,7 +24,7 @@ you efficiently: [Join our Discord](https://discord.gg/9h25DQFSCU). - **[Quick Start for Developers](./quick-start-for-developers)** - **[Build your first application](./your-first-app)** -- **[Intel SGX Technology Overview](/get-started/protocol/tee/intel-sgx-technology)** +- **[Intel SGX Technology](/get-started/protocol/tee/intel-sgx)** - **[Build your first SGX app (SCONE)](./create-your-first-sgx-app)** - **[End-to-end Encryption](./end-to-end-encryption)** - **[SGX Encrypted Dataset](./sgx-encrypted-dataset)** diff --git a/src/guides/build-iapp/advanced/sgx-encrypted-dataset.md b/src/guides/build-iapp/advanced/sgx-encrypted-dataset.md index c4e8428..8eb068b 100644 --- a/src/guides/build-iapp/advanced/sgx-encrypted-dataset.md +++ b/src/guides/build-iapp/advanced/sgx-encrypted-dataset.md @@ -6,7 +6,7 @@ the `IEXEC_DATASET_FILENAME` environment variable in your application. ::: tip Prerequisites: - Familiarity with the basic concepts of - [Intel® SGX](/get-started/protocol/tee/intel-sgx-technology) and + [Intel® SGX](/get-started/protocol/tee/intel-sgx) and [SCONE](https://scontain.com) framework. - [Build With a Scone TEE application](create-your-first-sgx-app.md) @@ -22,15 +22,15 @@ With iExec, it is possible to authorize only applications you trust to use your datasets and get paid for it. Data is encrypted using standard encryption mechanisms and the plain version never leaves your machine. The encrypted version is made available for usage and the encryption key is pushed into the -[SMS](/get-started/protocol/tee/intel-sgx-technology#secret-management-service-sms). -After you deploy the dataset on iExec it is you, and only you, who decides which +[SMS](/get-started/protocol/tee/intel-sgx#secret-management-service-sms). After +you deploy the dataset on iExec it is you, and only you, who decides which application is allowed to get the secret to decrypt it. ::: warning Datasets are only decrypted inside authorized -[enclaves](/get-started/protocol/tee/intel-sgx-technology) and never leave them. -The same thing applies to secrets. +[enclaves](/get-started/protocol/tee/intel-sgx) and never leave them. The same +thing applies to secrets. ::: @@ -171,9 +171,8 @@ iexec dataset deploy ``` You will get a hexadecimal address for your deployed dataset. Use that address -to push the encryption key to the -[SMS](/get-started/protocol/tee/intel-sgx-technology) so it is available for -authorized applications. +to push the encryption key to the [SMS](/get-started/protocol/tee/intel-sgx) so +it is available for authorized applications. For simplicity, we will use the dataset with a TEE-debug app on a debug workerpool. The debug workerpool is connected to a debug Secret Management @@ -194,8 +193,8 @@ iexec dataset check-secret We saw in this section how to encrypt a dataset and deploy it on iExec. In addition, we learned how to push the encryption secret to the -[SMS](/get-started/protocol/tee/intel-sgx-technology). Now we need to build the -application that is going to consume this dataset. +[SMS](/get-started/protocol/tee/intel-sgx). Now we need to build the application +that is going to consume this dataset. ## Prepare your application diff --git a/src/guides/build-iapp/inputs-and-outputs.md b/src/guides/build-iapp/inputs-and-outputs.md index 00c9a56..6b9a5b3 100644 --- a/src/guides/build-iapp/inputs-and-outputs.md +++ b/src/guides/build-iapp/inputs-and-outputs.md @@ -15,30 +15,124 @@ applications. This guide covers all input types available to your iApp and how to generate proper outputs that users can retrieve and decrypt. -## Development vs User Execution +## Two Perspectives on Inputs -**Two perspectives on inputs:** +**Inputs work differently depending on your role:** - 🔧 **As a developer** (using iApp Generator): You write code to access inputs from the TEE environment - 👤 **As a user** (using DataProtector): You provide inputs when executing the iApp via `processProtectedData()` +::: tip + +You can also execute iApps outside of DataProtector using other methods. See the +[Use an iApp guide](/guides/use-iapp/introduction) for more information. + +::: + This guide shows both perspectives for each input type. ## Input Types Overview -When your iApp executes in the TEE, it can access four different types of -inputs: +Inside the TEE, your iApp can work with four distinct categories of inputs: + +| Input Type | Visibility | Security Level | Purpose | How iApp Accesses It | +| --------------------- | ---------- | -------------- | ------------------------ | ---------------------- | +| **Protected Data** | Public | Encrypted | Data to be processed | Clear files in TEE | +| **Args** | Public | Clear | Configuration parameters | Command line arguments | +| **Input Files** | Public | Clear | Large datasets, models | Clear files in TEE | +| **Requester Secrets** | Private | Encrypted | User's sensitive data | Environment variables | + +## 1. Protected Data + +**What it is:** Encrypted data that's only decrypted inside your TEE +environment. + +**When to use:** Processing sensitive information like personal data, financial +records, health data. + +### How to Access Protected Data + +Protected data is available in the `IEXEC_IN` directory as decrypted files: + +::: code-group + +```python [Python] +import os +import json + +# Get the input directory and dataset filename +iexec_in = os.environ['IEXEC_IN'] +data_filename = os.environ['IEXEC_DATASET_FILENAME'] + +# Protected data is decrypted and available as files +try: + # For single protected data + with open(f"{iexec_in}/{data_filename}", 'r') as f: + data = json.load(f) + + # Access the sensitive data + user_email = data.get('email') + user_preferences = data.get('preferences') + + print(f"Processing data for user: {user_email}") + +except FileNotFoundError: + print("No protected data provided") +``` + +```javascript [JavaScript] +const fs = require('fs'); +const path = require('path'); + +// Get the input directory and dataset filename +const iexecIn = process.env.IEXEC_IN; +const dataFilename = process.env.IEXEC_DATASET_FILENAME; + +try { + // Protected data is decrypted and available as files + const dataPath = path.join(iexecIn, dataFilename); + const data = JSON.parse(fs.readFileSync(dataPath, 'utf8')); -| Input Type | Visibility | Use Case | Access Method | -| --------------------- | ----------- | ------------------------ | ---------------------- | -| **Args** | Public | Configuration parameters | Command line arguments | -| **Input Files** | Public URLs | Large datasets, models | Download from URLs | -| **Requester Secrets** | Private | API keys, credentials | Environment variables | -| **Protected Data** | Encrypted | User's sensitive data | File system in TEE | + // Access the sensitive data + const userEmail = data.email; + const userPreferences = data.preferences; -## 1. Arguments (Args) + console.log(`Processing data for user: ${userEmail}`); +} catch (error) { + console.log('No protected data provided'); +} +``` + +::: + +### How Users Provide Protected Data + +Users specify the protected data address when executing your iApp: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// User provides the protected data they want to use for processing +const response = await dataProtectorCore.processProtectedData({ + protectedData: '0x123abc...', // Address of the protected data + app: '0x456def...', // Your iApp address +}); +``` + +::: warning + +Protected data is decrypted and loaded into TEE enclave memory. Very large +datasets (>1-2GB) may cause out-of-memory errors. Consider data preprocessing or +chunking for large datasets. + +::: + +## 2. Arguments (Args) **What they are:** Public parameters passed to your iApp during execution. @@ -47,14 +141,14 @@ anything that doesn't need to be secret. ::: danger -Security Warning Args are **completely public** and visible on the blockchain -explorer. Never pass sensitive information through args. +Args are **completely public** and visible on the blockchain explorer. Never +pass sensitive information through args. ::: ### How to Access Args -In your iApp Generator project, args are passed as command-line arguments: +In your iApp project, args are passed as command-line arguments: ::: code-group @@ -107,7 +201,7 @@ const response = await dataProtectorCore.processProtectedData({ - Processing options: `"format=json output_size=small"` - Analysis parameters: `"start_date=2024-01-01 end_date=2024-12-31"` -## 2. Input Files +## 3. Input Files **What they are:** Files downloaded from public URLs during iApp execution. @@ -182,20 +276,20 @@ const response = await dataProtectorCore.processProtectedData({ - Reference datasets: `"https://data.gov/reference-corpus.csv"` - Configuration files: `"https://myapp.com/config.json"` -### Limits and Best Practices +::: warning -- **File size**: Limited by TEE enclave memory (typically several GB max) +- **File size**: Limited by TEE enclave memory (typically 1-2GB max) - **Memory constraint**: Files are loaded into enclave memory - large files may cause out-of-memory errors - **Format**: Any format (binary, text, compressed) - **URLs**: Must be direct download links (not web pages) - **Security**: Files are public - don't use for sensitive data -- **Best practice**: Keep input files under 1-2GB for reliable execution -## 3. Requester Secrets +::: + +## 4. Requester Secrets -**What they are:** Confidential credentials provided by the user running your -iApp. +**What they are:** Confidential data provided by the user running your iApp. **When to use:** API keys, database credentials, authentication tokens that the user needs to provide. @@ -238,9 +332,9 @@ if (apiKey) { ::: -### How Users Provide Inputs +### How Users Provide Requester Secrets -Users provide all inputs when executing your iApp via DataProtector: +Users provide all Requester Secrets when executing your iApp via DataProtector: ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; @@ -254,11 +348,6 @@ const processProtectedDataResponse = protectedData: '0x123abc...', // Protected data address app: '0x456def...', // Your iApp address args: 'model=bert threshold=0.8', // Public arguments - inputFiles: [ - // Public input files - 'https://example.com/model.pkl', - 'https://example.com/config.json', - ], secrets: { // Requester secrets 1: 'sk-1234567890abcdef', // API key @@ -267,115 +356,6 @@ const processProtectedDataResponse = }); ``` -## 4. Protected Data - -**What it is:** Encrypted user data that's only decrypted inside your TEE -environment. - -**When to use:** Processing user's sensitive information like personal data, -financial records, health data. - -### How to Access Protected Data - -Protected data is available in the `IEXEC_IN` directory as decrypted files: - -::: code-group - -```python [Python] -import os -import json - -# Get the input directory -iexec_in = os.environ['IEXEC_IN'] - -# Protected data is decrypted and available as files -try: - # For single protected data - with open(f"{iexec_in}/protectedData", 'r') as f: - data = json.load(f) - - # Access user's sensitive data - user_email = data.get('email') - user_preferences = data.get('preferences') - - print(f"Processing data for user: {user_email}") - -except FileNotFoundError: - print("No protected data provided") -``` - -```javascript [JavaScript] -const fs = require('fs'); -const path = require('path'); - -// Get the input directory -const iexecIn = process.env.IEXEC_IN; - -try { - // Protected data is decrypted and available as files - const dataPath = path.join(iexecIn, 'protectedData'); - const data = JSON.parse(fs.readFileSync(dataPath, 'utf8')); - - // Access user's sensitive data - const userEmail = data.email; - const userPreferences = data.preferences; - - console.log(`Processing data for user: ${userEmail}`); -} catch (error) { - console.log('No protected data provided'); -} -``` - -::: - -### How Users Provide Protected Data - -Users specify the protected data address when executing your iApp: - -```ts twoslash -import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; - -const web3Provider = getWeb3Provider('PRIVATE_KEY'); -const dataProtectorCore = new IExecDataProtectorCore(web3Provider); -// ---cut--- -// User provides their protected data for processing -const response = await dataProtectorCore.processProtectedData({ - protectedData: '0x123abc...', // Address of their protected data - app: '0x456def...', // Your iApp address -}); -``` - -### Working with Multiple Protected Datasets - -When multiple datasets are provided, they're available as separate files: - -::: code-group - -```python [Python] -import os - -iexec_in = os.environ['IEXEC_IN'] - -# List all available protected datasets -for filename in os.listdir(iexec_in): - if filename.startswith('dataset_'): - with open(f"{iexec_in}/{filename}", 'r') as f: - dataset = json.load(f) - print(f"Processing dataset: {filename}") -``` - -::: - -### Memory Limitations - -::: warning - -TEE Memory Constraints Protected data is decrypted and loaded into TEE enclave -memory. Very large datasets (>1-2GB) may cause out-of-memory errors. Consider -data preprocessing or chunking for large datasets. - -::: - ## Creating Outputs Your iApp must generate outputs in the `IEXEC_OUT` directory. **Every iApp must @@ -452,7 +432,7 @@ fs.writeFileSync( ### Output Best Practices 1. **Always create `computed.json`** - This is mandatory -2. **Use descriptive filenames** - `analysis_result.json` vs `output.txt` +2. **Use descriptive filenames** - `analysis_result.json`, not `output.txt` 3. **Include metadata** - Timestamps, versions, parameters used 4. **Structure your data** - Use JSON for structured results 5. **Keep files reasonable** - Large outputs increase retrieval time and may hit @@ -538,7 +518,7 @@ const response = await dataProtectorCore.processProtectedData({ # Access inputs in your iApp args = sys.argv[1:] # Processing parameters api_key = os.environ.get('IEXEC_REQUESTER_SECRET_1') # User's API access -protected_data = load_protected_data() # User's sensitive data +protected_data = load_protected_data() # The sensitive data to process # Process and output results results = analyze_data(protected_data, args, api_key) @@ -605,7 +585,7 @@ const response = await dataProtectorCore.processProtectedData({ # Get configuration from args report_type = get_arg('type', default='summary') -# Access user's business data +# Access the business data business_data = load_protected_data() # Generate report diff --git a/src/guides/build-iapp/manage-access.md b/src/guides/build-iapp/manage-access.md index 9d18e8c..eecc0c4 100644 --- a/src/guides/build-iapp/manage-access.md +++ b/src/guides/build-iapp/manage-access.md @@ -6,15 +6,15 @@ description: Control who can use your iApp and set pricing with app orders # 💰 Manage Access **Orders control who can use your iApp and under what conditions.** Once your -iApp is deployed with iApp Generator, you need to create app orders to make it +iApp is deployed with iApp Generator, you need to publish app orders to make it accessible to users and define your governance rules. -Think of orders as **usage contracts** - they define pricing, access +Think of orders as **usage proposals** - they define pricing, access restrictions, and execution conditions for your application. ## What is an Order? -An **app order** is a signed contract that defines the usage conditions for your +An **app order** is a signed proposal that defines the usage conditions for your iApp: - **Price per execution** (in nRLC) @@ -43,7 +43,7 @@ Here's the simplified process: 5. **You automatically receive** payment in for each execution ``` -Deployed iApp + Signed App Order = Application accessible on iExec +Deployed iApp + Published Signed App Order = Application accessible on iExec ``` ## App Order Example diff --git a/src/guides/build-iapp/using-tdx.md b/src/guides/build-iapp/using-tdx.md deleted file mode 100644 index 1992e9e..0000000 --- a/src/guides/build-iapp/using-tdx.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Using TDX (Experimental) -description: - Enable Intel TDX for enhanced TEE security in iApp - experimental feature ---- - -# 🛡️ Using TDX (Experimental) - -:::danger ⚠️ EXPERIMENTAL FEATURE - -**TDX support is currently experimental and should NOT be used in production.** -This feature is provided for testing and development purposes only. Expect -instabilities, limited compatibility, and potential outages. - -::: - -**Intel TDX (Trust Domain Extensions) is the next generation of TEE -technology.** This guide shows you how to enable TDX in your iApp and understand -the differences from the default SGX implementation. - -## What is TDX? - -**TDX (Trust Domain Extensions)** is Intel's newer confidential computing -technology, different from the default SGX implementation. - -### SGX vs TDX Differences - -**SGX (Current Default)**: - -- ✅ **Production ready** and stable -- ✅ **Widely supported** by iExec workers -- ❌ **Memory limitations** in TEE environment - -**TDX (Experimental)**: - -- ✅ **Potentially better** for memory-intensive workloads -- ❌ **Experimental** and unstable -- ❌ **Limited worker availability** -- ❌ **Not production ready** - -| Feature | Intel SGX | Intel TDX | -| ------------------------ | ----------------------------------------------------------------------------------- | -------------------------------------------- | -| Release Year | 2015 | 2023 | -| Enclave Scope | Application level | Virtual machine level | -| Code Adaptation Required | Yes - needs redesign of app's logic | No - supports lift-and-shift of full systems | -| Memory Size | Limited | Extensive (multi-GB+) | -| Integration Complexity | Higher (more dev work) | Lower (VM legacy code) | -| Best Fit For | Lightweight, high-assurance modules (e.g. wallets, crypto key ops, small AI models) | Heavier AI workloads, legacy apps, databases | - -## Enabling TDX in iApp Generator - -### Environment Variable Method - -**Enable TDX for deployment and execution**: - -```bash -# Set the experimental flag -export EXPERIMENTAL_TDX_APP=true - -# Deploy and run with TDX -iapp deploy -iapp run -``` - -:::warning Environment Variable Declaration - -The syntax for setting environment variables differs between operating systems: - -- **Mac/Linux**: `export EXPERIMENTAL_TDX_APP=true` -- **Windows**: `set EXPERIMENTAL_TDX_APP=true` - -::: - -### Per-Command Method - -**Enable TDX for specific commands**: - -```bash -# Deploy TDX-enabled iApp -EXPERIMENTAL_TDX_APP=true iapp deploy - -# Run with TDX -EXPERIMENTAL_TDX_APP=true iapp run - -# Debug TDX execution -EXPERIMENTAL_TDX_APP=true iapp debug -``` - -### Verification - -**Check if TDX is enabled**: - -```bash -# Your deployed iApp should show TDX-related tags -iexec app show -``` - -### - -⚠️ **To use** the iExec DataProtector SDK with TDX support, you must configure -the SDK with the right SMS endpoint. - -```jsx -const dataProtector = new IExecDataProtector(web3Provider, { - iexecOptions: { - smsURL: 'https://sms.labs.iex.ec', - }, -}); -``` - -⚠️**You need** to change the default worker pool in your protected Data -declaration - -```jsx -await dataProtector.core.processProtectedData({ - protectedData: protectedData.address, - workerpool: 'tdx-labs.pools.iexec.eth', - app: '0x1919ceb0c6e60f3B497936308B58F9a6aDf071eC', -}); -``` - -## Protected Data Compatibility - -:::warning Protected Data Requirements - -**TDX iApp may require TDX-compatible protected data.** Check compatibility -before using protected data with TDX iApp. - -::: - -**Important**: The exact process for creating TDX-compatible protected data may -differ from standard protected data creation. Consult the latest DataProtector -documentation for TDX-specific requirements. - -## Development Workflow - -### 1. **Local Testing** - -```bash -# Test locally (same as regular iApp) -iapp test --protectedData "mock_name" - -# TDX only affects remote deployment/execution -``` - -### 2. **Deployment** - -```bash -# Deploy TDX iApp -EXPERIMENTAL_TDX_APP=true iapp deploy -``` - -### 3. **Execution** - -```bash -# Run with TDX -EXPERIMENTAL_TDX_APP=true iapp run -``` - -## Current Limitations - -:::danger Production Warnings - -- **🚫 NOT for production use** -- **🚫 Limited worker availability** -- **🚫 Unstable execution** environment -- **🚫 Breaking changes** without notice - -::: - -## When to Use TDX - -**Consider TDX only for**: - -- 🔬 **Research/development** purposes -- 🧪 **Testing future capabilities** - -**Use SGX for**: - -- 🚀 **All production applications** -- ⚡ **Reliable execution** requirements - -## What's Next? - -**For production applications, use the standard SGX guides**: - -- **[Debugging Your iApp](/guides/build-iapp/debugging)** - Troubleshoot - execution issues -- **[Inputs and Outputs](/guides/build-iapp/inputs-and-outputs)** - Handle data - in TEE environment -- **[App Access Control and Pricing](/guides/build-iapp/manage-access)** - - Deploy production-ready iApp diff --git a/src/references/glossary.md b/src/references/glossary.md index 9be08c2..dac449a 100644 --- a/src/references/glossary.md +++ b/src/references/glossary.md @@ -12,17 +12,34 @@ description: iExec terms glossary A computer program designed to automate processes. An application is generally under the control of different communities such as product managers, project owners, or data center administrators. An application can also be decentralized -thanks to the blockchain: see “DApp”. +thanks to the blockchain: see [DApp](#decentralized-application-dapp). + +### Attestation + +A process that verifies the integrity and authenticity of a TEE environment. +Attestation proves that code is running in a genuine, unmodified TEE +environment. + +**Key Points**: + +- **Verification**: Proves the TEE environment is genuine and unmodified +- **Trust Establishment**: Builds trust between parties in confidential + computing +- **Remote Attestation**: Allows verification of remote TEE environments +- **iExec Integration**: Used to verify worker TEE environments + +**Analogy**: Attestation is like having a security guard verify that a secure +facility is legitimate and hasn't been tampered with before allowing access. ## B ### Bellecour Sidechain -iExec’s product sidechain. It is linked to Ethereum Mainnet with a bridge +iExec's product sidechain. It is linked to Ethereum Mainnet with a bridge allowing for the transfer of assets between networks. It allows iExec to be used without paying Ethereum gas fees. -See “Sidechain and xRLC” for more information. +See [Sidechain](#sidechain) and [xRLC](#xrlc) for more information. ### Beneficiary @@ -34,19 +51,14 @@ contract etc. ### Confidential Computing / Trusted Computing -Ensures computation confidentiality through mechanisms of memory encryption at -the hardware level (in a Trusted Execution Environment or TEE). It can be used -so that only authorized code can run inside a protected area and manipulate its -data. In some cases, ensuring that code runs correctly without any third party -altering the execution is even more important than hiding the computation's -data. +A technology that ensures computation confidentiality through hardware-level +memory encryption (Trusted Execution Environment or TEE). It allows only +authorized code to run in protected areas and manipulate data securely. These +guarantees are critical for decentralized cloud computing where code runs on +remote machines not controlled by the requester. -This concept is called Trusted Computing. These guarantees are critical for a -decentralized cloud where code is being executed on a remote machine, that is -not controlled by the requester. They are also required to prevent leakage while -monetizing data sets. - -See ”Trusted Execution Environments ('TEE')” for more information +See [Trusted Execution Environment (TEE)](#trusted-execution-environment-tee) +for more information ## D @@ -57,7 +69,7 @@ and a frontend user interface. A DApp has its backend code running on a decentralized peer-to-peer network. Contrast this with a traditional application where the backend code is running in fully controlled environments. -See “Application” for more information. +See [Application](#application) for more information. ### DApp Provider @@ -81,28 +93,26 @@ Owns datasets that can be monetized in the iExec marketplace. ### Deal An agreement between all parties (requester and providers) in the iExec network. -A deal is created when requester and providers’ orders are matched in the +A deal is created when requester and providers' orders are matched in the marketplace and recorded in the PoCo smart contract. ## E -### Ethereum - -A decentralized, open-source blockchain with smart contract functionality. -Ethereum proposes using blockchain technology to maintain a decentralized -payment network and to store computer code that can be used to power -decentralized applications. - ### Enclave In confidential computing jargon, an "enclave" is the special memory zone protected by the CPU. For simplicity's sake, we can refer to private regions of memory defined by Intel® SGX application as "enclaves". -### EVM (Ethereum Virtual Machine) +**Key Points**: -The Ethereum's execution environment. This is the virtual machine which executes -the smart contracts on the blockchain. +- **Protected Memory**: Secure area where sensitive code and data run +- **Hardware Protection**: Protected by CPU security features +- **Isolation**: Completely isolated from the rest of the system +- **SGX Specific**: Term primarily used with Intel SGX technology + +**Analogy**: An enclave is like a secure room within a building that only +authorized people can enter and where everything inside is protected. ### Explorer (iExec Explorer) @@ -121,10 +131,22 @@ capable of having a different value from another token from the same Smart Contract. This uniqueness may come from a variety of sources, including age, rarity, or appearance. -### iExec Academy +### Ethereum -iExec’s content aggregator where people can find content related to the project, -including articles, demos, documentation, and tutorials. +A decentralized, open-source blockchain with smart contract functionality. +Ethereum proposes using blockchain technology to maintain a decentralized +payment network and to store computer code that can be used to power +decentralized applications. + +### EVM (Ethereum Virtual Machine) + +The Ethereum's execution environment. This is the virtual machine which executes +the smart contracts on the blockchain. + +### Explorer (iExec Explorer) + +Tracks and displays all transactions occuring on iExec's platform. It provides +detailed information on the latest deals, tasks, apps, and datasets deployed. ## I @@ -135,6 +157,43 @@ crypto asset in exchange for other cryptocurrencies. The goal is to raise funds and, in turn, create a community of incentivized users who want the project to succeed so that the presale tokens gain in value. +### iExec Academy + +iExec's content aggregator where people can find content related to the project, +including articles, demos, documentation, and tutorials. + +### Intel SGX (Software Guard Extensions) + +Intel's first-generation TEE technology that protects individual applications or +parts of applications. SGX creates small, secure memory areas called "enclaves" +where sensitive code and data can run safely. + +**Characteristics**: + +- **Scope**: Application-level protection +- **Memory**: Limited secure memory (like a small safe) +- **Code Changes**: Requires significant modifications +- **Best For**: Focused, lightweight applications + +**Analogy**: SGX is like installing a small, specialized safe inside your office +for specific valuable items. + +### Intel TDX (Trust Domain Extensions) + +Intel's next-generation TEE technology that protects entire virtual machines. +TDX provides larger secure memory spaces and requires minimal code changes +compared to SGX. + +**Characteristics**: + +- **Scope**: Virtual machine-level protection +- **Memory**: Large secure memory space (multi-GB+) +- **Code Changes**: Minimal changes needed - "lift and shift" approach +- **Best For**: Complex applications, legacy systems, AI workloads + +**Analogy**: TDX is like moving your entire office into a secure building where +everything is protected. + ## M ### Mainnet @@ -164,7 +223,7 @@ paying for the creation. Once the transaction is verified, a new NFT is minted. This process to add NFTs to a blockchain allows creators to sell their photos, videos, and digital 3D objects. -See “ERC-721” for more information. +See [ERC-721](#erc-721) for more information. ### MREnclave @@ -183,17 +242,17 @@ nRLC is the smallest subdivision of the RLC token, 1 RLC equals to 10^9 nRLC. nRLC is the base unit for the PoCo, orders prices in a deal are calculated in nRLC. -See “Deal and PoCo” for more information. +See [Deal](#deal) and [PoCo](#poco-proof-of-contribution) for more information. ## O ### Oilers A term of affection used to designate the iExec community. Oilers are said to be -holding “digital oil”. This term could also be in reference to the iExec -whitepaper that states: “ iExec introduces a new paradigm in cloud computing: it +holding "digital oil". This term could also be in reference to the iExec +whitepaper that states: " iExec introduces a new paradigm in cloud computing: it will allow the trading of computing resources as commodities; in the same way we -may observe with resources such as oil, gold or rice.” +may observe with resources such as oil, gold or rice." ### Oracle @@ -223,15 +282,6 @@ payments are always fair and timely. ## R -### Requester - -A person who buys the execution of a task in the iExec marketplace. - -### RLC (Run on lots of computers) - -An Ethereum (ERC20) token launched during the iExec ICO in 2017. This utility -token is used on the iExec marketplace to buy and sell computing assets. - ### Remote attestation As explained by @@ -243,6 +293,15 @@ details about the application being attested. If the attestation is successful, a secure communication channel is established between the provider and the enclave, and secrets can safely land in the latter. +### Requester + +A person who buys the execution of a task in the iExec marketplace. + +### RLC (Run on lots of computers) + +An Ethereum (ERC20) token launched during the iExec ICO in 2017. This utility +token is used on the iExec marketplace to buy and sell computing assets. + ### Roadmap Describes business and technical developments towards the adoption of the iExec @@ -256,23 +315,34 @@ on ongoing projects and the future work. It is available here Organizes the work distribution for workers in a worker pool. -### SDK (Software Development Kit) +### Scone Framework -A set of tools for interaction with smart contracts and the iExec’s marketplace. -It is available as a CLI and JS library. Access SDK here: - +A high-level framework that simplifies the development of Intel SGX +applications. Scone provides tools and libraries to make SGX development easier +and more accessible. + +**Key Points**: + +- **SGX Simplification**: Makes SGX development easier and more accessible +- **iExec Integration**: Used by iExec to simplify SGX application development +- **High-Level Tools**: Provides libraries and tools for SGX development +- **Production Ready**: Used in production iExec SGX applications -### SGX (Secure Guard Extension by Intel) +**Analogy**: Scone is like having a toolkit that makes it easier to build secure +applications, similar to how a construction toolkit makes building houses +easier. -Is a confidential computing technology developed by Intel. +### SDK (Software Development Kit) -See “Confidential Computing” for more information. +A set of tools for interaction with smart contracts and the iExec's marketplace. +It is available as a CLI and JS library. Access SDK here: + ### Sidechain A controlled blockchain deployed over a data center and linked to Ethereum -Mainnet with a bridge permitting to transfer assets between the two. iExec’s -sidechain “Bellecour” is iExec’s mainnet bridged to ethereum mainnet. +Mainnet with a bridge permitting to transfer assets between the two. iExec's +sidechain "Bellecour" is iExec's mainnet bridged to ethereum mainnet. ### Smart Contracts @@ -282,9 +352,9 @@ contracts into digital parallels. Smart contracts are very logical - following an if this then that structure. This means they behave exactly as programmed and cannot be changed. -Nick Szabo used the term "smart contract" in 1994, when he wrote “an -introduction to the concept” and, in 1996, “an exploration of what smart -contracts could do”. +Nick Szabo used the term "smart contract" in 1994, when he wrote "an +introduction to the concept" and, in 1996, "an exploration of what smart +contracts could do". ### SMS (Secret Management Service) @@ -302,12 +372,12 @@ operation. ### Staking (of RLC) -A mechanism in PoCo that involves a certain amount of Workers’ RLC being -‘locked-up’ during the execution of a task. To prevent malicious workers, the +A mechanism in PoCo that involves a certain amount of Workers' RLC being +'locked-up' during the execution of a task. To prevent malicious workers, the locked RLC is staked as a security deposit. Workers who computed a false result will lose their stake. -See “PoCo” for more information. +See [PoCo](#poco-proof-of-contribution) for more information. ## T @@ -320,12 +390,38 @@ A task within iExec is an instance where computing power is required. Used by programmers and developers to test and troubleshoot the aspects and features of a blockchain network to ensure it is ready for mainnet launch. +### Trusted Domain + +A secure virtual machine created by Intel TDX technology. Trusted domains are +isolated, protected environments where entire applications can run securely. + +**Key Points**: + +- **VM-Level Protection**: Protects entire virtual machines, not just parts +- **Multiple Domains**: Can run multiple trusted domains on a single TDX machine +- **Complete Isolation**: Each domain is completely isolated from others +- **TDX Specific**: Term used specifically with Intel TDX technology + +**Analogy**: A trusted domain is like having multiple secure offices within one +secure building, where each office is completely private and protected. + ### Trusted Execution Environment (TEE) A hardware secure area used to guarantee the confidentiality, integrity, and -ownership of code and data. +ownership of code and data. Think of TEE as a **secure vault inside your +computer** where sensitive operations happen - like having a private room that +only authorized code can enter. + +**Key Benefits**: + +- 🔒 **Data Privacy**: Your data is encrypted and protected during processing +- 🛡️ **Code Integrity**: Your code runs exactly as intended, without tampering +- 🌐 **Trust in Untrusted Environments**: Run securely on remote computers you + don't control -See” Confidential Computing ” for more information +**Real-world analogy**: Imagine a bank vault inside a regular building. The +building (your computer) can be accessed by many people, but the vault (TEE) has +special security measures that keep its contents completely private and secure. ## W @@ -369,4 +465,5 @@ The bridge helps maintain the parity between the main chain and the external chain. For example, one xRLC on the sidechain has the same value as 1 RLC on the mainchain. -See “Sidechain, Bellecour Sidechain or Minting” for more information. +See [Sidechain](#sidechain), [Bellecour Sidechain](#bellecour-sidechain) or +[Minting](#minting) for more information. diff --git a/src/references/iapp-generator.md b/src/references/iapp-generator.md index c31f8cf..f334eab 100644 --- a/src/references/iapp-generator.md +++ b/src/references/iapp-generator.md @@ -53,8 +53,8 @@ Once you've built your first iApp, level up with these practical guides: Ready for production? Dive into specialized topics: -- **[Using TDX (Experimental)](/guides/build-iapp/using-tdx)** - Next-gen TEE - technology +- **[Build Intel TDX App (Experimental)](/guides/build-iapp/advanced/create-your-first-tdx-app)** - + Next-gen TEE with traditional deployment and iApp Generator technology - **[Complete Guides Overview](/guides/build-iapp/build-&-test)** - All development guides in one place