User's Guide: AWS Nitro File Persistence

1.0 Introduction

Welcome to the Fortanix Confidential Computing Manager (CCM) User Guide. This document describes the Nitro Overlay File System Persistence feature in the Fortanix Confidential Computing Manager.

The Fortanix Confidential Computing Manager (CCM) Nitro File Persistence feature provides the encryption keys necessary for the Nitro converter to allow a filesystem to be created, mounted, unmounted, and saved for a Nitro Enclave using the Nitro node agent.

The Nitro File Persistence feature allows you to save the filesystem state of a Nitro Enclave after the enclave has been stopped. Typically, due to the short-lived nature of the Nitro Enclave, all data is lost unless exported. When enabled (ON by default in the CCM UI), this mechanism will allow a user to follow a set of instructions to save the filesystem of a converted container and to restart a container image with the filesystem.

2.0 Enabling Nitro File Persistence

The primary and recommended way of creating a file persistence-enabled Nitro Enclave is using the Fortanix CCM UI as described in Section 2.1: Using the Fortanix CCM UI. The File persistence option can be enabled when creating a Fortanix CCM application (app) and an image.

You can also enable this using the Fortanix CCM REST API as described in Section 2.2: Using the Fortanix CCM REST API.

2.1 Using the Fortanix CCM UI

The File Persistence feature can be enabled in the Fortanix CCM UI by creating a new application or image, selecting the enclave type as AWS Nitro, and making sure the File persistence check box is enabled.

For steps to enable or disable the File persistence option during the CCM App creation workflow, refer to the Users’ Guide: Add and Edit an Application.

For steps to enable or disable the File persistence option during the CCM image creation workflow, refer to the Users’ Guide: Create an Image.

  • The File persistence option is enabled by default in both the CCM app and image creation workflows.
  • If the File persistence option is enabled during the Fortanix CCM app creation workflow and if you disable it during the image creation workflow, then the File Persistence feature is considered as disabled.
  • If the File persistence option is disabled during the Fortanix CCM app creation workflow and if you enable it during the image creation workflow, then the File Persistence feature is considered as enabled.
  • You must configure an application certificate when you create a Fortanix CCM app for the File Persistence feature to work since when a Nitro image runs, it must be configured ahead of time to receive a certificate, which will authorize access to Fortanix DSM to obtain the keys for the Linux Unified Key Setup (LUKS) volume. Without the app certificate, this feature will not work.

2.2 Using the Fortanix CCM REST API

  1. Create a Fortanix CCM image (standalone conversion) using the CCM REST API and register the image as a build using the following endpoint:
    POST /v1/builds/convert-app/nitro-enclaves
  2. Pass the CreateBuildRequest object as data in the above request as shown below.
    {"request":{"app_id":"<App ID>","input_image":{"name":"nginx:stable"},"output_image":{"name":"<input_image_path:input_tag>","auth_config":{"username":"<username>","password":"<password>"}},"converter_options":{"certificates":[{"issuer":"MANAGER_CA","subject":"","keyType":"RSA","keyParam":{"size":2048},"keyPath":"/run/key.pem","certPath":"/run/cert.pem","chainPath":""}]}},"nitro_enclaves_options":{"cpu_count":2,"mem_size":1024,"enable_overlay_filesystem_persistence":true}}
  3. The above request will have an enable_overlay_filesystem_persistence field. This field will default to false if not present, but you can provide a value of true to enable the Nitro File Persistence for this Image.
    • The above steps should only be used for Nitro images.
    • The converter API to create the Docker container for this build must also be called with the correct flag to enable Nitro File Persistence. An image converted without this parameter will not function with Nitro File Persistence.

3.0 Creating a Persistence Blockfile

If the Nitro File Persistence feature is enabled for each running instance of a Fortanix CCM image container, it will create a LUKS2 blockfile for use with this system.

3.1 Automatic Creation

  1. To create a File Persistence blockfile, run the container with the docker run command as shown below.
    docker run -it --privileged -v /run/nitro_enclaves:/run/nitro_enclaves -e RUST_LOG=debug -e NODE_AGENT=http://<NODE_AGENT_IP>:9092/v1/ -p 8081:80 -p 6061:443 <container_name>
  2. Subsequently, after the container stops or is stopped with the docker stop, it will be possible to extract the blockfile for later use with the following command.
    docker cp <container_name>:/opt/fortanix/enclave-os/Blockfile-rw.ext4 <destination_filename>
    The File Persistence blockfile will be created by Nitro when the Fortanix CCM application is created. Use the docker cp command to extract the file as shown in step 2 above.

4.0 Using the File Persistence Blockfile

After the Nitro Persistence File is obtained, it must also be mounted into a container for use. This will allow a container to start with the same filesystem state as it had during the shutdown.

4.1 Mounting

To use the Nitro Persistence File, it must be mounted during normal container startup with the following command:

docker run -it --privileged -v /run/nitro_enclaves:/run/nitro_enclaves -v <path_to_persistence_file>:/opt/fortanix/enclave-os/Blockfile-rw.ext4 -e RUST_LOG=debug -e NODE_AGENT=http://<NODE_AGENT_IP>:9092/v1/ -p 8081:80 -p 6061:443 <container_name>
  • The destination filepath must be the same as in the command above; otherwise, the system will not work.
  • After the Nitro Persistence File is mounted, the Nitro startup processes will check it for compatibility and replace it with new data if necessary. So, if they are mounted to the incorrect version of the build, it will result in the destruction of data. The LUKS volumes mounted that do not have special Fortanix header formatting will be overwritten.
  • Since the Nitro Persistence blockfile is a special instance of a LUKS volume, a user cannot directly mount and decrypt it. These blockfiles can only be opened by Fortanix Nitro images.
  • Different versions of application images cannot mount each other's volumes; there is no migration between versions. Any migration would have to take place at runtime, over a network connection, between a newer and older build number of an image.
  • The system, at present, is implemented using an overlay filesystem. This overlay is placed on top of the base container image.
  • Due to the use of an overlay, all files in the system will be saved, including logs and other files created by the normal operating environment.
  • These blockfiles are regular files, so they can be copied and moved as required, and copies can be run on any instance of the same Image build version.


Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful