Skip to main content

Initialization parameters

In this tutorial, you will learn to pass initialization parameters while deploying your application. These initialization parameters can be files or strings which need to be passed on to enclaves during startup.

Brief​

We will be using a prebuilt Docker image so you don't have to worry about architecture differences. It is the same as the echo server you built previously which supports changing the port that the server listens on using an env var. We will attempt to change this port by using initialization parameters.

Create a docker compose file​

Create a file named docker-compose.yml describing the service being deployed:

cat > docker-compose.yml <<EOF
services:
  echo-server:
    image: marlinorg/oyster-cvm-tutorials-echo-server
    network_mode: host
    restart: unless-stopped
    env_file: "/init-params/.env"
EOF

Notice the use of the env_file option which adds env vars to the container from the file specified. It now expects us to make the specified file available through initialization params.

The init-params folder is a special directory inside the enclave where initialization files and configuration data are stored after being passed through the --init-params flag.

important

Note the use of network_mode: host. It is currently required for deploying Docker images on Oyster.

Create an env file​

Create an echo.env file that contains the PORT variable to be sent to the enclave:

cat > echo.env << EOF
PORT=5000
EOF

Deploy the enclave​

Deploy the enclave image using:

# Replace <key> with private key of the wallet
oyster-cvm deploy --wallet-private-key <key> --duration-in-minutes 15 --docker-compose docker-compose.yml --init-params ".env:1:1:file:./echo.env"

You should now be able to interact with the echo server (on the new port!) using

nc <ip> 5000

Understanding init params​

The --init-params flag allows you to pass configuration data to your enclave. Each param follows this format:

<enclave_path>:<attest>:<encrypt>:<type>:<value>

where

  • enclave_path: Path where the file will be stored within the /init-params/ folder inside the enclave
  • attest: Set to 1 to include in attestation (makes it part of the enclave's unique identity) or 0 to exclude
  • encrypt: Set to 1 to encrypt the data (only decrypted inside the enclave) or 0 for no encryption
  • type: Either file (to read from a local file) or utf8 (to use a simple string)
  • value: Either the path to a local file or a string, depending on the type

So the incantation that we used, .env:1:1:file:./echo.env, says the following

  • Take a file
  • at ./echo.env locally
  • add it to the attestation
  • encrypt it
  • make it available at /init-params/.env

Another acceptable init param is .env:1:0:utf8:PORT=5000, it skips encryption since the port doesn't have to be a secret and passes it directly on the command line without needing a separate file.

You can specify multiple init parameters by adding more --init-params flags to your command.

tip

For applications that require secrets and configuration parameters, it is recommended to use separate files for each. The configuration file should be attested but does not need to be encrypted, while the file containing secrets should be encrypted but excluded from attestation. This approach ensures that configuration parameters can be verified through attestation, while secrets remain secure and are not subject to verification.