DSM Accelerator Webservice for Nitro with CCM Setup

1.0 Introduction

This article outlines the procedure for configuring the Fortanix-Data-Security-Manager (DSM) Accelerator Webservice on Nitro Enclave using the Fortanix Confidential Computing Manager (CCM).

Configuring the Fortanix DSM Accelerator Webservice for Nitro with CCM helps with the following:

• Key Export Control: To ensure that only Fortanix DSM Accelerator Webservice can export the key, an authenticated Fortanix DSM Accelerator application (app) will be created in DSM, and a quorum policy will be established in each relevant group requiring this app’s approval for key exports. Users without the app’s approval will encounter errors, though additional apps can be included in the quorum policy if necessary.

• Transport Layer Security (TLS) Certificate Management: The Fortanix DSM Accelerator Webservice will internally manage TLS keys and certificates to comply with enclave security in the Trusted Execution Environment (TEE). When starting the Fortanix DSM Accelerator Webservice, it will either retrieve credentials from Fortanix DSM or use a self-signed certificate if none are available. Fortanix DSM Accelerator Webservice APIs will facilitate the generation and secure storage of TLS keys and certificates, with Fortanix CCM using remote attestation to dynamically obtain a signed certificate from a CCM zone CA for enhanced security.

2.0 Prerequisites

The following are the prerequisites for running Fortanix DSM Accelerator Webservice on Nitro:

• Familiarity with creating accounts and groups in Fortanix CCM: For a quick start, refer to Fortanix CCM - Quickstart.

• Knowledge of using and configuring apps on the Fortanix DSM: For more information, refer to Getting Started with Fortanix DSM.

3.0 Process Diagrams

3.1 Image Conversion

The following diagram illustrates the process of converting the base Fortanix DSM Accelerator Webservice into a Nitro-compatible version using Fortanix CCM. In this process, Fortanix CCM stores the enclave measurements of the converted image.

• Base DSM Accelerator Webservice: This is the original version of the Fortanix DSM Accelerator Webservice, designed without specific compatibility adjustments for Nitro environments.

• Conversion to Nitro Compatibility: This step involves modifying the base Fortanix DSM Accelerator Webservice to ensure it aligns with Nitro’s infrastructure requirements. The modifications might include updates to configuration settings, security features, and integration points.

• Role of Fortanix CCM:

  • Image Conversion: The diagram details how Fortanix CCM supports the conversion process, ensuring that the Fortanix DSM Accelerator Webservice is properly adapted for Nitro.

  • Storing Enclave Measurements: Fortanix CCM captures and stores the enclave measurements of the updated image.

  • Provisioning App Certificates: Fortanix CCM provides the Fortanix DSM Accelerator Webservice with a certificate that enables it to securely authenticate with Fortanix DSM and authorize export requests, ensuring that key exports are limited only to the Fortanix DSM Accelerator Webservice.

3.2 Fortanix DSM Accelerator Webservice Nitro Authentication with Fortanix DSM

The following diagram illustrates the Fortanix DSM Accelerator Webservice authentication process with Fortanix DSM:

• Initially, Fortanix DSM Accelerator Webservice Nitro enclave sends its enclave measurements to Fortanix CCM using the Nitro Node Agent.

• Fortanix CCM then validates these measurements to ensure they are correct and compliant.

• After successful validation, Fortanix CCM issues an application certificate to the Fortanix DSM Accelerator Webservice Nitro enclave. This certificate is essential for authenticating the Fortanix DSM Accelerator Webservice Nitro enclave when connecting to the Fortanix DSM.

This process ensures that the Fortanix DSM Accelerator Webservice Nitro enclave is verified and authorized, allowing for secure interactions with Fortanix DSM.

4.0 Whitelist the Build in CCM Account

Perform the following steps to whitelist the build measurements of the Fortanix DSM Accelerator Webservice Nitro Docker image in your CCM account:

1. Download the latest Fortanix DSM Accelerator Webservice Nitro package.

2. Run the following command to untar the downloaded tarball: For example, dsma-nitro.tgz.

   tar -zxf dsma-nitro.tgz
   ls

   Output:

   README.md  build_info.json  dsma-nitro-1.20.0.2.tgz  dsma-nitro-docker-image.tar  whitelist_domain_and_image.sh tls_configuration_utility.sh

3. Use the whitelist_domain_and_image.sh script to whitelist the build measurements of dsma-nitro-docker-image.tar in your account. The build information is available in the build_info.json file.

   ./whitelist_domain_and_image.sh --help
   Utility responsible for two things: 
   1. Uploads the build measurements of the DSMA to CCM, So the CCM can provision app-cert to DSMA
   2. Downloads the CCM zone CA certificate that signs the app-cert issued to DSMA.
   Once you run this script, Please complete the domain whitelisting and build whitelisting tasks from CCM UI.
   Usage: ./whitelist_domain_and_image.sh -u username -a account-id -b build-info-file -n app-name -g group-id -e ccm-endpoint
   Arguments:
   -u, --username       ccm username
   -a, --account-id     Account ID of the user, can be copied from the settings in the UI
   -b, --build-info     Path to the json file that contains the build measurements supposed to be whitelisted.
   -n, --app-name       Name of the application in which the build has to be whitelisted
   -g, --group-id       Group ID in which the app exists or to be created
   -e, --ccm-endpoint   CCM endpoint URL without any trailing /

4. Create a group (if one does not already exist) on the Fortanix CCM user interface (UI), where the application (for example, dsma-nitro) will be located, and the builds will be associated. You must provide an application name and group IDfor the whitelist_domain_and_image.sh script. It will create the application within the group if it does not already exist.

5. Run the following command to whitelist the build in the Fortanix CCM account:

   ./whitelist_domain_and_image.sh --username testuser@fortanix.com \
   --account-id 40fefbf-6e8f-49e1-b1e8-f400ba70d6af \
   --group-id 5fca626-9a3f-4dc6-b4ab-34791282ddb8 \
   --app-name dsma-nitro --build-info ./build.test.json \
   --ccm-endpoint https://ccm.test.fortanix.com

   Output:

   Username: user@fortanix.com
   Account ID: 40fe1fbf-6e8f-49e1-b1e8-f400ba80d6af
   Build Info: ./build.test.json
   App Name: dsma-nitro
   Group ID: 5fca2626-9a3f-4dc6-b4ab-347912b2ddb8
   CCM Endpoint: https://ccm.test.fortanix.com
   Enter your password: 
   Authenticating to ccm
   Selecting the account
   Copying the zone CA certificate to <script-dir>/zone_cert.pem
   App does not exist, creating one
   APPID: "05dd426d-bc05-43e5-86db-12b6b7709c8f"
   Whitelisting the Domain
   Successfully whitelisted the Domain
   Successfully added the build to the app:dsma-nitro
   Whitelisting the build
   Successfully whitelisted the build

5.0 Run Fortanix DSM Accelerator Webservice on Nitro

Perform the following steps to run Fortanix DSM Accelerator Webservice on Nitro:

1. Refer to the recommended specifications below for setting up your Amazon Web Services (AWS) instance:

   1. Nitro Enclave: Enabled

   2. Instance Type: c5a.2xlarge

   3. AMI: Amazon Linux 2023

   4. Hard Disk: Tested with 24 GB

   5. Allow incoming HTTP connections

   6. Allow incoming HTTPS connections

2. Install the Nitro CLI using the steps mentioned in the AWS official documentation.

3. Update the /etc/nitro_enclaves/allocator.yaml file to allocate at least 2 GB of memory and 4 CPUs for Fortanix DSM Accelerator Webservice Nitro.

   Run the following command to restart the nitro-enclaves-allocator.service if needed:

   sudo systemctl restart nitro-enclaves-allocator.service

4. Enroll a compute node on Fortanix CCM. This process includes preparing the host for the DSM Accelerator Webservice Nitro deployment by installing a node agent, which helps the DSM Accelerator Webservice Nitro enclave obtain a certificate from the Fortanix CCM.
   For more information on enrolling a compute node, refer to Enroll a Compute Node Using AWS Nitro on Amazon Linux.

5. Run the docker load command to load the Fortanix DSM Accelerator docker image: Here, dsma-nitro-docker-image.tar is the Nitro-compatible Fortanix DSM Accelerator Webservice image.

   $ docker load  < dsma-nitro-docker-image.tar
   Loaded image: dsma-nitro:1.20.0.2
   $ docker image ls
   REPOSITORY   TAG            IMAGE ID       CREATED        SIZE
   dsma-nitro   1.20.0.2       3d0c7ff3271d   32 hours ago   944MB
   

6. Run the following commands to obtain the zone CA that issues the app certificate to Fortanix DSM Accelerator Webservice Nitro: You can skip this step if you already have a zone CA certificate obtained in Step 4 of Section 4.0: Whitelist the Build in CCM Account.

   # login to ccm cluster (prod)
   curl -c /dev/shm/ccm-cookies --request POST -u '<username>:<password>''https://ccm.fortanix.com/v1/sys/auth'
   # Select  account
   curl -b /dev/shm/ccm-cookies -c /dev/shm/ccm-cookies --header 'X-CSRF-Header: 1' --header 'Content-Type: application/json' -X POST https://ccm.fortanix.com/v1/sys/session/select_account/<acct-id>
   # <acct-id> is the ccm account id
   # Get zone cert
   curl --request GET -b /dev/shm/ccm-cookies --header 'X-CSRF-Header: 1' --header 'Content-Type: application/json' 'https://ccm.fortanix.com/v1/zones' | jq .
   # To escape new line characters in the cert do this
   echo $(curl --request GET -b /dev/shm/ccm-cookies --header 'X-CSRF-Header: 1' --header 'Content-Type: application/json' 'https://ccm.fortanix.com/v1/zones' | jq '.[0].certificate')

7. On Fortanix DSM UI, configure an application (for example, dsma-nitro) with authentication using Trusted CA.

   1. Fortanix DSM Accelerator Webservice will use this application to interact with Fortanix DSM independently. Ensure to record the app ID for future reference.

   2. Fortanix DSM Accelerator Webservice will present the signed certificate issued by the CCM zone CA (with the domain fortanix.com) to authenticate the app and enable these interactions.

   

8. Create a group that is accessible only by dsma-nitro. This group will be used to store the TLS certificate and private key for client connections. Ensure that this group is set as the default group for the application.

9. Add dsma-nitro to all groups whose keys need to be accessed through Fortanix DSM Accelerator Webservice, designating it as the quorum approver. This will prevent client applications from exporting the keys independently.
   For more information, refer to Group Quorum Policy.

   NOTE

   • Ensure you include several human quorum reviewers to avoid the risk of losing control over the keys.

   • Select only the Cryptographic Operations while configuring the group quorum policy.

   

10. Generate an RSA key in the default group of the dsma-nitro app. The key UUID must be provided when starting the Fortanix DSM Accelerator Webservice container. This key will be used for TLS configuration of the Fortanix DSM Accelerator Webservice.

    

11. Run the following command to start the Fortanix DSM Accelerator Webservice container:

    sudo docker run -it --rm --privileged -v /run/nitro_enclaves:/run/nitro_enclaves\
    -e NODE_AGENT=http:/<host-ip>:9092/v1/ -p 443:443 \
    -e NITRO_ENABLED="true" -e DSMA_APP_ID="<dsma-app-id-created-in-step-9>" \
    -e TLS_KEY_ID="<rsa-key-id-created-in-step-12>" \
    -e PORT=443 -e CACHE_TTL=900 -e BEARER_AUTH_ENABLED="true"\
    -e FORTANIX_API_ENDPOINT="<sdkms-endpoint>" <nitro-compatible-docker-image>

    Example:

    sudo docker run -it --rm --privileged -v /run/nitro_enclaves:/run/nitro_enclaves\
     -e RUST_LOG=debug -e NODE_AGENT=http://172.31.7.150:9092/v1/ -p 443:443\
     -e NITRO_ENABLED="true" \
     -e DSMA_APP_ID="8a284543-a98c-4e15-b8a0-c3315a7e2364" -e PORT=443 \
     -e TLS_KEY_ID="5a9fd402-5aff-4326-939e-e0c25345b064" -e BEARER_AUTH_ENABLED="true"\
     -e CACHE_TTL=900 -e FORTANIX_API_ENDPOINT="https://apps.sdkms.test.fortanix.com"\513076507034.dkr.ecr.us-west-1.amazonaws.com/dsma-nitro:1.19.0.1-converted

    Here.

    • In the docker run command, ensure that the endpoint does not have any trailing slashes (/).

    • Prefix the DSM endpoint with apps. as shown in the example above, since standard endpoints do not support authentication using a Trusted CA.

    • The NITRO_ENABLED flag will launch the Fortanix DSM Accelerator Webservice in Nitro mode.

    • The DSMA_APP_ID is used to identify the dsma-nitro app.

    • The TLS_KEY_ID specifies the private key for which the Certificate Sign Request (CSR) will be generated and where the signed certificates will be stored.

    • The BEARER_AUTH_ENABLED is to enable Fortanix DSM Accelerator Webservice to accept bearer authentication for crypto requests.

6.0 Configure TLS for Fortanix DSM Accelerator Webservice on Nitro

The following are the steps to configure a TLS for Fortanix DSM Accelerator Webservice on Nitro:

1. When the Fortanix DSM Accelerator Webservice starts up, the dsma-nitro app attempts to export the key with the ID specified by TLS_KEY_ID in Fortanix DSM. If the key is located, the corresponding certificates are retrieved from Fortanix DSM. The exported private key and certificates are then used to configure TLS for the Fortanix DSM Accelerator Webservice.

   INFO dsma - =========== DSMA SERVER START UP =================
   INFO dsma - Listening on port: 443
   INFO dsma - CA File path: None
   INFO dsma - Connection will retry in: 30000 millis
   INFO dsma - Availability set to false
   INFO dsma - TTL used by the Valentino cache: 900 sec
   INFO dsma - =============== SETTING UP DSMA SERVER ===============
   INFO dsma::server - Initialized DsmAServer
   Proxy config: None
   INFO dsma - Successfully connected to DSM at "https://apps.sdkms.test.fortanix.com"
   INFO dsma::server - Fetching TLS key and certs from DSM
   INFO sdkms_provider::async_state - 2024-09-11 13:16:38.525105341 UTC OUTBOUND REQ POST crypto/v1/keys/export
   INFO sdkms_provider::async_state - 2024-09-11 13:16:39.015044571 UTC INBOUND RESP X-Request-ID: dyXCjyxr Status: 200 OK
   INFO dsma::server - Found no certificate associated with the key  
   INFO dsma::api - Building router
   INFO dsma - =============== DSMA SERVER SETUP COMPLETE ===============
   WARN dsma - Using self-signed TLS certificate. In order to avoid this, use the argument `--tls-files`.

2. If the certificates associated with the key are not present in Fortanix DSM, Fortanix DSM Accelerator Webservice will use a self-signed certificate instead. Use the tls_configuration_utility.sh provided in the package to configure TLS for the Fortanix DSM Accelerator Webservice as shown below:

   ./tls_configuration_utility.sh --help
   ================ CLI Tool to manage TLS certificates in DSMA ================
   Description:
   This CLI Tool provides functionalities for generating Certificate Signing Requests (CSR) and uploading TLS certificate.
   --generate-csr => Create a CSR (Certificate Signing Request) using either interactive prompts or an input file. You can specify an output file for the CSR or print it to the terminal.
   --upload-cert  => Process and upload a certificate chain from a specified file. The certificates in the file will be read and uploaded to DSM.
   You can authenticate using an API key. API key must belong to an app that has access to the TLS private key that was provided while starting DSMA.
   Usage: ./tls_configuration_utility.sh [OPTIONS]
   Pre-requisite: This script uses DSMA APIs to configure TLS, So it expects DSMA to be running and it's hosted location for --dsma-endpoint
   OPTIONS:
     -e, --dsma-endpoint    Specify the DSMA endpoint URL without any trailing /
     -g, --generate-csr     Generate CSR, You can optionally provide an input file for CSR details and specify an output file for saving the generated CSR.
                            Use [--generate-csr --help]/[-g -h] for detailed help related to CSR generation.
     -h, --help             Show this help message
     -u, --upload-cert      Specify the path to a file containing TLS certificate. Tool will read and upload the certificates from the file to DSM.
   Environment Variables:
     API_KEY        You can set the API key as an environment variable. If you don't answer api-key prompt, the script will use the API_KEY environment variable.
     DSMA_ENDPOINT  You can set the DSMA Endpoint as an environment variable. If --dsma-endpoint is not provided, the script will use the DSMA_ENDPOINT environment variable.
   Examples:
     ./tls_configuration_utility.sh --dsma-endpoint https://api.example.com --generate-csr                # Tool will prompt for CSR inputs to generate the CSR, CSR is printed to terminal
     ./tls_configuration_utility.sh --dsma-endpoint https://api.example.com --generate-csr -o mycsr.pem   # Tool will prompt for CSR inputs to generate the CSR
     ./tls_configuration_utility.sh --dsma-endpoint https://api.example.com --generate-csr -i myinput.txt # CSR is printed to terminal
     ./tls_configuration_utility.sh --dsma-endpoint https://api.example.com --generate-csr --input-csr myinput.txt --output-csr mycsr.pem

3. Use the --generate-csr flag to create a CSR using the provided private key. You can also include optional --input-file and --output-file flags.
   Here are the methods for CSR generation:

   1. Without --input-file and --output-file: You will be prompted for input, and the generated CSR will be displayed in the terminal.

      ./tls_configuration_utility.sh --dsma-endpoint <DSMA_ENDPOINT> --generate-csr
      Enter your API Key:
      Enter Country Name (2 letter code) : US
      Enter State or Province Name (full name): California
      Enter Locality Name: Santa Clara
      Enter Organization Name: Company
      Enter Organizational Unit Name: IT
      Enter Common Name: www.fortanix.com
      Enter Email Address: <EMAIL>
      Enter DNS Names (comma-separated, e.g., dns1.com,dns2.com): www.fortanix.test.com,www.foratnixtest.com
      CSR:
      -----BEGIN CERTIFICATE REQUEST-----
      <CSR_CONTENT>
      -----END CERTIFICATE REQUEST-----

   2. With only --input-file: Provide the path to an input file formatted as specified in the help documentation (see --generate-csr --help). The tool will read from this file.

      ./tls_configuration_utility.sh --dsma-endpoint <DSMA_ENDPOINT> --generate-csr --input-file <path_to_csr_input_file>
      Enter your API Key:
      Parsing OID values from csrinput...
      CSR:
      -----BEGIN CERTIFICATE REQUEST-----
      <CSR_CONTENT>
      -----END CERTIFICATE REQUEST-----

   3. With only --output-file: Specify a path for the output file where the generated CSR will be saved.

      ./tls_configuration_utility.sh --dsma-endpoint <DSMA_ENDPOINT> --generate-csr --output-file <path_to_csroutput_file>
      Enter your API Key: 
      Enter Country Name (2 letter code) : US
      Enter State or Province Name (full name): California
      Enter Locality Name: Santa Clara
      Enter Organization Name: Company
      Enter Organizational Unit Name: IT
      Enter Common Name: www.fortanix.com
      Enter Email Address: <EMAIL>
      Enter DNS Names (comma-separated, e.g., dns1.com,dns2.com): www.fortanix.test.com,www.foratnixtest.com
      CSR saved to file: <path_to_csroutput_file>

   4. With both --input-file and --output-file: Provide paths for both the input and output files.

      ./tls_configuration_utility.sh --dsma-endpoint <DSMA_ENDPOINT> --generate-csr --input-file <path_to_csr_input_file> --output-file <path_to_csroutput_file>
      Enter your API Key:
      Parsing OID values from csrinput...
      CSR saved to file: <path_to_csroutput_file>

4. After you have the CSR, you can have it signed by your trusted CA. Then, use the --upload-cert command to upload the signed certificate, which will import it into DSM for future use.

   ./tls_configuration_utility.sh --dsma-endpoint <DSMA_ENDPOINT> --upload-cert <path_to_cert>
   Enter your API Key:
   Certificate has been uploaded successfully.

   NOTE

   • The order of the certificates is [“<leaf-cert>”, “<intermediate-cert-1>”, “<intermediate-cert-2>”, …, “<root-ca>”]..

   • Each certificate should be a string without Privacy-Enhanced Mail (PEM) guards or newline characters.

   The image below displays the certificates that were imported into the dsma-nitro group after the successful request to –-upload-cert:

   

5. When the app is restarted, Fortanix DSM Accelerator Webservice begins again from Step 1.

   INFO dsma - ================= DSMA SERVER START UP =================
   INFO dsma - Listening on port: 443
   INFO dsma - CA File path: None
   INFO dsma - Connection will retry in: 30000 millis
   INFO dsma - Availability set to false
   INFO dsma - TTL used by the Valentino cache: 900 sec
   INFO dsma - =============== SETTING UP DSMA SERVER ===============
   INFO dsma::server - Initialized DsmAServer
   Proxy config: None
   INFO dsma - Successfully connected to DSM at "https://apps.sdkms.test.fortanix.com"
   INFO dsma::server - Fetching TLS key and certs from DSM
   INFO sdkms_provider::async_state - 2024-09-11 14:01:52.414029253 UTC OUTBOUND REQ POST crypto/v1/keys/export
   INFO sdkms_provider::async_state - 2024-09-11 14:01:52.903381872 UTC INBOUND RESP X-Request-ID: 6HPoJiBn Status: 200 OK
   INFO sdkms_provider::async_state - 2024-09-11 14:01:52.923782357 UTC OUTBOUND REQ GET crypto/v1/keys/971420ec-9955-47c0-ad6d-c6d198c5cfah
   INFO sdkms_provider::async_state - 2024-09-11 14:01:53.003644554 UTC INBOUND RESP X-Request-ID: XTf1iLt8 Status: 200 OK
   INFO sdkms_provider::async_state - 2024-09-11 14:01:53.004076964 UTC OUTBOUND REQ GET crypto/v1/keys/1ae9f0ca-b57e-4c3a-a25b-9c2e9a368bf3
   INFO sdkms_provider::async_state - 2024-09-11 14:01:53.104191706 UTC INBOUND RESP X-Request-ID: udzrfhTQ Status: 200 OK
   INFO dsma - Using certificate found in DSM
   INFO dsma::api - Building router

7.0 Additional References

• DSM Accelerator - Concepts

• DSM Accelerator Webservice Developer Guide

• DSM Accelerator Webservice Deployment