Manifest Entries

This section is a reference to entries that may appear in the manifest template file for a secure enclave.

policy_manager

This optional entry is used when the Anjuna SGX Runtime is used in combination with the Anjuna Policy Manager, which is a server that allows multiple enclaves to securely gain access to encryption keys that are not tied to the Intel® SGX sealing capabilities. Intel® SGX sealing keys are specific to a CPU, and as such, can not be used to encrypt data on multiple hosts. This makes sharing encrypted files between multiple enclaves on different hosts more complex. The Anjuna Policy Manager addresses this problem by securely delivering the encryption keys to authorized enclaves. See Policy Manager Reference for more information.

Example:

policy_manager:
  socket: apm-broker
  url: https:://apm-server.test:8201
  ca_cert: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
attested_files

This optional entry is used to generate an attested file for some of the files that the application in the enclave writes. For each file listed under the attested_files: option - a single file is generated, and it contains a file header and the actual content that the application wrote. The attested file can then be verified by the receiving end to prove that this file was created by a specific trusted enclave, before using the content of that file. Attested files are described in detail on the anjuna-check-attestation documentation page.

Example:

attested_files:
  - path: python3.py

Applications may specify the same file as both attested and encrypted to attest encrypted files. In this case, the cleartext content is encrypted and then attested:

Example:

attested_files:
  - path: attested-encrypted-private.bin
encrypted_files:
  - path: attested-encrypted-private.bin
  ...
You can read more about the encrypted_files option below.


command_arguments
command_arguments:
- command_name
- first_parameter
...
- nth_parameter

An optional entry to fix the command-line parameters passed to the executable. When used, anjuna-runtime does not allow parameters to be passed to the executable on the command line and instead uses the manifest values. Each command line parameter must be specified on a different line. For example, to execute the command openssl genrsa -out private_key.pem, specify the following configuration:

Example:

command_arguments:
- openssl
- genrsa
- -out
- private_key.pem
disable_avx

Disable AVX (Advanced Vector Extensions) support. This option should be set to needed if the CPU does not support the AVX instruction set extensions. The default value is false. This value affects the enclave signature and is always present in the compiled manifest file.

enclave_size

Integer specifying the enclave size (which must be a power of 2). Default is 256 MB. Capital suffixes M, and G can be added.The minimal valid value for this setting is 128M.

encrypted_files
encrypted_files:
  - path: testfile_sgx_encrypted.txt
    key: secret_sgx_key_id

One or more entries, each specifying a pathname and a key. Each entry identifies a file that the Anjuna SGX Runtime is to store encrypted, rendering it unreadable to processes outside the secure enclave. The Anjuna SGX Runtime automatically encrypts the listed files, stores them encrypted, and decrypts them inside the secure enclave as-needed.

Files not listed in the encrypted_files section of the manifest are not encrypted by the Anjuna SGX Runtime.

Each path given must match the pathname that the protected application uses to find the file. A path may be either absolute or relative, but if the application uses an absolute path to find the file, then the path should be absolute in the manifest; if the application uses a relative path, then it should be relative in the manifest.

You can use simple wildcard characters to match several files in a common path. If, for example, your application frob requires access to three files named foo.frob, bard.frob, and baz.frob in the directory /opt/quux, then you can specify them in the following way:

Example:

encrypted_files:
  - path: /opt/quux/*.frob
    key: frob_key_id

The character '?' matches any single character; the character '*' matches any number of characters of any kind.

environment
environment:
- name: VAR1_NAME
  value: VAR1_VALUE
- name: VAR2_NAME
  value: VAR2_VALUE

Defines or overwrites one or more environment variables. Any security sensitive environment variable that the application uses should be fixed in this file where it will become part of the enclave signature. If you need spaces in an environment variable value, just surround the value with quotes according to normal YAML rules.

LD_LIBRARY_PATH is a special environment variable. We recommend, at least initially, that you do not set it in your manifest template file. When not set in the template file, anjuna-compile-manifest will create it for you. We place Anjuna’s Runtime folder first in the generated LD_LIBRARY_PATH so that your program uses our enclave-optimized version of glibc. anjuna-compile-manifest will also place any other path needed that ldd reports when run on the executable.

For example, on a typical Linux system, the LD_LIBRARY_PATH would look like this:

environment:
- name: LD_LIBRARY_PATH
  value: Runtime:/lib/x86_64-linux-gnu
is_production

Set this boolean value to true for a release enclave that can not be debugged. The default value is false. This value affects the enclave signature and will always be in the compiled manifest file.

isv_prod_id

Intel® SGX ISVPRODID value. The value must be an integer between 0 and 65535. Default value is 0.

isv_svn

Intel® SGX ISVSVN value. The value must be an integer between 0 and 65535. Default value is 0.

keys
keys:
- id:       secret_sgx_key
  source:   hardware
  bindings:
  - VENDOR_IDENTITY
  - ENCLAVE_IDENTITY

- id:       user_rsa_key
  source:   RSA
  value: |
  -----BEGIN PUBLIC KEY-----
  contents of public.pem file generated in Step #2
  -----END PUBLIC KEY-----

  - id:       secret_enclave_key
    source:   enclave_generated

  - id:       secret_server_key
    source:   key_server
    uri:      anjuna://keys/database_key

Each entry in the keys field identifies a cryptographic key that the Anjuna SGX Runtime can use to secure data. There are four types of values that are valid for entries in this field:

  • A hardware key is generated by the Intel® SGX hardware of the host.

  • An RSA key is supplied literally, inline in the manifest template file.

  • An enclave_generated key is a public key automatically generated by the Anjuna SGX Runtime for the enclave; the corresponding private key is generated inside the enclave and never leaves it.

  • A key_server key is obtained from a key-management server.

    The bindings field, used when the source field’s value is hardware, controls the hardware flags used to automatically derive a key for the configuration. For example, the VENDOR_IDENTITY value shown in the example enables the MRSIGNER feature, and the VENDOR_ENCLAVE enables the MRENCLAVE feature.

    For RSA keys, when inserting a multiline PEM key into a YAML file, insert a pipe character ("|") after the colon (":") and indent all of the individual lines of the key by the same amount.

    For example:

    - id:       user_rsa_key
  source:   RSA
  value: |
  -----BEGIN PUBLIC KEY-----
  contents of public.pem file generated in Step #2
  -----END PUBLIC KEY-----
log_level

Specifies whether runtime debug information should be printed.

  • debug print lots of additional information including system call tracing.

  • error only reports severe errors.

The default value is error. We expect to support intermediate logging levels in the future.

logger_type

Specifies which logger to use:

  • stream print log messages to standard output.

  • stderr print log messages to standard error.

  • syslog output log messages to syslog.

  • remote_syslog send log messages to remote syslog server. Requires specifying syslog_server_ip and syslog_server_port.

num_threads

The maximum number of threads that the enclave executable will use. Must be an integer between 1 and 64. Default is 4.

syslog_server_ip

Specifies the IP address of a remote syslog server. Required when logger_type is remote_syslog.

syslog_server_port

Specifies the port on which a remote syslog server is listening. Required when logger_type is remote_syslog.

trusted_files

A list of files that are measured.

trusted_files:
- /path/to/file1
- relative/path/to/file2
  ..

These are files that get a SHA256 hash taken and are placed in the compiled manifest under a new entry named trusted_hashes which include a sha256 hash. The example above would get compiled to:

trusted_hashes:
- path: /path/to/file1
  hash: sha256-hash-of-1st-entry
- path: relative/path/to/file2
  hash: sha256-hash-of-2nd-entry

If, at runtime, one of these files is opened and the SHA256 hash does not match, the open syscall will fail and return an error set to EACCESS.

trusted_libs

trusted_libs is the same as trusted_files, but every entry must be a shared library or other ELF file. When an entry is added to trusted_libs, both the entry and all shared library dependencies of that entry will be locked to a specific SHA256 hash. This is useful for shared libraries that are not compiled in to an executable. For example, to load a shared library needed to interact with an HSM via a PKCS#11 API:

trusted_libs:
  - /usr/lunasa/lib/libCryptoki2.so
tls_encrypted_ports

Provides automatic TLS termination for the TCP connections. This option is useful when the user application listens for incoming connections on a predetermined port number.

Refer to TLS Termination Specifications and Limitations to see the specifications and limitations of the Anjuna Runtime support for the automatic TLS termination.

The different attributes are -

  • server_ports a list of ports that will be automatically protected with TLS. We can specify multiple ports, and port ranges separated by a colon.

  • source specifies where the TLS credentials (certificate and private key) come from. Currently, only a single value is supported - "inline", which indicates that the certificate(s) and private key are specified in this manifest file itself.

  • certificate that will be advertised to the TLS clients in PEM format.

  • ca_certificate an optional Certificate Authority (CA) certificate chain that can be used by TLS clients to verify the server certificate mentioned above.

  • private_key_file_path refers to the (encrypted) file containing the private key corresponding to the public key contained in the server certificate. It can be an absolute path or a path relative to the starting path of the Anjuna SGX Runtime.

The TLS private key specified by the attribute private_key_file_path must be encrypted to ensure that it is not accessible to any applications other than the enclave.

You can encrypt the TLS private key using the anjuna-encrypt tool after using the --provision command line option with the Anjuna SGX Runtime (see anjuna-sgxrun).

For example:

tls_encrypted_ports:
  - server_ports:
    - 8080           # single port
    - 9000:9100      # port range
    source: inline
    certificate: |
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----
    ca_certificate: |
      -----BEGIN CERTIFICATE-----
      [intermediate CA certificate(s)]
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      [root certificate]
      -----END CERTIFICATE-----
    private_key_file_path: /path/to/private/key/file