User's Guide: Add and Edit an Application

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.

Because 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 CCM defines general characteristics for the application including the domain name(s) assigned to the application and, if the application is using EnclaveOS, the parameters to use when processing the application in the EnclaveOS 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.

Prerequisites

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

Steps to Add an Application

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

  1. Sign in to the Fortanix CCM, and then click the Management Console tab.
  2. On the Applications page, click + ADD APPLICATION to add a new application.  CCMAppNewA.pngFigure 1: Add new application
  3. There are two types of applications that you can add:
    1. Add EDP Application
    2. Add Enclave OS Application

Add Enclave OS Application

EOS1.png

                                                       Figure 2: Add Enclave OS application

  1. In the Enclave OS application form, we will add a Flask Server Application. Fill in the relevant details as shown below, and click NEXT. You can use Fortanix's docker registry for the sample app. 
  2. In the Add application form (Figure 3), fill all the required fields (Application name, Input image name, Output image name, ISVPRODID, ISVSVN, Memory Size, Thread Count).
    1. The Application name is the name of the application.
    2. Description (optional) – Enter the application’s description
    3. The Input image name is your current application’s current docker image.
    4. The Output image name is where you can find the converted application.

      Enclave Parameters
    5. ISVPRODID is a numeric product identifier. A user must choose a unique value in the range of 0-65535 for their applications.
    6. ISVSVN is a numeric security version to be assigned to the Enclave. This number should be incremented if a security-relevant change is made to the application.
    7. Memory size – Choose the memory size from the drop-down to change the memory size of the enclave.
    8. Thread count – Change the thread count to support the application.
      Add Labels

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

    9. Suggested Labels – This field will show the top 10 labels that are frequently used by users of an account.
    10. Add Labels – Enter the Key and Value pair and click the LABEL button to save the label. The newly created label will appear in the Labels Added field. A user can also choose 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 is 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 application is not mandatory, even without labels applications can still run on the nodes. But if we 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.
      CCMAppNew1a.png
      CCMUserguide8.pngCCMUserguide9.png Figure 3: Application details

    Certificate Configuration
    Add any certificate using the App Certificate configuration section. 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(s) for the application. These are domains that appear in the TLS certificates issued by the Fortanix CCM. You can add multiple domains separated by a comma.
    • Key path – Enter the key path that will be accessible by the application.
    • Certificate path – Enter the certificate path that will be accessible by the application.
    • Chain path – Enter the chain path for the complete certificate chain.
      NOTE
      The user will be able to either add the Certificate Path or the Chain Path, not both.
      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.
    • 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.
    • 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 CCM CA certificate.
       
      As an optional step, the user can install the CA certificate in the system trust store where all the certificates are stored. 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.
  3. Click NEXT to create the application (Figure 3). The application will now be deployed and added to your approval and visible in the APPLICATION tab (Figure 4). You can approve the image creation request in the Tasks tab. CCMAppNew2a.png
    Figure 4: Application created
    NOTE
    • Creating an application does not mean that an SGX 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.
    CCMAppNew3a.png
    Figure 5: Add Labels

Refer to User's Guide: Create an Image to create an image for the Enclave OS application.

Steps to Edit an Enclave OS Application

You can edit an application after you add it to your list.

  1. Sign in to Fortanix CCM, and then navigate to the APPLICATION tab in the Management Console.
  2. Click the name of the application that you want to edit. A new screen opens where you can review and edit the configuration including certificates and deployed images.
  3. Click EDIT APPLICATION. CCMAppNew4a.png
    Figure 6: Edit application
  4. Update the configuration that you want to make. Be sure that you understand the way that changing the advanced settings affects your application before you make any change.
  5. Click UPDATE CCMAppNew5.pngCCMUserguide5.pngCCMUserguide6.png
    Figure 7: Update application
    NOTE
    • The Application name cannot be edited.
    • Allowed domain(s) can only be edited if the application does not have any pending domain approval task.

Add EDP Application

EDP1.png

Figure 8: Add EDP application

  1. In the EDP Add application form, fill the relevant details such as the Application name and Description (optional).
  2. Add Labels: To control which applications are allowed to run on which nodes, we add Labels for applications and nodes in the form of “Key:Value” pairs. Refer to Application and Compute Node Policy Enforcement for more details.
    1. Suggested Labels – This field will show the top 10 labels that are frequently used by users of an account.
    2. Add Labels – Enter the Key and Value pair and click the LABEL button to save the label. The newly created label will appear in the Labels Added field. A user can also choose 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 is 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 application is not mandatory, even without labels applications can still run on the nodes. But if we 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.
  3. Certificate Configuration
    Add any certificate using the Certificate configuration section. The em-app RUST library can be used by EDP apps to obtain a signed EM Certificate over enclave generated certificates.  CCMAppNew6.pngCCMUserguide11a.png
    Figure 9: Add EDP application details
  4. Enter the certificate Domain. You can choose to add multiple certificates using the ADD A CERTIFICATE button. Once you configure all the certificates, click NEXT to configure the image.
    NOTE

    It is also possible to add labels for an application from the detailed view of the EDP application.
    CCMAppNew7.png
    Figure 10: Add Labels
  5. Refer to User's Guide: Create an Image to create an image for the EDP application.

Steps to Edit an EDP Application

You can edit an EDP application after you add it to your list.

  1. Sign in to Fortanix CCM, and then navigate to the APPLICATION tab in Fortanix CCM UI.
  2. Click the name of the application that you want to edit. A new screen opens where you can review and edit the configuration including certificates. CCMAppNew8.png
    Figure 11: Edit application
  3. Click EDIT APPLICATION. CCMAppNew9.png
    Figure 12: Edit application
  4. Update the configuration that you want to make. 
  5. Click UPDATE. CCMAppNew10.png
    Figure 13: Update application

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.

NOTE
Syntax 2 overrides Syntax 3, so it is recommended to use one or the other of these, not both, in the manifest file.
Was this article helpful?
0 out of 0 found this helpful