|
1 | 1 | This folder contains the necessary files to build a Docker image for running the Notary Server on Intel SGX-enabled hardware. |
2 | 2 |
|
3 | | -The container is built as part of the CI pipeline. For details on the build process, refer to the [CI workflow configuration](../../../../.github/workflows/ci.yml). |
| 3 | +## Compile the Notary Server for Intel SGX |
| 4 | + |
| 5 | +We use [Gramine](https://github.com/gramineproject/gramine) to run the Notary Server on Intel SGX. Gramine allows the Notary Server to run in an isolated environment with minimal host requirements. |
| 6 | + |
| 7 | +The isolated environment is defined via the manifest template (`notary-server.manifest.template`). |
| 8 | + |
| 9 | +The Notary Server for SGX is compiled with the Rust feature flag `tee_quote`. This enables the server to use an ephemeral private notary key for signing attestations (`private_key_pem_path: "/ephemeral/notary.key"`) and also adds the SGX *quote* to the server's `/info` endpoint. |
| 10 | + |
| 11 | +### CI |
| 12 | + |
| 13 | +The [notary-server-sgx Docker container](https://github.com/tlsnotary/tlsn/pkgs/container/tlsn%2Fnotary-server-sgx) is built as part of the CI pipeline. For details on the build process, refer to the [CI workflow configuration](../../../../.github/workflows/ci.yml). |
| 14 | + |
| 15 | +CI builds a zip file named `notary-server-sgx.zip`, which contains the compiled binary and the signed manifest. This zip file is available for all releases and `dev` builds in the build artifacts. We also publish a Docker image `notary-server-sgx` at <https://github.com/tlsnotary/tlsn/pkgs/container/tlsn%2Fnotary-server-sgx>. Check the section below for details on running this container. |
| 16 | + |
| 17 | +### Development |
| 18 | + |
| 19 | +You can also build everything locally using the `run-gramine-local.sh` script. |
| 20 | + |
| 21 | +This script creates and signs the Gramine manifest for the Notary Server in a local development environment. It requires the Gramine SDK, so the most convenient way to use it is within a Docker container that includes the necessary dependencies and tools. |
| 22 | + |
| 23 | +> ⚠️ This script assumes that the `notary-server` binary is already built (for `linux/amd64`) and available in the current directory. Make sure it is built with the `tee_quote` feature: |
| 24 | +> `cargo build --bin notary-server --release --features tee_quote` |
| 25 | +
|
| 26 | +#### Build the Docker Image |
| 27 | + |
| 28 | +To build the Docker image for local development, run: |
| 29 | +```sh |
| 30 | +docker build -f gramine-local.Dockerfile -t gramine-local . |
| 31 | +``` |
| 32 | +#### Run the Gramine Script |
| 33 | + |
| 34 | +Once the image is built, you can run the `run-gramine-local.sh` script inside the container: |
| 35 | +``` |
| 36 | +docker run --rm -it \ |
| 37 | + --platform=linux/amd64 \ |
| 38 | + -v "${PWD}:/app" \ |
| 39 | + -w /app/ \ |
| 40 | + gramine-local \ |
| 41 | + "bash -c ./run-gramine-local.sh" |
| 42 | +``` |
| 43 | + |
| 44 | +If successful, the script will generate the following files: |
| 45 | +* `notary-server.sig` |
| 46 | +* `notary-server-sigstruct.json` |
| 47 | +* `notary-server.manifest` |
| 48 | +* `notary-server.manifest.sgx` |
| 49 | + |
| 50 | + |
| 51 | +You can verify that the provided **enclave signature (`notary-server.sig`)** matches the expected **`MR_ENCLAVE` and `MR_SIGNER`** values in `notary-server-sigstruct.json`, by running the following command inside a **Gramine Docker container** to inspect the enclave's signature: |
| 52 | + |
| 53 | +```sh |
| 54 | +docker run --rm -v "$(pwd):/work" -w /work gramineproject/gramine:latest \ |
| 55 | + "gramine-sgx-sigstruct-view --verbose --output-format=json notary-server.sig" |
| 56 | +``` |
| 57 | + |
| 58 | +The output should be the same as `notary-server-sigstruct.json` |
| 59 | + |
| 60 | +## How to Run TLSNotary on Intel SGX? |
| 61 | + |
| 62 | +Before running the Notary Server on Intel SGX hardware, ensure your system has the required Intel SGX components installed: |
| 63 | +```sh |
| 64 | +wget https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key |
| 65 | +cat intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null |
| 66 | + |
| 67 | +# Add the repository to your sources: |
| 68 | +echo 'deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu noble main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list |
| 69 | + |
| 70 | +sudo apt-get update |
| 71 | +sudo apt-get install libsgx-epid libsgx-quote-ex libsgx-dcap-ql -y |
| 72 | +``` |
| 73 | + |
| 74 | +For more details, refer to the official **[Intel SGX Installation Guide](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/Intel_SGX_SW_Installation_Guide_for_Linux.pdf).** |
| 75 | + |
| 76 | +### Docker Compose |
| 77 | + |
| 78 | +To run the Notary Server using Docker Compose, create a docker-compose.yml file like the following: |
| 79 | +```yaml |
| 80 | +services: |
| 81 | + dev: |
| 82 | + container_name: dev |
| 83 | + image: ghcr.io/tlsnotary/tlsn/notary-server-sgx:dev |
| 84 | + restart: unless-stopped |
| 85 | + devices: |
| 86 | + - /dev/sgx_enclave |
| 87 | + - /dev/sgx_provision |
| 88 | + volumes: |
| 89 | + - /var/run/aesmd/aesm.socket:/var/run/aesmd/aesm.socket |
| 90 | + ports: |
| 91 | + - "7047:7047" |
| 92 | + entrypoint: [ "gramine-sgx", "notary-server" ] |
| 93 | +``` |
| 94 | +
|
| 95 | +To retrieve the SGX attestation quote, query the `/info` endpoint: |
| 96 | +```sh |
| 97 | +curl localhost:7047/info | jq |
| 98 | +``` |
| 99 | + |
| 100 | +### Run local build directly with Gramine |
| 101 | + |
| 102 | +To run a locally built Notary Server inside a Gramine-protected SGX enclave, execute: |
| 103 | +```sh |
| 104 | +docker run --detach \ |
| 105 | + --restart=unless-stopped \ |
| 106 | + --device=/dev/sgx_enclave \ |
| 107 | + --device=/dev/sgx_provision \ |
| 108 | + --volume=/var/run/aesmd/aesm.socket:/var/run/aesmd/aesm.socket \ |
| 109 | + --publish=7047:7047 \ |
| 110 | + --volume="$(pwd):/work" \ |
| 111 | + --workdir=/work \ |
| 112 | + gramineproject/gramine:latest \ |
| 113 | + "gramine-sgx notary-server" |
| 114 | +``` |
0 commit comments