Skip to content

Commit 33a78a7

Browse files
committed
Add reproduction instructions to README
1 parent 55aec5e commit 33a78a7

File tree

1 file changed

+37
-1
lines changed

1 file changed

+37
-1
lines changed

README.md

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,10 @@ The consensus on environment configuration is coordinated through the Manifest d
1212

1313
The Quorum Key itself can be used by QuorumOS and enclave apps to encrypt and authenticate data.
1414

15-
1615
QuorumOS ("QOS") is a minimal, immutable, and deterministic Linux unikernel targeting various Trusted Execution Environments for use cases that require high security and accountability.
1716

17+
For more information about how it's used within Turnkey, please refer to [The Turnkey Whitepaper](https://whitepaper.turnkey.com/), and more specifically: [Foundations](https://whitepaper.turnkey.com/foundations).
18+
1819
## Development
1920

2021
### Requirements
@@ -23,6 +24,41 @@ QuorumOS ("QOS") is a minimal, immutable, and deterministic Linux unikernel targ
2324
- Docker 26+
2425
- GNU Make
2526

27+
### Reproducing builds
28+
29+
QuorumOS is built with [StageX](https://codeberg.org/stagex/stagex), a new deterministic Linux distro. StageX provides reproducible builds and guarantees a 1-to-1, immutable relationship between the human-readable source code in this repo and the resulting machine-executable artifacts produced by the build system.
30+
31+
This repository produces deterministic OCI container images. QuorumOS, the operating system, is packaged for execution inside of a Nitro EIF (Enclave Image File). This packaging is deterministic and done as part of [`qos_enclave`](./src/qos_enclave). The associated [Containerfile](./src/images/qos_enclave/Containerfile) contains the set of instructions to build the `nitro.eif` file, as well as `nitro.pcrs`, which contains the PCR measurements.
32+
33+
To produce the `qos_enclave` OCI container image, run:
34+
```
35+
make out/qos_enclave/index.json
36+
```
37+
38+
If you need to extract files from it, you can do so by using [docker](https://docs.docker.com/get-started/get-docker/) and [skopeo](https://github.com/containers/skopeo):
39+
40+
```sh
41+
# Creates an archive called qos_enclave.tar, with a tag "qos-enclave:latest"
42+
skopeo copy oci:./out/qos_enclave docker-archive:qos_enclave.tar:qos-enclave:latest
43+
44+
# Load the tar into local docker
45+
docker load < qos_enclave.tar
46+
47+
# Create the container without running it (outputs a container ID)
48+
docker create qos-enclave:latest
49+
50+
# Copy files locally for inspection
51+
docker cp CONTAINER_ID:/nitro.pcrs nitro.pcrs
52+
53+
# Look at the PCR values
54+
cat nitro.pcrs
55+
b26733f9... PCR0
56+
b26733f9... PCR1
57+
21b9efbc... PCR2
58+
```
59+
60+
These PCR values can be referenced against the content of [AWS remote attestations](https://docs.aws.amazon.com/enclaves/latest/user/set-up-attestation.html#pcr012).
61+
2662
### Submitting a PR
2763

2864
Before a PR can be merged our linter and unit tests need to pass.

0 commit comments

Comments
 (0)