DOCSEARCHbyAlgolia
Submit Docs

EGo Framework

repository·master·Indexed 20 days ago

https://github.com/edgelesssys/ego

A framework for building confidential applications in Go that run in encrypted, verifiable enclaves on Intel SGX hardware. EGo provides specialized tooling including `ego-go` (an adapted Go compiler) and `ego` (a CLI for enclave lifecycle management, signing, and creation). The framework supports remote attestation workflows, attested TLS connections, and deployment to Azure Kubernetes Service (AKS).

Tokens
22.7K
Snippets
80
Records
112
Agent score
68%

What's inside EGo

  1. What is EGo and when should you use it?

    master

    EGo is a framework for building confidential apps in Go. It allows you to run Go programs inside secure execution environments called enclaves (specifically targeting Intel SGX).

    Enclaves provide strong isolation, runtime encryption, and attestability. You should use EGo when building server applications that handle sensitive data, such as cryptographic keys or payment information (e.g., a service similar to HashiCorp Vault).

    A key advantage of EGo is that it allows you to run standard Go programs inside an enclave without requiring code modifications.

  2. What is EGo and how does it work?

    master

    EGo is a framework for building confidential applications in Go. These applications run in always-encrypted and verifiable enclaves on Intel SGX-enabled hardware.

    EGo provides two primary tools to simplify enclave development:

    1. ego-go: An adapted Go compiler that builds enclave-compatible executables. It maintains the same CLI interface as the standard Go compiler.
    2. ego: A CLI tool used for enclave-related lifecycle tasks, including signing and enclave creation.

    To build, sign, and run a confidential Go app, use the following workflow:

    ego-go build hello.go
ego sign hello
ego run hello

  3. How remote attestation with Microsoft Azure Attestation works

    master

    This sample demonstrates a remote attestation workflow where an EGo enclave server uses Microsoft Azure Attestation to prove its identity to a client (the relying party).

    Workflow Steps:

    1. Binding Identity: The server generates a self-signed certificate and an attestation report that includes the certificate's hash, binding the certificate to the enclave's identity.
    2. Requesting Attestation: The server sends an Attestation Request (containing the report and certificate) to the Azure Attestation Provider (e.g., a Regional Shared Provider).
    3. Validation: The Azure Attestation Provider validates the SGX Quote and ensures the report contains the hash of the Enclave Held Data (the certificate).
    4. Token Issuance: Upon successful validation, the provider returns a signed JSON Web Token (JWT) to the server. This token contains the certificate and verification metadata.
    5. Server Endpoints: The enclaved server exposes:
      • /token: Returns the JWT (the client requests this while skipping TLS certificate verification).
      • /secret: Receives a secret via the s query parameter.
    6. Client Verification: The client retrieves the provider's public key from its OpenID Metadata Endpoint, verifies the JWT signature and claims, and extracts the certificate.
    7. Secure Communication: Once the certificate is validated, the client establishes a secure TLS connection to the server to transmit the secret.

    Note: This workflow requires SGX-FLC systems with a quote provider installed.

  4. Use EStore for authenticated key-value storage

    master

    EStore is a key-value store designed for use inside enclaves. It provides authenticated encryption for data at rest, making it an ideal choice for persistent, secure storage within an EGo application. For a practical implementation, refer to the EStore sample in the repository.

    // EStore sample demonstration
// https://github.com/edgelesssys/ego/tree/master/samples/estore

  5. Implementation architecture of the local attestation sample

    master

    The sample implements two distinct server roles to facilitate secure communication:

    Attest Server (Unencrypted HTTP)

    Provides the initial handshake via an unencrypted endpoint:

    • /cert: Returns the secure server's certificate.
    • /report: Returns a local report for the certificate.
    • /client: Validates the client's report and returns a certificate for the client's public key.

    Secure Server (Encrypted HTTPS)

    Provides the protected service via a mutually authenticated TLS endpoint:

    • /ping: Returns pong.

    The Secure Server only accepts connections from clients that present a certificate obtained through the /client endpoint of the Attest Server, ensuring only attested clients can access the service.

  6. Seal and unseal data using the EGo API

    master

    Sealing allows you to encrypt data using a key that is cryptographically bound to both the specific enclave identity and the hardware (CPU) it is running on. This ensures that only the same enclave running on the same hardware can decrypt the data. Use the ecrypto package to perform these operations.

    // Use the EGo API (ecrypto package) to seal and unseal data
// https://pkg.go.dev/github.com/edgelesssys/ego/ecrypto

  7. Establish an attested TLS connection with EGo

    master

    EGo allows for transparently attested TLS connections between an enclave-based server and a client. This is achieved by using specialized TLS configuration functions that integrate attestation evidence into the TLS handshake.

    Server-side Setup

    The server creates a tls.Config object using CreateAttestationServerTLSConfig(). This configuration is used to initialize a standard TLS server that can serve HTTPS requests. In this sample, the server serves a /secret endpoint that accepts a secret via the s query parameter.

    Client-side Setup

    The client creates a tls.Config object using CreateAttestationClientTLSConfig(). When using this config:

    1. The tls.Config automatically handles certificate validity.
    2. You must provide a callback function to inspect the properties of the remote report (attestation evidence) to ensure the connection is being made to the expected enclave.
    3. The client uses a standard http.Client with this configuration to communicate.

    Requirement: This functionality requires SGX-FLC systems with a quote provider installed.

  8. How local attestation works in EGo

    master

    Local attestation allows two EGo enclaves running on the same host to verify each other's identity without additional infrastructure. Unlike remote attestation, local reports can only be verified by a predetermined target enclave using a specific handshake process:

    1. Verifier creates a target report: The verifier calls GetLocalReport(nil, nil) to generate a report that identifies itself.
    2. Exchange: The verifier sends this targetReport to the attester.
    3. Attester creates a targeted report: The attester calls GetLocalReport(someData, targetReport), where targetReport is the report received from the verifier. This binds the attester's report to the specific verifier.
    4. Exchange: The attester sends this new report back to the verifier.
    5. Verification: The verifier validates the attester's report using VerifyLocalReport(report).

    Note: This mechanism is limited to enclaves on the same host and does not work in simulation mode.

    // 1. Verifier creates target report
targetReport = GetLocalReport(nil, nil)

// 3. Attester creates targeted report using verifier's report
report = GetLocalReport(someData, targetReport)

// 5. Verifier verifies the report
VerifyLocalReport(report)

  9. Understand EGo process and runtime limitations

    master

    When developing for EGo, be aware of the following runtime constraints:

    • Single Process Model: An EGo app is a single process. You cannot spawn child processes using os/exec or os.StartProcess.
    • Error Handling: A nil pointer dereference will abort the process immediately without executing any defer statements.
    • Signal Handling: The os/signal package is unsupported; signals are not passed into the enclave.
    • Memory Mapping: mmap is only partially supported; memory-mapped files are currently unsupported.

  10. Core components of the EGo architecture

    master

    EGo's architecture consists of three main pillars that enable confidential computing:

    1. Modified Go Compiler: Compiles code specifically to run inside an enclave. It is designed so that EGo-compiled apps can still run as normal applications outside of enclaves, facilitating easier development and debugging.
    2. Tooling: Includes tools for signing enclaves and a specialized GDB debugger that allows you to debug Go code while it is running inside an enclave.
    3. Go Library: Provides programmatic access to core enclave features:
      • Remote Attestation: Allows the app to prove to a client that it is running inside a genuine enclave with a specific hash. This is commonly used to bootstrap attested TLS connections.
      • Sealing: Enables the secure storage of sensitive data to untrusted disk storage.

  11. Use the in-enclave-memory filesystem for transient storage

    master
    By default, any files written by an EGo application are stored in the enclave's memory. This provides high security as the data is isolated within the enclave, but it is volatile: all data is lost when the enclave terminates. This method is suitable for temporary files or caches that do not need to persist across restarts.

  12. Connecting to a TLS server from an enclave

    master
    Enclave clients cannot rely on the host's root certificates for TLS verification. To establish a secure connection to a TLS server, you must provide the enclave with a trusted set of root certificates. You can achieve this by embedding the certificates directly into the enclave binary using the files configuration in enclave.json.