DSM Accelerator Webservice Deployment

1.0 Introduction

This article describes the steps to deploy and consume Fortanix-Data-Security-Manager (DSM) Accelerator as a standard HTTP REST API using the DSM Accelerator Webservice.

2.0 User Privileges

The Fortanix DSM Accelerator Webservice is distributed as a container image and must be run by launching the container.

To start a container, use Docker CLI commands, which communicate with the Docker daemon (also known as the Docker engine) using a Unix socket.

The Docker daemon operates as a root-level process, managing container resources using kernel-level features such as namespaces, Cgroups, OverlayFS, and network bridges.

The Docker daemon creates the Unix socket with root privileges. As a result, the Docker CLI requires equivalent privileges to access this socket and interact with the daemon. Since the Fortanix DSM Accelerator is a containerized application, it adheres to this same architecture.

Users must have one of the following privileges to run the Fortanix DSM Accelerator Webservice container:

• sudo privileges to run the Docker commands  

• Added to the "docker" group

The rest of this article provides command-line examples, assuming the user has sudo privileges.

3.0 Minimum Server Requirements

The following table outlines the minimum server requirements necessary to deploy and run the Fortanix DSM Accelerator Webservice:

4.0 Deploy Fortanix DSM Accelerator Webservice

1. Download the container tarball (tar) file.  

2. Run the following command to load the Fortanix DSM Accelerator Webservice container:    

   sudo docker load -i CONTAINER_TAR_FILE_NAME

   Here, replace CONTAINER_TAR_FILE_NAME with the name of the file you downloaded.    

5.0 Run Fortanix DSM Accelerator Webservice

The Fortanix DSM Accelerator Webservice can be deployed as a standalone single container or as a service in a Kubernetes cluster.

If you want to run the Fortanix DSM Accelerator Webservice as a single container, run the following command using environment variables:

sudo docker run -it --network host --name dsma \
--mount type=bind,source="/absolute/path/to/your/certs/",target=/certs \
-e CA_FILE=/certs/your_ca_cert.pem \
-e SERVER_CERT_PATH=/certs/your_tls_cert.pem \
-e SERVER_KEY_PATH=/certs/your_private_key.der \
-e FORTANIX_API_ENDPOINT= <FORTANIX DSM URL>\
-e PORT=<PORT_NUMBER> \
-e CACHE_TTL=1800 \
dsma:<VERSION>

Here,

• Replace <FORTANIX DSM URL> with the URL of your Fortanix DSM environment. Use the endpoint corresponding to your Fortanix DSM application’s region listed here. For example, https://amer.smartkey.io.

• Replace <PORT_NUMBER> with the port on which the service should listen. For example, 8080.

• Replace <VERSION> with the desired Fortanix DSM Accelerator Webservice image version. For example, 1.30.2891.

The Fortanix DSM Accelerator Webservice also supports configuration using command-line options. 

The following command starts the container in detached mode (-d) and applies memory and logging limits. This command configures Docker runtime behavior (such as memory usage and logging) and does not configure application-level settings by itself.

sudo docker run -d --network host --memory=1g --memory-swap=2g --log-driver json-file --log-opt max-size=100m

You can add a --help option to see the names of the arguments, their corresponding environment variables, and any defaults.

Usage: dsma [OPTIONS]

Options:
    --fortanix-api-endpoint <ENDPOINT>
        The URL of the fortanix DSM [env: FORTANIX_API_ENDPOINT=] [default: https://apps.smartkey.io]
    --port <PORT>
        The port number that this server will listen on [env: PORT=8080] [default: 8080]
    --ca-file <CA-FILE>
        The path of the CA file for this server [env: CA_FILE=]
    --tls-files <CERT_FILE KEY_FILE>
        The parsed TLS cert and file files to be used instead of self-signed TLS [env: TLS_CERT_AND_KEY_FILES=]
    --proxy <PROXY_SETTINGS>
        The proxy config info to be used when connecting with the backing DSM [env: FORTANIX_PROXY=]
    --cache-ttl <CACHE_TTL>
        The TTL used by the Valentino cache [env: CACHE_TTL=] [default: 3600]
    --retry-for <RETRY_FOR>
        The amount of time the underlying DSM client will retry connections for (time in milliseconds) [env: RETRY_FOR=]
   -h, --help
        Print help
   -V, --version
        Print version

Here,

• For TLS certificate and key file configuration, you can either use a single environment variable TLS_CERT_AND_KEY_FILES or use the split environment variables SERVER_KEY_PATH and SERVER_CERT_PATH that are supported for backward compatibility.

• If you assign both the environment variable and CLI argument in the command to run the Fortanix DSM Accelerator Webservice (for example,-e PORT=8080 --port 8089), then the CLI argument will take precedence, and the Fortanix DSM Accelerator Webservice will use the value specified in the CLI argument.  

• You can choose any port number you want and pass that with the argument for the environment variable PORT or the CLI argument --port. Ensure that the port number is not in use.  

• Set the environment variable value FORTANIX_API_ENDPOINTor the CLI argument --fortanix-api-endpoint to point to your instance of Fortanix DSM/DSM SaaS.  

• Replace the environment variable value VERSION or the CLI argument --version with the version of the Fortanix DSM Accelerator Webservice you loaded and want to run.  

• Use CA_FILE environment variable or the --tls-files CLI argument if you are connecting to Fortanix DSM that uses a certificate signed by a custom CA. If you are connecting to DSM SaaS, you do not need to use this argument.  

• The TLS certificate file pointed to the environment variable SERVER_CERT_PATH or the CLI argument --tls-files can be in either the PEM or DER format. It also accepts the TLS cert chain (PEM chain) as a certificate file.  

• A certificate chain is a sequence of certificates, where each certificate in the chain is signed by the subsequent certificate.

  The expected sequence in a chain is [leaf_cert -> intermediate_ca  -> root_ca]. Where, root-ca is the final node of the certificate chain.

6.0 Additional References

• DSM Accelerator Webservice Developer Guide

• DSM Accelerator Webservice Deployment on AWS Lambda

• DSM Accelerator Webservice with Snowflake

• DSM Accelerator Webservice - External Logging