User's Guide: Convert Applications - (Deprecated)

Convert your Applications

You can convert your images to run in an EnclaveOS® environment by using the Fortanix SGX Container Converter. After your images are converted, you can deploy them on your SGX capable cluster.

Using SGX Converter Tool

The SGX Container Conversion tool modifies your existing Docker containers to run in the Fortanix Enclave Manager environment. The converter pulls your existing image, converts the Application, and pushes the resulting image to the specified location. After your images are converted, you can deploy them to your SGX capable workload container.

Before you begin:

Before you convert your applications, you should ensure that you fully understand the following considerations:

• For security reasons, secrets must be provided at runtime - not placed in the container image that you want to convert. When an app is converted and running, you can verify through attestation that the application is running in an enclave before you provide any secrets.
• Testing container environments include the following:
  • Debian 8
  • Debian 9
  • Ubuntu 16.04
  • Ubuntu 18.04
  • Ubuntu 20.04
  • Java OpenJDK 8
  • Java OpenJ9 0.14

Prerequisites:

• Input image and Output image for conversion.

Steps:                       

1. Click the Tools tab in the Fortanix Enclave Manager UI. 
2. Click CONVERT AN APPLICATION.
   Figure 1: Convert an Application
3. In the SGX container conversion form, fill all the required fields:
   • Source image
   • Output Image Enclave thread count

   Fill the optional field:

   • Enclave memory
4. Enter the REGISTRY CREDENTIALS for Source image and Output image. The Registry Credentials are the credentials to access the private docker registry from which an image is going to be pulled or pushed.
   • If you have added these registry credentials through the Settings page, then the check box Use saved credentials will be selected by default and the registry name will be filled automatically for the Add Registry Credentials fields.
     Figure 2: Convert an Application
   • If you have not saved any Registry Credentials in the Settings page of Fortanix CCM, then manually enter the registry credentials for Output Image.
     Figure 3: Convert an Application
5. Click the Convert button to convert the image.
6. Once the image is converted, it will show up in the Output Image Path that you provided.

Converting Java Applications

When you convert Java-based applications, there are a few extra requirements and limitations. When you convert Java applications using the Fortanix Enclave Manager UI, you can select Java-Mode. To convert Java apps by using the API, keep the following limitations and options in mind.

Limitations:

• The recommended maximum enclave size for Java apps is 4 GB. Larger enclaves might work but can experience degraded performance.
• The recommended heap size is less than the enclave size. We recommend removing any -Xmx option to decrease the heap size.
• The following Java libraries have been tested:
  • MySQL Java Connector
  • Crypto (JCA)
  • Messaging (JMS)
  • Hibernate (JPA)

Options:

To use the Java-Mode conversion, modify your Docker file to supply the following options. In order for the Java conversion to work, you must set all of the variables as they are defined in this section.

• Set the environment variable MALLOC_ARENA_MAX equal to 1.

  MALLOC_ARENA_MAX=1

• If you are using the OpenJDK JVM, set the following options.

  -XX:CompressedClassSpaceSize=16m
  -XX:-UsePerfData 
  -XX:ReservedCodeCacheSize=16m 
  -XX:-UseCompiler 
  -XX:+UseSerialGC

• If you are using the OpenJ9 JVM, set the following options.

  -Xnojit
  –Xnoaot