Configure and run a program

In the previous sections, you ran programs in secure enclaves without any special configuration. This was possible since anjuna-sgxrun created enclaves with a default configuration, and the default configuration was sufficient to run the simple example programs.

In most cases, though, you will want to configure the Anjuna SGX Runtime specifically to run your application in order to ensure that it works as well as possible, and to gain the best protections for your sensitive data.

This section presents a simple example of a custom configuration, configuring the Anjuna SGX Runtime to run OpenSSL. The instructions assume that you are using a system where the Anjuna SGX Runtime and OpenSSL are both installed and configured.

Prepare a manifest template

The Anjuna SGX Runtime takes the configuration of a secure enclave from a manifest file. The manifest provides the Anjuna SGX Runtime with parameters that control the amount of memory allocated to the enclave, the number of threads of execution permitted to run in it, the locations of input and output files, and other details that affect the correct operation of the program when running inside the enclave.

The Anjuna tools create the manifest from a manifest template, a text file that you can edit to configure the Anjuna SGX Runtime’s parameters appropriately for your application.

You will start by generating and then editing a manifest template for OpenSSL. Run the following command to generate the template file:

$ anjuna-sgxrun --setup openssl

The anjuna-sgxrun tool creates the manifest template, a file named openssl.manifest.template.yaml, and a link to a directory named Runtime containing the binaries needed to run the application with the Anjuna SGX Runtime.

You can edit the manifest template to configure parameters to your liking. For example, you can change the number of threads that the Anjuna SGX Runtime allows to run in the secure enclave.

In an editor of your choosing, open the file openssl.manifest.template.yaml and find the line that reads:

num_threads: 64

Edit that line to change the number from 64 to 32.

Next, exit your editor and execute the following command in the directory that contains openssl.manifest.template.yaml:

$ anjuna-sgxrun openssl version

The anjuna-sgxrun tool looks for a manifest file named openssl.manifest.sgx, building the manifest’s name from the name of the command you ask it to run. It notices that the manifest does not exist, but a template does. It compiles openssl.manifest.template.yaml, writing the output to openssl.manifest.sgx. It then uses the parameters in the manifest—including the adjusted thread limit—to configure the secure enclave and run OpenSSL within it.

The output for version release-1.51.0002 of the Anjuna SGX Runtime looks like this:

$ anjuna-sgxrun openssl version
Using existing openssl.manifest.template.yaml file
Compiled manifest written to openssl.manifest.sgx
"openssl.manifest.sgx" created
"openssl.sig" created
Starting "/usr/bin/openssl" in Anjuna Runtime
+ exec Runtime/anjuna-runtime --dev /usr/bin/openssl version
[ 8310] Anjuna Runtime version release-1.51.0002, Copyright (C) Anjuna Security, Inc. All rights reserved.
[ 8310] Enclave initialized:
[ 8310]     Enclave base address:           0x0000000800000000
[ 8310]     Enclave size:                   2GB
[ 8310]     Maximum number of threads:      32
[ 8310]     Enclave attributes:             0x0000000000000006
[ 8310]     Enclave SSA frame size:         1
[ 8310]     Enclave MRSIGNER:               768dd3ff9a2f7888fd9105776856d8b3e3e337dd828ab34875bc6763f7fa0721
[ 8310]     Enclave MRENCLAVE:              806b7d4da00c952cf2174d329f9025c5a9e4148762d2cfe033fc826ce171dcca
OpenSSL 1.1.1  11 Sep 2018

The output of the openssl version command appears at the end. The additional text before that output is produced by the Anjuna SGX Runtime’s tools as they process the manifest and set up the enclave.

Congratulations! You have successfully configured the Anjuna SGX Runtime to run an application with your chosen settings.