Skip to main content

Internal Architecture

Attested Connection Process​

When you use OBLV CLI to connect to an enclave, it creates a secure connection between your local environment and the enclave that is running your application. This process guarantees that all communication is handled securely while maintaining data confidentiality and integrity throughout the entire session. This page presents the operational flows that underpin the establishment of secure connections. The main two operational flows are the Controller Inititialisation flow which launches the OBLV CLI and performs initial attestation of the enclave and the Client Request flow which operates the CLI and attests the enclave with the additional services and plugins installed by the user.

Controller Initialisation Flow​

The controller initialisation flow is a phase where the OBLV CLI is executed in admin/controller mode, where it acts as a binary. This process is initiated directly by the controller itself, which performs the following steps:

  • Execution Mode: The controller launches the OBLV CLI as a binary.
  • Attestation of the Enclave: At this preliminary stage, the controller attests the enclave to ensure that the base services are operational and secure. During this phase, additional plugins or applications are not yet loaded into the enclave.

This initial step is crucial for setting up a trusted foundation before any user-specific configurations or extensions are introduced. This initiation may occur in scenarios such as scaling up applications.

Client Request Flow​

The client request flow outlines the interaction between the client-side OBLV CLI, operating as a reverse proxy, and the server-side components:

  • Execution Mode: The CLI operates in client/user mode, installed on the local machine.
  • Attestation of the Enclave: During execution, the attestation process validates not only the default and base services but also any additional services and plugins installed by the user.

This flow takes place every time a user connects to the enclave.

Detailed Steps of the Flows​

Below, you will find detailed steps of both the Controller Initialisation and the Client Request Flows. Both are very similar, however, all the user-defined services and plugins are only attested during the Client Request Flow.

  1. The controller starts OBLV CLI (only in the Controller Initialisation Flow).
  2. OBLV CLI processes the command-line arguments and determines the following:
    1. The configuration file path.
    2. Enclave's URL.
    3. The mode it needs to operate in (either user or controller depending on the flow type).
  3. OBLV CLI reads and parses the Configuration file.
  4. OBLV CLI starts to check the health state of the enclave and returns a response with a health status.
  5. OBLV CLI starts the attestation process.
  6. OBLV CLI uploads the manifest to the enclave, which in turn returns the upload response to the CLI.
  7. OBLV CLI returns a status code to the user indicating success or failure, and if successful, starts the HTTP reverse proxy on the given port.

Attestation Process​

After OBLV CLI receives a response with a success status for the health check, it goes through the validation process, where it validates the enclave based on the following details:

  • Attestation document: Validates the PCR codes and Nonce field of the attestation document. The details of these fields can be found here.
  • Manifest: A yaml file describing the application running inside the enclave is received. From this manifest, the following details are validated.
    • Docker digests for all of the containers running inside the enclave.
    • Configuration digests for the containers running inside the enclave.
note

Currently, the validation process involves comparing the string values in the Attestation response with those in the user-provided config file. However, it can be validated by retrieving the Docker digests from the container registry and calculating the hashes for the required config on the user's end.

The flow below showcases the attestation process:

Manifest Upload​

The CLI needs to upload the manifest to the enclave. The flow below exemplifies the manifest upload process:

note

For a more detailed description of the connection and the attestation processes, please contact the Oblivious team to request access to a whitepaper.

What's Next?​

Navigate to Guides to follow step-by-step guides on how to use OBLV Deploy functionalities to provide isolation and attestation to your applications.