User's Guide: Add and Edit an Application

1.0 Introduction

A Fortanix Confidential Computing Manager (CCM) Application is a program or service that is being protected with Runtime Encryption. In a microservice architecture, you might create an application in CCM for each of your microservices.

Since the code for an application is typically updated over time, an application definition in CCM is not associated with a particular enclave hash (MRENCLAVE). Instead, an application can be associated with one or more images, each of which represents a specific version of the application. MRENCLAVE values are associated with images.

The application record in Fortanix CCM defines general characteristics for the application including the domain name(s) assigned to the application and, if the application is using Enclave OS, the parameters to use when processing the application in the Enclave OS converter. In the future, CCM will allow defining policies indicating where the application can run and what other applications and data stores it can communicate with.

2.0 Prerequisites

Ensure the following:

• A group must be created. For more information, refer to the User’s Guide: Create a Group.

• Name of the input docker image of this application from the input registry.

• Output image location.

3.0 Add an Application

You can convert, deploy, and approve your application all at the same time using Fortanix CCM.

Perform the following steps to add an application:

1. Navigate to the Applications menu item from the CCM UI left navigation panel.

2. On the Applications page, click + ADD APPLICATION to add a new application.  

   

3. There are three types of applications that you can add:

   1. Add Enclave OS Application

   2. Add EDP Application

   3. Add ACI Application

4.0 Add Enclave OS Application

In the Enclave OS application form, add a Flask Server Application. Fill in the following relevant details and click the CREATE button. You can use Fortanix's docker registry for the sample app. 

App: fortanix/python-flask

Optional: You can run the app with the following command:

sudo docker run fortanix/python-flask

NOTE

It is recommended to use your private docker registry to keep the output image.

Perform the following steps:

1. In the Application form, fill in the following relevant details:

   1. Application name: Enter the name of the application.

   2. Description (optional): Enter the application’s description.

   3. Input image name: Enter the full path of the current application’s current docker image.

   4. Output image name: Enter the application's converted application name.

   5. Group: Select the required group name from the drop down menu to associate the application with that Group. 

   6. Add Labels: To control which applications are allowed to run on which nodes, you need to add Labels for applications and nodes in the form of “Key:Value” pairs. Refer to Application and Compute Node Policy Enforcement for more details.

      • Suggested Labels: This field will show the top 10 labels that are frequently used by users of an account.

      • Add Labels: Enter the Key and Value pair and click the ADD LABEL button to save the label. The newly created label will appear in the Labels Added field. You can also select an existing label from the Suggested Labels field.
        Example of a “Key:Value” pairs is – “Location:Location_name” where “ 
        Location” is the Key and “Location_name” is the Value of the key such as “South UK”.

        NOTE

        • A label's key and value can have a maximum of 256 characters and is case-sensitive.

        • Some keys are reserved for internal use which are called system-defined labels.

          • Such as: 'Fortanix', 'fortanix', ‘CCM’, ‘ccm’, confidentialcomputingmanager. Or

          • {Fortanix|Fortanix|CCM|ccm|confidentialcomputingmanager| Confidentialcomputingmanager}}<Any_Non-Alphanumeric-Char><Any-Char>.

        • Adding labels for applications is not mandatory, even without labels applications can still run on the nodes. But if you are adding labels for an application then it is mandatory to add the same labels on the node on which the application will run.

        • A node can have multiple labels that belong to different applications. For example:
          App1’s label => Location1: Value1
          App2’s label => Location2: Value2
          Then the Node can have labels => Location1: Value1 , Location2: Value2.

   7. Platform Configuration: Fortanix CCM allows you to run your confidential computing workloads on the AWS Nitro Enclaves platform.

      • Memory size – Select the memory size from the drop down to change the memory size of the enclave. 

      • CPU count – Enter the number of vCPUs to allocate to the enclave. The number of vCPUs that you can allocate to an enclave depends on the size and configuration of the parent instance. If the parent instance is enabled for multithreading, you must leave at least 2 vCPUs for the parent instance. If multithreading is not enabled, you must leave at least 1 vCPU for the parent instance. For example, if your parent instance has 4 vCPUs and it is enabled for multithreading, you can allocate up to 2 vCPUs to the enclave.

      • File persistence – This option is selected by default. This feature allows you to save the filesystem changes to an encrypted container mount. It allows the Nitro system to access a managed Security-object in Fortanix DSM to be able to encrypt and decrypt the Linux Unified Key Setup (LUKS) overlay file system. For more details, refer to User’s Guide: AWS Nitro File Persistence.

        NOTE

        For the File Persistence feature to work, you must configure the app certificate as described below, 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.

   8. Certificate Configuration: Add any certificate using the ADD A CERTIFICATE. A converted application can request a certificate from the Fortanix Confidential Computing Manager when your application is started. The certificates are signed by the Fortanix Confidential Computing Manager Certificate Authority, which issues certificates only to enclaves presenting a valid attestation.

      • Domain – Enter the allowed domain for the application. This is the domain that appears in the TLS certificate issued by the Fortanix Confidential Computing Manager.

      • Key path – Enter the key path that will be accessible by the application.

      • Key type – Select the type of key from the drop down menu that you want to generate.

      • Certificate path – Enter the certificate path that will be accessible by the application.

      • RSA Key Size – Select the size of the RSA keys in bits from the drop down menu.

      • Chain path (optional) – Enter the chain path for the complete certificate chain.

   9. Edit any ADVANCED SETTINGS that you might want to change.

      • Environment variables – Enter any environment variables that will be set at runtime. The variables need to be comma separated values.

      • Encrypted directories - Enter comma separated absolute paths of file system directories that should be encrypted by the application. Data written to these directories will be transparently encrypted and decrypted using Fortanix DSM-managed keys. Use this option to protect sensitive data at rest.

      • Read/Write directories - Enter comma separated absolute paths of file system directories to allow read/write by the application, without encryption or integrity protection. Use this only if you understand the security implications. For more information, refer to Section 4.1: Directory Protection for Enclave OS Applications.

      • Java runtime – Select the appropriate Java runtime values. When you select the Java Runtime option for an application, the converted docker image will run with the specified options for the chosen JVM (Java Virtual Machine).

        OPENJDK / ORACLE - 
        -XX:CompressedClassSpaceSize=16m
        -XX:-UsePerfData 
        -XX:ReservedCodeCacheSize=16m 
        -XX:-UseCompiler 
        -XX:+UseSerialGC
        OPENJ9 / LIBERTY - 
        -Xnojit
        -Xnoaot
        -Xdump:none

      • CA Cert path – Enter the path to store the Fortanix Confidential Computing Manager CA certificate.

      As an optional step, you can install the CA certificate in the system trust store where all the certificates are stored. The following are the three options given:

      • Yes, install and continue image conversion even if the installation fails – select this option if you want to convert the image even after the CA Certificate installation fails.

      • Yes, install and fail image conversion if the installation fails – select this option if you want to stop image conversion after the CA Certificate installation fails.

      • No, do not install – select this option if you do not want to install the CA Certificate.

      

2. Click SAVE to configure the image. The application will now be deployed and added to your approval and visible in the APPLICATION tab. You can approve the approval request in the Tasks tab.  

   NOTE

   • Creating an application does not mean that a Nitro Ready Image is created and pushed. An application will be converted and pushed to the specified location once an image of this application is created.

   • It is also possible to add labels for an Enclave OS application from the detailed view of an application.

   

   For more information on how to create an image for the Enclave OS application, refer to the User's Guide: Create an Image.

4.1 Enclave OS Directory/Filesystem Protections

Enclave OS provides file system integrity protection. There are three possible directory configurations within an Enclave:       

• Read-only (integrity protected, not encrypted, not writable) – This is the default configuration.

• Encrypted (integrity protected, encrypted, but initial contents are unencrypted).

• Read-write (unprotected).

For files in read-only directories, if Enclave OS detects that a file has been modified, it will halt the execution of the Enclave. Enclave OS will ensure that the complete root tree (all directors below "/") have read-only permission, except for the following directories: /etc, /run, /tmp, /opt/fortanix/enclave-os/app-config/rw/, since these directories have read-write permissions. Except for /etc, the other directories are encrypted to prevent potential tampers from outside the Enclave.

Let us examine a typical use case:

An enclaved Python Flask application will load myapp.py file when the enclave starts up. If this file was in a read-only folder and it was modified outside of the enclave, at run-time when the file is loaded by Flask, Enclave OS will detect the tamper and halt execution. If the myapp.py file was in the encrypted folder but modified from outside the enclave, it will detect the tamper and halt execution.

4.2 Edit an Enclave OS Application

Perform the following steps to edit an application after you add it to your list:

1. Navigate to the APPLICATION menu item in the CCM UI left navigation panel.

2. Click the name of the application you want to edit. The application details page opens, displaying configuration settings such as certificates and deployed images.

3. Click EDIT.  

   

4. Modify the required configuration settings.

   NOTE

   Ensure that you understand the impact of changes to advanced settings before proceeding.

5. Click SAVE to apply the changes.  

   NOTE

   • The Application name field cannot be edited.

   • The Allowed domain field is editable only if there are no pending domain approval tasks for the application.

5.0 Add EDP Application

Perform the following steps:

1. In the Application form, fill in the following relevant details:

   1. Application name: Enter the name of the application.

   2. Description (optional): Enter the application’s description.

   3. Group: Select the required group name from the drop down menu to associate the application with that Group.

   4. Add Labels: To control which applications are allowed to run on which nodes, you need to add Labels for applications and nodes in the form of “Key:Value” pairs. For more information, refer to the Application and Compute Node Policy Enforcement.

      • Suggested Labels – This field will show the top 10 labels that are frequently used by users of an account.

      • Add Labels – Enter the Key and Value pair and click the ADD LABEL button to save the label. The newly created label will appear in the Labels Added field. You can also select an existing label from the Suggested Labels field.

        NOTE

        • A label's key and value can have a maximum of 256 characters and is case-sensitive.

        • Some keys are reserved for internal use which are called system-defined labels.

          • Such as: 'Fortanix', 'fortanix', ‘CCM’, ‘ccm’, confidentialcomputingmanager. Or

          • {Fortanix|Fortanix|CCM|ccm|confidentialcomputingmanager|Confidential computingmanager}<Any_Non-Alphanumeric-Char><Any-Char>.

        • Adding labels for applications is not mandatory, even without labels applications can still run on the nodes. But if you are adding labels for an application then it is mandatory to add the same labels on the node on which the application will run.

        • A node can have multiple labels that belong to different applications. For example:
          App1’s label => Location1: Value1
          App2’s label => Location2: Value2
          Then the Node can have labels => Location1: Value1 , Location2: Value2.
          Example of a “Key:Value” pairs is – “Location:Location_name” where “Location” is the Key and “Location_name” is the Value of the key such as “South UK”.

   5. Certificate Configuration: Add any certificate using the ADD A CERTIFICATE. The em-app RUST library can be used by EDP apps to obtain a signed CCM Certificate over enclave-generated certificates. You can select to add multiple certificates using the ADD A CERTIFICATE button.

      • Domain: Enter the allowed domain for the application. This is the domain that appears in the TLS certificate issued by the Fortanix Confidential Computing Manager.

      • Type: Enter the type of certificate to obtain for the application.  

        

2. Click SAVE to configure the application.

   NOTE

   It is also possible to add labels for an application from the detailed view of the EDP application.

   

   For more information on how to create an image for the EDP application, refer to the User's Guide: Create an Image.

5.1 Edit an EDP Application

Perform the following steps to edit an EDP application after you add it to your list.:

1. Navigate to the APPLICATION menu item in the CCM UI left navigation panel.

2. Click the name of the application you want to edit. The application details page opens, displaying configuration settings such as certificates and deployed images.

3. Click EDIT.

   

4. Modify the required configuration settings.

5. Click SAVE.

6.0 Add ACI Application

Perform the following steps:

1. In the Application form, fill in the following relevant details:

   1. Application name: Enter the name of the application.

   2. Description (optional): Enter the application’s description.

   3. Image name: Enter the full path of the current application’s docker image. Ensure that the Image name does not include any container image tag.

   4. Group: Select the required group name from the drop down menu to associate the application with that Group.

   5. Certificate Configuration: Add any certificate using ADD A CERTIFICATE. A converted application can request a certificate from Fortanix CCM when your application is started. The certificates are signed by the Fortanix CCM Certificate Authority, which issues certificates only to enclaves presenting a valid attestation.

      • Domain: Enter the allowed domain for the application. This is the domain that appears in the TLS certificate issued by the Fortanix Confidential Computing Manager.

      • Type: Enter the type of the certificate to obtain for the application.

        

2. Click SAVE to configure the application.

For more information on how to create an image for the ACI application, refer to the User's Guide: Create an Image.

6.1 Edit an ACI Application

Perform the following steps to edit an ACI application after you add it to your list:

1. Navigate to the APPLICATIONS menu item in the CCM UI left navigation panel.

2. Click the name of the application you want to edit. The application details page opens, displaying configuration settings such as certificates and deployed images.

3. Click EDIT.

   

4. Modify the required configuration settings.

5. Click SAVE.

7.0 Setting Environment Variables for your Application

Many applications can be configured by using environment variables such as a container image, a Kubernetes pod specification, or a container entrypoint script. The {site.data.keyword.datashield_short} conversion process transfers any environment variables that are specified by the input container image to a configuration file in the output container, where they are covered by the enclave signature. This freezes the values of the environment variables at conversion time. If variables are supplied after the conversion takes place, they are not seen by the application. Since the variables are not seen, your application is not protected from any maliciously set environment variables at runtime.

By default, the only environment variable passed to the binaries in library OSes is PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin. If the host environment variables specifies a HOSTNAME  then it is also included in the list of default environment variables.

Syntax 1: loader.env.[ENVIRON]=[VALUE]

This syntax specifies the environment variable value that is customized for the enclaves. This syntax can be used multiple times to specify more than one environment variable.

The list of environment variables passed to the binaries in enclaves will include a merged list of default environment variables and environment variables specified with this syntax. If there are any conflicting variables, the default environment variable will be overwritten.

Syntax 2: loader.env.allow_all_env.all = 1

This syntax passes all the host environment variables to the binaries in the enclaves.

The list of environment variables passed to the binaries in enclaves will include a merged list of host environment variables and variables specified with syntax 1. If there are any conflicting variables, the host environment variables will be overwritten with the value specified by syntax 1. For example, if the manifest specifies loader.env.X = Z and the host specifies X=Y then the value of X=Z.

Syntax 3: loader.env.allow_some_env.[ENVIRON] = 1

This syntax specifies the environment variable that will be passed from the host environment variable to the binaries in the enclaves. This syntax can be used multiple times to specify more than one environment variable.

The list of environment variables passed to the binaries in enclaves will include a merged list of a subset of host environment variables as specified by Syntax 3 and variables specified with Syntax 1. If there are any conflicting variables, the host environment variables will be overwritten with the value specified by Syntax 1. For example, if the manifest specifies loader.env.X = Zand the host specifies X=Y then the value of X=Z.