1.0 Introduction

Developers can now bring Intel SGX applications developed using Fortanix EDP to Fortanix Confidential Computing Manager (CCM).

Applications can obtain a certificate signed by Fortanix CCM that confirms that the application:

is part of the CCM account,
is running correctly within an Intel SGX enclave,
has approved attributes specified in the CCM config (MRENCLAVE/MRSIGNER/ISVPRODID/ISVSVN),
and has an approved certificate domain name.

2.0 User Guide

2.1 Creating an Application Using Fortanix EDP

The application consists of 3 parts:

Environment
Source Code
Cargo

2.1.1 Environment

Currently, mbedtls requires Ubuntu 16.04 or Ubuntu 20.04 and the following dependencies -

apt-get update
apt-get install -y wget curl build-essential g++ clang pkg-config libssl-dev protobuf-compiler libclang-dev cmake jq

For the rest of the development environment, refer to the Installation guide.

2.1.2 Source Code

Github open source link for em-app is: https://github.com/fortanix/rust-sgx.The em-app RUST library can be used by EDP apps to obtain a signed CCM Certificate. The following code is used to sign an 'enclave' generated certificate:

use em_app::*;
...
 let node_agent_url = "http://localhost:9092";
 match get_fortanix_em_certificate(node_agent_url, "name", &mut key) {
...

Where node_agent_url must point to the node agent running on the same hardware; otherwise, attestation will fail.

To use the API without exposing the private key, the following trait is available:

/// Operations needed on any input key pair. This is already implemented for mbedtls::Pk.
pub trait ExternalKey {
    fn get_public_key_der(&mut self) -> Result<Vec<u8>>;
    fn sign_sha256(&mut self, input: &[u8]) -> Result<Vec<u8>>;
}

This is implemented for mbedtls::Pk and allows for the implementation of any specific flow. The following code generates a public/private key pair within SGX enclave and gets a signed certificate from Fortanix CCM.

let mut rng = Rdrand;
let mut key = Pk::generate_rsa(&mut rng, 3072, 0x10001).unwrap();

let node_agent_url = "http://localhost:9092";
 
// Call to library to fetch certificates
match get_fortanix_em_certificate(node_agent_url, "name", &mut key) {
    Ok(result) => println!("{}", serde_json::to_string_pretty(&result.certificate_response).unwrap()),
    Err(e) => println!("Error: {}", e),
}

This allows the key to be kept private within the enclave and even hides it from the Fortanix library as well.
Following is the complete example:

/* Copyright (c) Fortanix, Inc. 
 * 
 * This Source Code Form is subject to the terms of the Mozilla Public 
 * License, v. 2.0. If a copy of the MPL was not distributed with this 
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/* Copyright (c) Fortanix, Inc. */
 
/* Usage example for certificate library. This obtains an EM signed certificate if everything is configured correctly.*/
extern crate mbedtls;
extern crate em_app;
 
use mbedtls::pk::Pk;
use mbedtls::rng::Rdrand;
 
use em_app::*;
use std::env;
 
fn main() -> Result<(), String> {
 // Running in SGX - need to manually enable backtrace so we get nice warnings - this should disappear in production environment 
   env::set_var("RUST_BACKTRACE", "1");
 
   // Generate key - mbedtls::Pk has required trait implemented - customers may choose any other mechanism to create certificates 
   let mut rng = Rdrand;
   let mut key = Pk::generate_rsa(&mut rng, 3072, 0x10001).unwrap();
 
   // This must be on localhost otherwise local attestation will not work
   let node_agent_url = "http://localhost:9092";
 
   // Call to library to fetch certificates 
   match get_fortanix_em_certificate(node_agent_url, "name", &mut key) {
       Ok(result) => println!("{}", serde_json::to_string_pretty(&result.certificate_response).unwrap()),
       Err(e) => println!("Error: {}", e),
   }
 
   Ok(())
}

The above example would generate the following results on an application enrolled and whitelisted in Fortanix CCM :

{
  "task_id": "42edb41c-cf09-4102-a8a4-aaa39174aa3d",
  "task_status": "SUCCESS",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIEKTCCApGgAwIBAgIUO08hoEHGblBISTQD0vS2H0uC5c0wDQYJKoZIhvcNAQEL\nBQAwJDEiMCAGA1UEAwwZRGVmYXVsdCBFbmNsYXZlIFpvbmUgUm9vdDAeFw0yMDA2\nMDUxNDAzNTZaFw0yMDA5MDMxNDAzNTZaMBYxFDASBgNVBAMMC2V4YW1wbGUuY29t\nMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEApXf+0coxctXYUkAr/6/X\nhVEbtDjAIgFapGg9cZhv9ZShGtnTsthe8H6OJEwwrNYW10EZyscAOi8d08QxagPv\nu0DvNzy1ro3D53Oc3orLPSTGixkZAOLFcM7bSW3XBYyrTyI7+Sh0x4tKlW+LTSVD\ndZ7tfuPQJjbqCeAom+5FzkB9eaquH7EnTL41lMSSNzl++7if8f7YHxVRc1Fw2wAh\nWOjlqrRjl9UZ0RO4W0iq3xnjwgNqJbDHIbxWpEB2iKU/9UIkIb7y9rmQQ9EQMMeG\n5zZ+TxbotYfEDAS0tQL70h0YuTEVgphua7CGXABS0fgy+wi1bdnaWgrz+K4nRZrM\nzlVT2k4bp2oRINYLrNQ2n0NWjHxc7Fvn/ujOT/MFAMTuvXjS9OOchFU+cpaXn5tJ\nPOhXuEqvh6j8E3VxMJESrgQnLLcQ9WLlx4ZZrzZMYGGfdH1VAUnrjzeEXiZx//T1\nff9rzjDWp7IZTJZTow3w/5iqcS5ZjsdjYyf5xEPBEHoBAgMBAAGjYTBfMAwGA1Ud\nEwEB/wQCMAAwDwYDVR0PAQH/BAUDAwegADAfBgNVHSMEGDAWgBSkw/SjpHtZ2N8r\ncWe3uQzgvZFJRDAdBgNVHQ4EFgQUVj95X/7jElFkMXd7Q3ifvUYVoU4wDQYJKoZI\nhvcNAQELBQADggGBADs2KgAfIzo2Bj0EFK9gqiksmwmfgNf5zl1RGKcQvSn2SM5d\nrzJcgoHYHJLSvw0af04VLJ9U+x5Pd/WSIFfhQ9F++J2d1jlQBkON3Ke/0l98Y0e2\nWetvTekp4xheHJ42M0GsdGJNJMfrL+c+s7zZgeBRZLi9l0lYPmVmh/cF4W+xc495\n8fx5hTSEUfZ6WuHjK8QeMqdiKy+nck8ON2AgRNa7GeW5ilYo8lUFREC1k62unir2\nA6VY/T6FUC0/9AT4rCFUi+kfzkaYcStGGfz8fTiXRzJVk3WGFfqNVmY8Nkf5aFZt\nrDG9f+1Eet6Xyqn+rFkhqdIBHfhKhxqdcfhL66Y2UTvAchWnJ9g8qSHmCozWKD2/\nau2SIvKtOtVnMI7GgoDz+gnuwrE0up+GzEtvAzU5JeoPsvzp38UsyPtZ4RJol1cn\nS9CfD5wRL1YcjSO0kJkhwLvGXiTVwnOzJaQTY70wXrWIaTEhfHmd2wYP9ZxNqvnV\nIEVn5z3tmAUFN71oVg==\n-----END CERTIFICATE-----\n"
}

2.1.3 Cargo File

A cargo file is needed to import the Fortanix CCM certificate library.

[workspace]
 
[package]
name = "get-certificate"
version = "0.1.0"
authors = ["fortanix.com"]
edition = "2018"
 
[dependencies]
em-app = { path = "../../" }
mbedtls = {version="0.5", default-features = false, features = ["sgx"]}
serde_json = "1.0"

Where, em-app = { path = "../../" } is the certificate library. You can replace this with your own library path as required.

2.2 Building the SGX Application

Step 1: Build the application

cargo build --target=x86_64-fortanix-unknown-sgx

Step 2: Package the generated ELF application into an SGX format.

cd target/x86_64-fortanix-unknown-sgx/debug/
ftxsgx-elf2sgxs ./get-certificate --heap-size 409600 --stack-size 409600 --threads 1

NOTE
Replace heap-size, stack-size, and threads parameters with values relevant for your application.

Step 3: Sign the application (for testing, creating a random cert).
Signing the application generates a signature structure (sigstruct) for the application enclave. The sigstruct.bin is used to register the enclave with CCM.

openssl genrsa -3 3072 > private.pem
sgxs-sign ./get-certificate.sgxs ./sigstruct.bin --key ./private.pem

NOTE
The example uses a randomly generated key; the expectation here is that you will use a properly secured signing key for production.

2.3 Configuring CCM for EDP Application

To allow an application to obtain a certificate, it requires an approved configuration in CCM with the following requirements:

SGX Application should run on the same machine where a 'CCM Node Agent' also runs.
The Fortanix CCM is configured to allow a certificate for the requested domain and application:
- An account is created.
- The 'CCM Node Agent' running on the machine is associated with this account.
- A group is created.
- An application is created in this account and assigned to the group.
- An image is created in the above application with SGX application attributes.
- The image is whitelisted
- The domain for the image is also whitelisted.
The 'Intel' attestation works for the target machine.

There are many ways to configure Fortanix CCM for EDP applications: automated, manual, and through UI.

2.3.1 Automatic using CCM-CLI

In this method, you can use a script that uses the CCM APIs, which are available at https://www.fortanix.com/api/ccm/.
Script URL: Inside the 'em-app' crate, examples folder https://github.com/fortanix/rust-sgx/tree/master/em-app/examples/get-certificate, there is a 'register_and_run.sh' script that builds and configures the Fortanix CCM and a config file to run the script.

To build, configure, and run the examples, use the following command:

./register_and_run.sh ./config

For this to run, the user needs em-cli, which can be installed using the following command:

cargo install em-cli

The script above with the example in the section "Creating an application using Fortanix EDP" will take care of the following:

Create an account (if not already created).
Select the account.
Create an application (if not already created).
Create an image with EDP application attributes (if not already created).
Whitelist build (if not already whitelisted).
Whitelist domain (if not already whitelisted).

OR

2.3.2 Automatic using CURL

In this method, you can use a script that uses the CCM APIs, which are available at https://www.fortanix.com/api/ccm/.

Script URL: Inside the 'em-app' crate, examples folder, there is an em_curl' script which does everything automatically. This is the same script as CCM-CLI, but it works by overriding CCM_CLI with CURL. https://github.com/fortanix/rust-sgx/blob/master/em-app/examples/scripts/em_curl.sh

Add the following parameters to the config to use CURL instead of CCM-CLI.

curl_override="y"
curl_opts=""

The script above with the example in the section "Creating an application using Fortanix EDP" will take care of the following:

Create an account (if not already created).
Select the account.
Create a group.
Create an application (if not already created).
Create a build with EDP application attributes (if not already created).
Whitelist build (if not already whitelisted).
Whitelist domain (if not already whitelisted).

2.3.3 Manual using CCM-CLI

To configure Fortanix CCM with CCM-CLI, refer to Using CCM-CLI with Fortanix Confidential Computing Manager.

2.3.4 Manual using CURL

To configure Fortanix CCM with CURL APIs, refer to Using Fortanix Confidential Computing Manager to Build an Enclave OS Application from Scratch.

OR

2.3.3 Through UI

Step 1: Sign up and Log in to Confidential Computing Manager

Visit https://ccm.fortanix.com/ and sign up.
After your account is approved by the administrator, log in by entering your email ID and password.
Figure 1: Logging In

Step 2: Create and Select an Account

Once you sign up and log in, you will be taken to the Accounts page. Click ADD ACCOUNT to create a new account.
Enter a name for the new account and optionally add a custom logo for the account. Click CREATE ACCOUNT to complete the account creation.
Figure 2: Create an Account

After the account is created, click SELECT to select the newly created account. Click GO TO ACCOUNT to enter the account and start enrolling the compute nodes and creating applications.
Figure 3: Select an Account

Step 3: Add an EDP Application

Perform the following steps:

In the EDP Add application form, fill in the relevant details such as the Application name and Description (optional).
Select a Fortanix CCM group for the application in the Group field.
Add any certificate using the Certificate configuration section.
Enter the certificate domain. You can choose to add multiple certificates using the ADD A CERTIFICATE button. After you configure all the certificates, click NEXT to configure the image.
Figure 5: Application Created

Step 4: Create an EDP Application Image

In the Add image form, enter the Image Version.
Next, you have to add the Sigstruct details. The SIGSTRUCT for an enclave is generated when an application is signed. It is used to register the enclave with CCM. In the Enclave Configuration SIGSTRUCT section, you will see three options to add SIGSTRUCT. Choose one of the options to add the SIGSTRUCT details.
Figure 6: Create an EDP Application Image
Click CREATE to create the EDP application image.

Step 5: Domain and Image Whitelisting

An application whose domain is whitelisted will get a TLS Certificate from Fortanix CCM. Similarly, when an application runs from the converted image, the application will try to contact Fortanix CCM and ask for a TLS Certificate.
Click the Tasks → Pending menu item, and approve the pending requests to whitelist the domain and image.
Figure 7: Whitelist the Domain
Click the Tasks → Approved menu item, and view the approved requests to whitelist the domain and image.
Figure 8: Whitelist the Image

2.4 Running the application

On a node running the Fortanix CCM Node Agent, start the application.

ftxsgx-runner get-certificate.sgxs

How can I bring my EDP application to Fortanix Confidential Computing Manager?