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.

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":"fortanix.com","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.
   
   NOTE

   • 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>

   NOTE

   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>