Skip to main content

Building and running enclaves

This section walk you through the steps to build an image and run them inside enclaves.

Setup​

  • Install docker as enclave images are built from docker images.

  • In order for enclaves to receive attestations and be a usable in Kalypso, the Dockerfile should follow the linked template. Any custom code can be added before # entry point but the part above it should remain untouched.

Building an enclave image​

To build an enclave image, you must first build the docker image. A docker image named nitroimg can created by using the following command:

docker build --no-cache ./ -t nitroimg

You can verify it by running

docker images

which should result in something like

REPOSITORY                  TAG           IMAGE ID       CREATED         SIZE
nitroimg                   latest        11231231233    4 weeks ago      65MB

Finally build the enclave image using

nitro-cli build-enclave --docker-uri nitroimg:latest --output-file nitro-enclave.eif

which will create a file name nitro-enclave.eif with logs that resemble the following:

Start building the Enclave Image...
Using the locally available Docker image...
Enclave Image successfully created.
{
  "Measurements": {
    "HashAlgorithm": "Sha384 { ... }",
    "PCR0": "3ae42f09fd46de189474f8e1af22a07f5c3270dd47fae5e414baf2dfc7366e676c4f2deaa016620c65d45978656d8ee8",
    "PCR1": "bcdf05fefccaa8e55bf2c8d6dee9e79bbff31e34bf28a99aa19e6b29c37ee80b214a414b7607236edf26fcb78654e63f",
    "PCR2": "b206dcf9e23b6973a41ca8284debabba3fc31ae2bd0e043b6e25ba37a8b0f9bb5508bd0a31d7859a426070551f102d83"
  }
}
danger

Work with the assumption that every enclave image has unique PCRs and measurements and that it is very hard to build another image with the same measurements. Hence, remember to save/backup the enclave image nitro-enclave.eif. Else, enclaves will have to be re-registered if a previously created enclave instance stops and a new one has to be spun up.

Running the enclave​

You can start the enclave with

nitro-cli run-enclave --cpu-count 2 --memory 5000 --eif-path nitro-enclave.eif --enclave-cid 88

where
--cpu-count 2 refers to the number of CPUs to be dedicated to the enclave
--memory 5000 refers to the memory to be dedicated to the enclave
--eif-path spcifies the path to enclave image file
--enclave-cid 88 mentions the vsock id through which the enclave communicates with the external environment (88 can be used as-is unless multiple enclaves are being run on the same machine)

You can also start the enclave in debug-mode, if you wish see the logs. However, in debug mode the enclaves can not be attested.

nitro-cli run-enclave --cpu-count 2 --memory 5000 --eif-path nitro-enclave.eif --enclave-cid 88 --debug-mode