anjuna-sgxrun

Name

anjuna-sgxrun

Generates a manifest, creates a signature file, and runs an application in a secure enclave created by the Anjuna SGX Runtime.

Synopsis

anjuna-sgxrun [OPTIONS] <application> [<application arguments>]
The examples on this page assume that you have installed Vault at /usr/local/bin/vault.

Description

anjuna-sgxrun is a utility for quickly testing an application under the Anjuna SGX Runtime by generating a manifest using default settings. Running an application under the Anjuna SGX Runtime is as simple as inserting anjuna-sgxrun before the regular command line for the application being run.

Because applications must be signed to run in an enclave, anjuna-sgxrun generates an application execution manifest and a signature file, where the measurement of the enclave is signed with a development certificate created during the Anjuna SGX Runtime installation.

For example, to run HashiCorp Vault, execute:

$ anjuna-sgxrun /usr/local/bin/vault server -dev

The command above combines anjuna-sgxrun --setup, anjuna-compile-manifest, anjuna-sign, and Runtime/anjuna-runtime for ease-of-use in development environments.

For production deployments, you should explicitly run each of those commands instead, which enables finer-grained control and auditing of changes.

$ anjuna-sgxrun --setup /usr/local/bin/vault  # set up the `Runtime` symlink and create the manifest template file
$ # <edit the manifest template as needed>
$ anjuna-compile-manifest /usr/local/bin/vault  # compile the manifest
$ anjuna-sign /usr/local/bin/vault  # sign the binary using the key at $SGX_SIGNER_KEY
$ Runtime/anjuna-runtime /usr/local/bin/vault [args]  # run the app

Runtime symlink

anjuna-sgxrun creates a symlink in the current working directory from ./Runtime to <runtime install path>/<platform>/bin/Runtime. This is used to locate shared libraries used by the Anjuna SGX Runtime.

Manifest template file

anjuna-sgxrun uses a manifest template to create the enclave manifest file. If the template file does not exist in the directory from which anjuna-sgxrun is run, anjuna-sgxrun will first create it from a default template.

This section describes the flow that anjuna-sgxrun uses to decide which template file to use, and if it does not exist - to create it.

anjuna-sgxrun --setup

Running anjuna-sgxrun with the --setup option creates a manifest template file if one does not exist. No other tasks are run.

When running anjuna-sgxrun --setup:

If manifest.template.yaml already exists, nothing will happen.
Otherwise, manifest.template.yaml is created with the default manifest template content.

When running anjuna-sgxrun --setup AppName:

If AppName.manifest.tempate.yaml already exists, nothing will happen.
Otherwise, AppName.manifest.tempate.yaml is created with the default manifest template content.

anjuna-sgxrun

Running anjuna-sgxrun creates a manifest template file if one does not exist, compiles the manifest, creates a signature file, and starts the enclave.

When running anjuna-sgxrun AppName:

If AppName.manifest.tempate.yaml exists, it will be used as the template file.

If AppName.manifest.tempate.yaml does not exist, but manifest.template.yaml does exist, then manifest.template.yaml will be used as the template file.

Otherwise, AppName.manifest.template.yaml is created with the default manifest template content.

The script continues, and anjuna-sgxrun compiles the AppName.manifest.yaml file, creates a signature file, and starts the enclave.

Enclave signing

For an application to run in Intel® SGX, it needs to be signed. The Anjuna installer creates a signing key that can be used for running applications in debug enclaves. Users can specify a different signing key for anjuna-sgxrun by defining the environment variable SGX_SIGNER_KEY:

$ SGX_SIGNER_KEY=<key file path> anjuna-sgxrun /usr/local/bin/vault server -dev

or

$ export SGX_SIGNER_KEY=<key file path>
$ anjuna-sgxrun /usr/local/bin/vault server -dev

A signing key can be generated with the following command:

$ openssl genrsa -3 -out <key file path> 3072

Providing secrets to the enclave

Many applications require sensitive input data to perform their function. The sensitive data could be a TLS key, some credentials, or more complex data that contains sensitive information (like a database connection string). Leaving sensitive data in the clear on the file system is problematic, and the Anjuna SGX Runtime provides a simple solution to address this problem.

Users can prepare an enclave to receive encrypted data by using the --provision command line option with the Anjuna SGX Runtime. When using this option, the Anjuna SGX Runtime starts an enclave that is identical to the enclave used to run the protected application, but instead of executing the application, it generates a random RSA key-pair and encrypts the private key using the Intel® SGX sealing capabilities. This operation guarantees that only this specific enclave can access the private key.

The enclave also generates an attestation quote, which can be verified by the Anjuna anjuna-check-attestation tool.

The public key associated with the generated private key can then be transmitted in the clear to a different trusted host that has access to the secrets. By using the public key and the anjuna-encrypt tool, a user can encrypt any sensitive file so that only the intended enclave can automatically decrypt the sensitive data.

When using the --provision option, the Anjuna SGX Runtime creates three files in the directory ./provision/:

  • ./provision/<application>.pubkey, the public key that should be used to encrypt data for this specific enclave

  • ./provision/<application>.key.sealed, the private key, which is needed to decrypt any data encrypted using the associated public key. This private key is encrypted using the Intel® SGX Sealing capabilities, and can only be decrypted by this enclave.

  • ./provision/<application>.quote.bin, the Intel® SGX Attestation Quote that proves that the public key was generated in this specific enclave.

The files ./provision/<application>.pubkey and ./provision/<application>.quote.bin should be transferred to a trusted host, where they can be used to:

  • verify that the enclave that generated the public key is a genuine Intel® SGX enclave

  • check that the identity of the enclave is correct (using the anjuna-check-attestation tool)

  • encrypt files for this enclave (using the anjuna-encrypt tool).

Encrypted files can then be copied back to the host running the enclave, and the Anjuna SGX Runtime can transparently make the encrypted files readable to the application running in the enclave.

Options

Usage options:
 anjuna-sgxrun [--provision [--spid value]] <application> [<application args>]
 anjuna-sgxrun --setup [<application>]
 anjuna-sgxrun --version

Provisioning Option:
  --spid value    Set the Intel Service Provider ID (spid)

Setup Option:
  --setup         Generates a manifest template file in current directory
  --version       Displays the version of Anjuna Runtime

Exit status

anjuna-sgxrun returns the target application’s exit code.

Example

$ anjuna-sgxrun /usr/local/bin/vault server -config config/vault_config.hcl