{"id":13631921,"url":"https://github.com/project-oak/oak","last_synced_at":"2025-04-18T01:32:16.994Z","repository":{"id":37447882,"uuid":"173796172","full_name":"project-oak/oak","owner":"project-oak","description":"Meaningful control of data in distributed systems.","archived":false,"fork":false,"pushed_at":"2024-11-06T09:00:10.000Z","size":253533,"stargazers_count":1318,"open_issues_count":70,"forks_count":113,"subscribers_count":39,"default_branch":"main","last_synced_at":"2024-11-06T09:36:27.820Z","etag":null,"topics":["distributed-systems","enclave","policy"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/project-oak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-04T18:08:59.000Z","updated_at":"2024-11-06T08:55:21.000Z","dependencies_parsed_at":"2024-11-06T09:39:31.809Z","dependency_job_id":null,"html_url":"https://github.com/project-oak/oak","commit_stats":{"total_commits":3220,"total_committers":48,"mean_commits":67.08333333333333,"dds":0.7049689440993789,"last_synced_commit":"86d9227e1faf178aecea3f2c4c9e85775784e9e8"},"previous_names":[],"tags_count":516,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-oak%2Foak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-oak%2Foak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-oak%2Foak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/project-oak%2Foak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/project-oak","download_url":"https://codeload.github.com/project-oak/oak/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223772097,"owners_count":17199967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distributed-systems","enclave","policy"],"created_at":"2024-08-01T22:02:44.228Z","updated_at":"2024-11-09T00:30:25.121Z","avatar_url":"https://github.com/project-oak.png","language":"Rust","readme":"\u003c!-- Oak Logo Start --\u003e\n\u003c!-- An HTML element is intentionally used since GitHub recommends this approach to handle different images in dark/light modes. Ref: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#specifying-the-theme-an-image-is-shown-to --\u003e\n\u003c!-- markdownlint-disable-next-line MD033 --\u003e\n\u003ch1\u003e\u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/oak-logo/svgs/oak-logo-negative.svg?sanitize=true\"\u003e\u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/oak-logo/svgs/oak-logo.svg?sanitize=true\"\u003e\u003cimg alt=\"Project Oak Logo\" src=\"docs/oak-logo/svgs/oak-logo.svg?sanitize=true\"\u003e\u003c/picture\u003e\u003c/h1\u003e\n\u003c!-- Oak Logo End --\u003e\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/project-oak/oak/ci.yaml?branch=main\u0026style=for-the-badge)](https://github.com/project-oak/oak/actions/workflows/ci.yaml?query=branch%3Amain)\n[![Docs](https://img.shields.io/badge/docs-rust-brightgreen?style=for-the-badge)](https://project-oak.github.io/oak)\n\nOak is a software platform for building distributed systems providing externally\nverifiable (or falsifiable) claims about system behaviors in a transparent way.\n\nOak provides building blocks that are used to build Enclave Applications, i.e.\napplications that are isolated from the host on which they run, and are remotely\nattestable.\n\nIn this doc we focus on distributed systems composed of heterogeneous \"nodes\"; a\nnode may be an Enclave Application running on a server (e.g. private data\ncenter, public cloud provider, etc.), a regular application running on a client\ndevice (e.g. phone, laptop), a regular HTTP or gRPC service, a storage system,\netc. When two nodes talk to each other, either or both of them may be Enclave\nApplications. For each interaction between two nodes, we refer to them as\n\"initiator\" and \"responder\". We avoid the terms \"client\" and \"server\" for those\nroles, because in some cases the \"initiator\" node may actually be running on a\n\"server\" - all combinations are possible.\n\nAn Enclave Application in an Oak distributed system can remotely attest itself\nto other nodes: this consists in providing evidence of its own software and\nhardware identity, bound to local cryptographic keys (stored in tamper-proof\nhardware, guaranteeing that keys cannot be exfiltrated or copied), ultimately\nsigned by one or more software or hardware roots of trust available on the host\nof that node. The software identity of an Enclave Application consists of\nmeasurements (i.e. digests / hashes) of the executable binaries that contribute\nto it, as well as additional data (e.g. configuration).\n\n## Root of Trust\n\nOak focuses on VM-based\n[Trusted Execution Environments (TEEs)](https://en.wikipedia.org/wiki/Trusted_execution_environment)\n(e.g. AMD SEV-SNP, Intel TDX) as hardware root of trust for Enclave\nApplications. This allows an Enclave Application to provide a remote attestation\nreport signed by hardware-bound keys in the TEE, which are not accessible by the\nservice provider. These keys are ultimately rooted in the TEE manufacturer (e.g.\nAMD, Intel); this reduces (ideally, removes) the need to trust the service\nprovider of that node in order to validate its evidence, by distributing trust\nacross multiple non colluding actors.\n\n## Encrypted Communication\n\nAt startup, each Enclave Application generates a local key pair, and binds the\npublic key to its own evidence. When a node intends to communicate with an\nEnclave Application (as either initiator or responder), an end-to-end encrypted\nchannel is established between the two nodes. As part of the channel\nestablishment, each node also provides its own evidence (if any) to the other\nnode, and may use the evidence provided by the other node to establish its\ntrustworthiness, before deciding whether to exchange data with it.\n\nThis encrypted and attested channel provides:\n\n- Confidentiality: each node knows that data sent over it may only be read by\n  the other node\n- Integrity: each node knows that data received over it must have been written\n  by the other node\n- Authenticity: each node knows the identity of the binary in any attested node\n  processing the data it sends over the channel.\n\n## Split Architecture\n\nIn order to minimize the attack surface and the Trusted Computing Base (TCB) of\nan Enclave Application, Oak encourages a split architecture:\n\n- Enclave Application: a binary built (reproducibly) from open source code,\n  running inside the TEE. The Enclave Application has access to the decryption\n  keys bound to the attestation evidence; it decrypts incoming requests from\n  other nodes, processes them, encrypts responses and sends them back over the\n  communication channel. This is the binary that is associated with externally\n  verifiable claims. No other binary has access to incoming requests in\n  plaintext.\n\n- Host Application: a binary that runs on the host (untrusted) server\n  environment that acts as the front-end for the Enclave Application; it exposes\n  a gRPC endpoint which is externally reachable by other nodes. This binary only\n  ever handles encrypted data; its main job is to create and maintain an\n  instance of the Enclave Application in the TEE, and forward encrypted data to\n  and from the Enclave Application. It may also contain proprietary logic that\n  is needed to interact with the control plane or other internal systems\n  necessary to run on the service provider infrastructure.\n\nThis architecture means the service provider would not be able to swap the\nEnclave Application binary with a different (potentially malicious) one without\nbeing detected. If the service provider were to introduce a backdoor in the\nEnclave Application, it would have to sign the binary and publish it in a\nverifiable log via the Transparent Release process, which would make the\nbackdoor irreversibly visible to external observers.\n\n## Sealed Computing\n\nA canonical use of Oak is to build privacy-preserving sealed computing\napplications.\n\nIn a sealed computing application, a node (usually a client device) sends data\nto an enclave application (usually a server), which processes data without the\nservice provider hosting the enclave application being able to see the inputs,\noutputs, or side effects of the computation.\n\nThe following is a simplified architectural diagram.\n\n![architectural_overview](docs/images/OakDiagramOverview.svg)\n\n## Operating System\n\nOak supports two flavors of Operating Systems within the TEE, on which Enclave\nApplications may be deployed:\n\n- Oak Restricted Kernel: a very minimal custom written microkernel that only\n  supports a single CPU and a single application. It places very severe\n  restrictions on what the application can do by only exposing a very limited\n  set of syscalls to the application. Oak Restricted Kernel applications are\n  suitable for cases where review of the entire trusted code base inside the TEE\n  is critical, and the limited features and reduced performance is an acceptable\n  trade-off. Ideally it should be possible for a single expert human reviewer to\n  review the code of the Oak Restricted Kernel in its entirety in a couple of\n  weeks.\n\n- Oak Containers: The Enclave Application is provided as part of an OCI runtime\n  bundle. This includes a full Linux kernel and a Linux distribution with a\n  container runtime engine inside the TEE. Using the OCI runtime bundle as a\n  compatibility layer provides a more familiar development experience and more\n  flexibility. Oak Containers also supports multiple CPUs in the TEE and is\n  therefore suitable for cases with high performance requirements. The drawback\n  of this approach is that the size of the entire trusted code base running in\n  the TEE is significantly larger, as it is not feasible for a single human\n  reviewer to review the code for the entire Linux kernel and Linux\n  distribution. The trust model for his approach relies on the security of the\n  broader Linux ecosystem. The additional features and flexibility that the\n  Linux kernel provides to the application also makes it more difficult to\n  reason about the behavior of an application, which in turn makes the review\n  process more complicated.\n\n## Remote Attestation\n\nRemote Attestation is a process by which a TEE provides evidence to a remote\nparty about its own state and the identity of the workload running inside the\nTEE (the Enclave Application).\n\nOak uses a multi-stage protocol in order to measure the identity of each layer\nin the boot process (beyond just the bootloader) and cryptographically bind it\ntogether with the TEE evidence. The [Oak Stage 0 virtual firmware](stage0) is\npre-loaded into the VM memory, and it is covered by the TEE attestation report.\nTo cover the later boot stages, Oak relies on the\n[Device Identifier Composition Engine (DICE)](https://trustedcomputinggroup.org/work-groups/dice-architectures/)\napproach, where each boot stage is responsible for measuring the next stage. Oak\naugments the attestation report with this additional evidence so that the\nidentity of all the components of the workload is covered (e.g. kernel and\napplication) by the evidence.\n\nWhen a node connects to an Enclave Application, it first requests the\nattestation evidence and associated endorsements. The endorsements include a\ncertificate chain from AMD to prove that the attestation report was signed by a\nlegitimate AMD CPU and optionally signed statements from the developers of the\nvarious components running inside the enclave. The other node then verifies the\nevidence using these endorsements to make sure it matches its expectations. The\nclient node should ensure that the enclave application is running in an\nup-to-date and correctly configured TEE (e.g. the CPU is running up to date\nversions of the microcode and SNP firmware and that debugging is disabled) and\nthat the identity of the various components running inside the enclave matches\nexpectations.\n\nOnce the node is satisfied that the enclave application meets all its\nexpectations, it uses a public key that is bound to the evidence to set up an\nencrypted channel with the enclave application.\n\nTo be sure that the enclave application will handle data in accordance with\nexpectations, external reviewers must review the code running in the TEE. Oak\nenables this by publishing provenance information of most Oak components. These\nact as a reverse index that allows a reviewer to look up the exact source code\ncommit that was used to build each component given the measurement digest of the\nbinary from the attestation evidence. All Oak components are reproducibly\nbuildable (see Transparent Release below), which means that a reviewer can fetch\nthe specific source code commit and rebuild the component to confirm that it\nproduces the same exact measurement digest. This gives the reviewer confidence\nthat the code version they are reviewing is the exact same code version that was\nloaded into the enclave during startup.\n\n## Transparent Release\n\nTransparent Release is a set of formats and tools that allow developers to\npublish and consume claims about binary artifacts in a transparent and\nnon-repudiable way.\n\nAs part of the remote attestation process, a node obtains the identity of the\nEnclave Application in the form of one or more binary digests (e.g. usually at\nleast one per each layer of the boot chain); it then needs to establish whether\nthese measurements are trustworthy.\n\nAs a first approximation, we could assume that the client knows exactly which\ndigests to expect by hard-coding them, and can verify the actual values against\nthe expected ones locally. This works, but it is very limiting with respect to\nthe evolution of the server application: as soon as any of the Enclave\nApplication binaries changes as part of a new release, the node will stop\ntrusting the Enclave Application, and the two will not be able to interact any\nmore.\n\nWe could solve this by hard-coding in the node a public key used to sign the\nbinary digests, instead of the digests themselves. This way, when the Enclave\nApplication binaries change, the developer can sign them with the corresponding\nprivate key in their possession, and distribute these signatures alongside the\nremote attestation report to the node, which can then verify the validity of\nthese signatures. This works, but it has the problem of allowing the Enclave\nApplication to present different signatures to different nodes, which would be\nvery hard for users to detect.\n\nThe solution implemented is to sign not only the digests when a new release is\ncreated, but also to log this signature to an external append-only verifiable\nlog. Oak relies on [Rekor](https://docs.sigstore.dev/logging/overview/) (by\nSigstore) as the external verifiable log for this purpose. As part of the\nTransparent Release process the signature is logged to Rekor, and an inclusion\nproof (or inclusion promise) is obtained from it, signed by Rekor's root key.\nThis is then stored alongside the binary artifact in question, and provided to\nnodes that may want to verify the identity of the Enclave Application. This\nmakes it impossible for the developer to insert a backdoor in the Enclave\nApplication without also logging it to the verifiable log.\n\n## Trust Model\n\nWe acknowledge that perfect security is impossible. In general, having a smaller\nTrusted Computing Base (TCB) is better, and Oak tries to minimize the TCB to the\nminimum components that need to be trusted.\n\n### Untrusted\n\nOak is designed to be verifiably trustworthy without needing to trust the\nfollowing:\n\n- most hardware (memory, disk, motherboard, network card, external devices)\n- Host Operating System (kernel, drivers, libraries, applications)\n- Hypervisor / VMM\n\nThe service provider may intend to access and exfiltrate users’ private data.\nThey own the host machines in the data center, therefore have server root access\nand are capable of modifying the host machine OS, drivers, hypervisor, etc. They\ncan also inspect network traffic that contains users’ data. In the Oak\narchitecture, we treat the host hardware and the host OS operated by the service\nprovider as untrusted. The data that need to be protected need to be encrypted\nwhen stored in the host OS’s memory system, with the decryption keys managed by\nthe TEE, not accessible by the service provider hosting the hardware machines.\nThe Oak architecture allows applications to make stronger claims by reducing the\nneed to trust the service provider.\n\n### Trusted-but-verifiable\n\n- Oak trusted platform\n- Enclave application\n\nBoth the Oak platform libraries and components, and the Enclave Application that\nruns on that platform, run inside the TEE. They have access to unencrypted data.\nOak establishes trust for these components by open sourcing them, and enables\nexternal inspection and verification via Transparent Release.\n\n### Trusted\n\n- Hardware TEE manufacturer (e.g. AMD, Intel)\n\nThe hardware TEE is responsible for memory encryption and decryption, and\ngenerating the remote attestation report, etc.\n\nNo particular TEE manufacturer is absolutely trusted by Oak; rather, each client\ndecides what TEE manufacturer(s) to trust when connecting to Enclave\nApplications running on other hosts. Oak makes it possible for Enclave\nApplications running on TEEs to present evidence rooted in the manufacturer of\nthe TEE itself. Additional TEE models and manufacturers may be supported by Oak\nover time.\n\n### Side channel attacks\n\n[Side-channel attacks](https://en.wikipedia.org/wiki/Side-channel_attack)\npresent significant challenges for confidential computing environments. We\nacknowledge that most existing TEEs have compromises and may be vulnerable to\nsome side-channel attacks. This is an active research area, both hardware and\nsoftware innovations are needed to defend fully against such attacks. Service\nproviders hosting the TEE based servers need to implement strong host security.\nStrong security requires\n[defense in depth](\u003chttps://en.wikipedia.org/wiki/Defense_in_depth_(computing)\u003e).\n\nAttacks that require physical access to the server hardware is another class of\nattacks that Oak and TEE hardware manufacturers cannot defend against alone.\nPhysical attacks are expensive and therefore not scalable. To defend against\nthem, service providers need to implement strong physical security in their data\ncenters.\n\n## Getting involved\n\nWe welcome [contributors](docs/CONTRIBUTING.md)! To join our community, we\nrecommend joining the\n[mailing list](https://groups.google.com/g/project-oak-discuss).\n","funding_links":[],"categories":["Distributed Systems","Rust","Application Security","Secret Management"],"sub_categories":["Library OSes and SDKs","Supply chain security","Hardware Security Module (HSM)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproject-oak%2Foak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproject-oak%2Foak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproject-oak%2Foak/lists"}