---
title: "DSM Accelerator Webservice Developer Guide"
slug: "dsm-accelerator-webservice-developer-guide"
updated: 2026-06-10T15:16:05Z
published: 2026-06-10T15:16:05Z
canonical: "support.fortanix.com/dsm-accelerator-webservice-developer-guide"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.fortanix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DSM Accelerator Webservice Developer Guide

## 1.0 Introduction

This article describes the Fortanix-Data-Security-Manager (DSM) Accelerator Webservice configurations and supported features.

For clients that require no-code changes, Fortanix DSM Accelerator Webservice can be provisioned as an industry-standard PKCS#11 and JCA/JCE library. This allows for routine symmetric and asymmetric cryptographic operations, as outlined in [*Algorithm Support*](https://support.fortanix.com/docs/algorithm-support). However, certain applications may use the Fortanix SDK and DSM REST APIs directly. Such applications can use Fortanix DSM Accelerator Webservices, which can be provisioned in various containerized environments such as managed, cloud-native, or on-premises Kubernetes, OpenShift, and so on.

> [!NOTE]
> NOTE
> 
> Fortanix DSM Accelerator Webservice is an optional extension to the Fortanix DSM platform. Be aware of the license requirements in use.

## 2.0 Downloads

The latest version of the Fortanix DSM Accelerator Webservice can be downloaded [*here*](https://fortanix.zendesk.com/hc/en-us/articles/9677812763156-DSM-Accelerator-Webservice).

*For information on Fortanix DSM Accelerator Webservice deployment and installation, refer to*[*DSM Accelerator Webservice Deployment*](/v1/docs/dsm-accelerator-webservice-deployment-guide)*.*

## 3.0 Supported Features

| **SUPPORTED FEATURES** | **API** | **DESCRIPTION** |
| --- | --- | --- |
| **Clear-cache endpoint** | `dsma_hostname/accelerator/v1/keys/clear` | Use this API to clear the cache by providing a list of key IDs in the payload. |
| **API endpoint in Fortanix DSM Accelerator Webservice for GET** | `<dsma_hostname>/` | This endpoint can be invoked on the root URL itself - "`/`". This endpoint can be used to check the availability of the Fortanix DSM Accelerator Webservice. For example, if the Fortanix DSM Accelerator Webservice instance is running on localhost:8080, then the API can be invoked at `https://localhost:8080/`. |
| **Support for bringing up/ starting Fortanix DSM Accelerator Webservice using PEM or DER format for a secret key.** | NA | DER format: `sudo docker run -it --network host --fortanix-api-endpoint <end-point> -v /home/administrator/dsma/certs:/certs --tls-files "/certs/dsma_tls_chain.pem /certs/dsma_key.der" --port <port number> <webservice number> /bin/bash` PEM format: `sudo docker run -it --network host --fortanix-api-endpoint <end-point> -v /home/administrator/dsma/certs:/certs --tls-files "/cert/dsma_tls_chain.pem /cert/dsma_key.pem" –port <port number> dsma:<webservice version> /bin/bash` |
| **Time-based expiration policy - TTL (Time to Live) for its cache** | NA | Use this parameter to set the expiration time for all the keys being cached by the Fortanix DSM Accelerator Webservice. You can configure this value as per your application requirements and/or use-case by providing the `--cache-ttl` CLI configuration with a value in seconds (unit of time). For example, `--cache-ttl 600`. |
| **Encrypt** | - `crypto/v1/encrypt` - `crypto/v1/keys/:id/encrypt` |  |
| **Decrypt** | - `crypto/v1/decrypt` - `crypto/v1/keys/:id/decrypt` |  |
| **Sign** | - `/crypto/v1/sign` - `/crypto/v1/keys/{key-id}/sign` |  |
| **Verify** | - `/crypto/v1/verify` - `/crypto/v1/keys/{key-id}/verify` |  |
| **Batch Encrypt** | `crypto/v1/keys/batch/encrypt` |  |
| **Batch Decrypt** | `crypto/v1/keys/batch/encrypt` |  |
| **Batch Sign** | `crypto/v1/keys/batch/sign` |  |
| **Batch Verify** | `crypto/v1/keys/batch/verify` |  |
| **Generate an HMAC Key** | `/crypto/v1/mac` |  |
| **Verify an HMAC Key** | `/crypto/v1/macverify` |  |
| **Support for policy awareness in the Fortanix DSM Accelerator Webservice for security objects** | NA | Fortanix DSM Accelerator Webservice enforces application and security object policy from the upstream DSM. |
| **Support for policy awareness in the Fortanix DSM Accelerator Webservice for apps** | NA | Fortanix DSM Accelerator Webservice enforces application and security object policy from the upstream DSM. |
| **Support for password-protected TLS private keys** | NA | Allows TLS server private keys to be encrypted. |
| **Support for Mutual TLS (mTLS)-based export from Fortanix DSM** | NA | Allows the Fortanix DSM Accelerator Webservice to export keys using its certificate and private key using mTLS, instead of relying on client application (app) credentials. You can configure it using environment variables or CLI options. *For more information, refer to*[*Section 7.6: Mutual TLS (mTLS) Based Exports*](/v1/docs/dsm-accelerator-webservice-developer-guide#76-mutual-tls-mtls-based-exports)*.* |

## 4.0 Supported Algorithms and Modes

The following table lists the algorithm, modes, and key size supported for the Fortanix DSM Accelerator Webservice:

| **Crypto** | **Algorithm** | **Mode/Method** | **Key Size/Curve** | **Padding Support** | **Use** |
| --- | --- | --- | --- | --- | --- |
| **Symmetric** | AES | CFB | 128/192/256 bits |  | Data Encryption or Decryption, Tokenization |
| CCM |
| GCM |
| CTR |
| CBCNOPAD |
| OFB |
| CBC |
| ECB |
| KW |
| KWP |
| FF1 (or FPE) | 256 bits |  |  |
| **Symmetric** | DES | CBCNOPAD | 56 bits |  | Data Encryption or Decryption |
| CBC |
| ECB |
| **Symmetric** | DES3 | CBC | 112/168 bits |  | Data Encryption or Decryption |
| CBCNOPAD |
| ECB |
| **Symmetric** | SHA-1 | SHA-1 | HMAC Key Length: Between 112 and 8192 bits |  | Mac Generate and Mac Verify, Key Generation |
| SHA-2 | SHA-1 |
| SHA-224 |
| SHA-256 |
| SHA-384 |
| SHA-512 |
| RIPEMD | RIPEMD-160 |
| **Asymmetric** | EC | SHA224 | Curves: SecP192K1, SecP224K1, SecP256K1, NistP192, NistP224, NistP256, NistP384, NistP521 |  | Digital Signature sign or verify |
| SHA256 |
| SHA512 |
| SHA1 |
| SHA384 |
| **Asymmetric** | RSA | SHA256 | Exponent = [65537, 3] | PSS, PKCS#1 v1.5 | Digital Signature sign or verify |
| SHA512 |
| SHA1 |
| SHA384 |
| PKCS#1 v1.5, OAEP | Data Encryption or Decryption |

## 5.0 Permissions and Policies

Fortanix DSM Accelerator Webservice honors the following policies for both security objects and apps as defined in the Fortanix DSM user interface (UI):

> [!NOTE]
> NOTE
> 
> Fortanix DSM Accelerator Webservice supports encryption using either the UUID (kid) or the name of the security object. While performing the encryption using the security object name, ensure that the following endpoints are used:
> 
> - `https://{{localhost}}/crypto/v1/encrypt`
> - `https://{{localhost}}/crypto/v1/decrypt`
> - `https://{{localhost}}/crypto/v1/sign`
> - `https://{{localhost}}/crypto/v1/verify`
> - `https://{{localhost}}/crypto/v1/keys/batch/sign`
> - `https://{{localhost}}/crypto/v1/keys/batch/verify`

- **Export** - This operation enables the security object to be retrieved with an authenticated request. This operation exports the security object either from the DSM Accelerator local cache (if it exists) or from the Fortanix DSM. By default, the 'Export' operation is disabled for all key types. The operation should not be enabled unless required. It is more secure to keep the value of the key inside Fortanix DSM only.

> [!NOTE]
> NOTE
> 
> Fortanix DSM Accelerator requires export permission to be enabled for the security objects to be cached locally.
- **Sign**– This operation enables the key to be used for generating a digital signature. The signing key must be an asymmetric key such as RSA, DSA, or elliptical key, with the private part present. The symmetric keys may not be used to sign data.
- **Verify**- This operation enables the key to be used for verifying a signature. The verifying key must be an asymmetric key such as RSA, DSA, or an elliptic curve key, with the ‘Verify’ operation enabled. The symmetric keys may not be used to verify data.

> [!NOTE]
> NOTE
> 
> Currently, Fortanix DSM Accelerator only supports RSA and EC asymmetric keys for Sign and Verify.
- **Encrypt** – This operation allows the key to be used for encryption. Encryption involves converting data from plain text to an encoded format called ciphertext using a key generated by an algorithm. Both asymmetric and symmetric keys can be used to perform the ‘Encrypt’ operation.
- **Decrypt** - This operation allows the key to be used for decryption. Decryption involves the process of converting ciphertext into plaintext using a key. Both asymmetric and symmetric keys can be used to perform the ‘Decrypt’ operation.

> [!NOTE]
> NOTE
> 
> - The effective policy is the largest set of permissions contained in both the set of app (application) and security object permissions. For example, if an app is permitted to perform encryption and decryption operations using the key, and the security object is only permitted to perform encryption, then you will only be able to perform encryption using the key.
> - The effective policy will be updated after exporting a security object from Fortanix DSM to the Fortanix DSM Accelerator Webservice.

![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/Ven Diagram.png)

**Figure 1: Ven diagram**

## 6.0 Supported Endpoints

The current version of the Fortanix DSM Accelerator Webservice handles the following APIs locally (accelerated). That is, the following operations are performed locally using cached keys, and the rest of the APIs are proxied to the DSM that you specified using the `FORTANIX_API_ENDPOINT` variable. You can point your application to your running instance of Fortanix DSM Accelerator Webservice, and it will work seamlessly.

- `crypto/v1/encrypt`
- `crypto/v1/decrypt`
- `crypto/v1/sign`
- `crypto/v1/verify`
- `crypto/v1/keys/batch/encrypt`
- `crypto/v1/keys/batch/decrypt`
- `crypto/v1/keys/batch/sign`
- `crypto/v1/keys/batch/verify`
- `crypto/v1/keys/{key-id}/sign`
- `crypto/v1/keys/{key-id}/verify`
- `crypto/v1/keys/:id/encrypt`
- `crypto/v1/keys/:id/decrypt`
- `crypto/v1/mac`
- `crypto/v1/macverify`

> [!NOTE]
> NOTE
> 
> When calling these APIs, you need to pass the Basic authentication token directly. You do not need to authenticate first and then pass the bearer token.

In addition to these crypto API endpoints, Fortanix DSM Accelerator Webservice also provides the following API endpoints:

- Clear-cache endpoint [`POST` API]: `/accelerator/v1/keys/clear`

This API is used to clear the cache by providing a list of key IDs in the payload.

The following is an example that shows how to use this API to clear the cache by providing a list of key IDs in the payload:

```bash
curl --location -X POST 'https://dsma.fortanix.com:8080/accelerator/v1/keys/clear' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Nzc...cUxR' \
--data-raw '{"key_ids": [
		"8868fc72-b771-11ed-afa1-0242ac120002",
		"987689cb-ef23-41d5-a468-556a910b1402",
		"d7833ef3-6803-4afa-b7ca-499c34c4664d"
	]
}'
```

The following is an example to clear the entire cache by providing an empty or null payload.

```bash
curl --location -X POST 'https://dsma.fortanix.com:8080/accelerator/v1/keys/clear' \
--header 'Authorization: Basic MWE0YWExNTY...vWUZDUzFzQzNR' \
--data-raw '{}'
```

> [!NOTE]
> NOTE
> 
> You can also pass `--data-raw '{}'` in the command above to clear the entire cache.
- `GET` API]: `<dsma_hostname>/`

This endpoint can be invoked on the root URL itself - "`/`".

For example, if the Fortanix DSM Accelerator Webservice instance is running on localhost:8080, then the API can be invoked at `https://localhost:8080/`. This endpoint performs a connection test to ascertain that the Fortanix DSM Accelerator Webservice instance is up and running and that the client application is able to make REST calls to its URL. The response HTTP Status Code - 200 OK should be considered a success.

The following is an example of the CURL request:

```bash
curl --location --request GET 'https://localhost:8080/'
```

> [!NOTE]
> NOTE
> 
> This is a no-auth API, hence it does not require any Authorization header in the request call.

## 7.0 Configure DSM Accelerator Webservice Properties

### 7.1 Proxy Settings

Fortanix DSM Accelerator Webservice also allows you to specify a proxy. To use a proxy for the Fortanix DSM Accelerator Webservice, set the environment variable `FORTANIX_PROXY`.

This value for this environment variable is of the form:

`http://{{username}}:{{password}}@{{host}}:{{port}}`

Where, `username` and `password` are optional.

Example:

`--proxy http://administrator:password@91.126.249.149:2946`

Or

`-e FORTANIX_PROXY=http://administrator:password@91.126.249.149:2946`

### 7.2 Time-Based Expiration Policy

Fortanix DSM Accelerator Webservice supports a "time-based expiration policy" - Time to Live (TTL) for its cache. This feature allows you to set the expiration time for all the keys being cached by the Fortanix DSM Accelerator Webservice.

- You can configure this value as per your application requirements and/or use-case by providing the `CACHE_TTL` environment variable or the `--cache-ttl` CLI argument with a value in seconds (unit of time).

Example:
  - Using the environment variable : `-e CACHE_TTL=600`
  - Using CLI argument: `--cache-ttl 600`
- By default, this value is `3600` seconds (60 minutes). This default value will apply in case the environment variable is not configured or set properly.
- A cached entry will expire after the specified duration past from insert. For example, `--cache-ttl 1200` seconds (20 mins).

| **ENTRY** | **INSERTED AT** | **EXPIRED AT** |
| --- | --- | --- |
| Key-1 | 12:00 | 12:20 |
| Key-2 | 12:10 | 12:30 |
- The effective maximum `--cache-ttl` for Fortanix DSM Accelerator Webservice instance may be limited by an Administrative Policy set in DSM in the future.

### 7.3 Prioritize Cached Key

Fortanix DSM Accelerator Webservice allows users to set a TTL for cached keys. Once the TTL expires, the keys are automatically removed from the cache, even if they could be refreshed. When a key is accessed again, the Fortanix DSM Accelerator Webservice tries to retrieve and cache it. However, if Fortanix DSM is unreachable, the operation will fail.

To address potential outage scenarios and ensure that the Fortanix DSM Accelerator Webservice can keep working with the existing cached keys, users can set the `AVAILABILITY` environment variable to `true` and prioritize the use of the cached key.

For example, `-e AVAILABILITY=true` or `--availability`

### 7.4 Key Export Guardrails

The Key Export Guardrails feature enables Fortanix DSM Accelerator Webservice to enforce export permissions configured on security objects in Fortanix DSM.

When export restrictions are applied:

- The client application can access the security object only in wrapped form.
- Raw key material is never exposed.
- Client access is limited to cryptographic operations only.

*For more information on export permissions, refer to*[*Export Policy*](/v1/docs/users-guide-export-policy)*.*

**Prerequisite:**

- **Export permissions** must be configured on the security object in Fortanix DSM.
- Wrapping keys must be defined in the **Export Permissions**.

Perform the following steps to enable Key Export Guardrails on Fortanix DSM Accelerator Webservice:

1. Add the following environment variable to the Docker container:

```bash
WRAPPED_EXPORTS_ENABLED=true
```

Alternatively, you can pass the following optional command-line argument:

```bash
--wrapped-expbasorts-enabled
```
2. Add the wrapping keys configured in the export policy in Fortanix DSM by specifying the file or directory paths where the list of unwrapping keys is in JSON format. The paths should be provided as space-separated values along with `dir` or `file` format specifiers, where `dir` represents the directory of files and `file` represents the individual file path.

> [!NOTE]
> NOTE
> 
> You must specify a value for `UNWRAPPING_KEYS` if `WRAPPED_EXPORTS_ENABLED` is set to true.

> [!NOTE]
> NOTE
> 
> Specifying `unwrapping_keys` is mandatory when Key Export Guardrails are enabled.

Each file should contain a list of JSON objects, as shown in the following example:

```bash
[
    {
        "key": {
            "kid": "ce12f4fa-e518-4767-9c8e-c8e31feb82b8"
        },
        "unwrapping_key": "6qUAwWnaGuDMBBCyVi28MU/7HIk8ASYEKiTsJlx+XM8="
    },
    {"key": {
            "kid": "ce12f4fa-e518-4767-9c8e-c8e31feb82b7"
        },
        "unwrapping_key": "6qUAwWnaGuDMBBCyVi28MU/7HIk8ASYEKiTsJlx+XM8="
    },
    {"key": {
            "name": "pub-key"
        },
        "is_asymmetric": true,
        "unwrapping_key": "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"
    }
]
```
  - Using environment variables:

```bash
UNWRAPPING_KEYS="dir <directory-1-path> <directory-2-path> ..."
```

Or

```bash
UNWRAPPING_KEYS="file <file-1-path> <file-2-path> ...."
```
  - Using command line arguments:

```bash
--unwrapping-keys "dir <directory-1-path> <directory-2-path> ..."
```

Or

```bash
--unwrapping-keys "file <file-1-path> <file-2-path> ..."
```
  - The `key` field must be the security object descriptor (as configured in the Fortanix DSM Export permissions). Fortanix DSM supports wrapping by key ID (`kid`) or key name (`name`) in the export policy.
    - For enhanced security, only the following keys are supported:
      - AES (256-bit GCM) can wrap both symmetric and asymmetric keys.
      - RSA with OAEP SHA256 encryption padding can only wrap symmetric keys.
    - The `is_asymmetric` field is optional. It indicates whether the wrapping key is asymmetric. The default value is `false`.
    - The `unwrapping_key` field contains the key material used to unwrap the exported key in Base64-encoded format. For asymmetric wrapping, this should be the private key.

### 7.5 TLS Configuration

Fortanix DSM Accelerator Webservice supports TLS configuration using a server certificate and private key in PEM or DER format, including private keys encoded in PKCS#8 format.

#### 7.5.1 TLS Server Certificate and Key Configuration

The TLS server certificate and private key for Fortanix DSM Accelerator Webservice can be configured using:

- The environment variable `TLS_CERT_AND_KEY_FILES`

Or
- The CLI argument `--tls-files`

Both of which accept space-separated absolute paths to the certificate and private key files, respectively, in the following format:

```bash
<path/to/cert> <path/to/key>
```

Example:

```bash
"/home/user/tls/cert.pem /home/user/tls/key.pem"
```

#### 7.5.2 Password-protected TLS Private Keys

Fortanix DSM Accelerator Webservice supports password-protected TLS private keys, including encrypted PKCS#8 keys.

If the TLS private key is encrypted, the password required to decrypt it can be provided using:

- The environment variable `TLS_KEY_PASSWORD_FILE`

Or
- The CLI argument `--tls-key-password-file`

Both of which accept the absolute path to a file containing the password.

This configuration**is optional**and**must be specified only when the TLS private key is password-protected**.

Example:

```bash
"/home/user/tls/tls-key-password.txt"
```

### 7.6 Mutual TLS (mTLS) Based Exports

mTLS-based exports in Fortanix DSM Accelerator Webservice offer a more secure way to export cryptographic keys from Fortanix DSM. Traditionally, exports require client app credentials, which in turn require broader export permissions. With mTLS, the Fortanix DSM Accelerator Webservice authenticates using its own certificate and private key, allowing independent key exports while restricting client applications to crypto-only access. This enhances security and reduces the overall permission scope.

> [!NOTE]
> NOTE
> 
> **PKCS#12 (.p12)–based configuration is deprecated**. But it **remains supported for backward compatibility**.

#### 7.6.1 Prerequisites

Before enabling mTLS-based exports, the following prerequisites must be completed to ensure proper authentication and access configuration:

- Fortanix DSM Administrator (admin) must create a dedicated application in DSM for the DSM Accelerator Webservice.
- The application must be configured for **Trusted CA** or **Certificate** authentication.
- The certificate and private key must be provided to the DSM Accelerator Webservice in PKCS#12 (`.p12`) format.

#### 7.6.2 Setup

Perform the following steps to enable mTLS-based exports in Fortanix DSM Accelerator Webservice:

- Create a DSM app dedicated to Fortanix DSM Accelerator Webservice key exports, configure it with Trusted CA or Certificate authentication, add it to the relevant key group(s), and grant export permissions only to this app. *For more information on DSM app creation, refer to*[*Getting Started with Fortanix DSM - UI*](/v1/docs/users-guide-getting-started-with-fortanix-data-security-manager-ui)*.***
- During the Fortanix DSM Accelerator Webservice setup, supply the `.p12` file and its password so the Fortanix DSM Accelerator Webservice can extract the certificate and private key for mTLS-based authentication.

> [!NOTE]
> NOTE
> 
> - Currently, Fortanix DSM Accelerator Webservice does not perform Certificate Revocation List (CRL) checks when using certificate-based authentication for mTLS exports.
> - The certificate used by Fortanix DSM Accelerator Webservice can expire and is not auto-renewed. On expiry, key export attempts fail with a **403 error: "MTLS certificate in DSMA has expired"**. To resume operation, restart the service with a new valid certificate.
- Set the following environment variables when starting Fortanix DSM Accelerator Webservice:

Alternatively, you can use the following command-line arguments to configure the same settings:
  - `MTLS_EXPORTS_ENABLED`: Set to `true` to enable mTLS-based exports.
  - `MTLS_P12_FILE`: Path of the `.p12` file containing the certificate and the private key.
  - `MTLS_P12_PASSWORD`: Password to the `.p12` file.
  - `DSMA_APP_ID`: UUID of the Fortanix DSM app configured with certificate or Trusted CA authentication.
  - Use `--mtls-exports-enabled` to enable mTLS-based exports.
  - Use `--mtls-p12-file /path/to/your/pkcs12file` to specify the path to the PKCS#12 file.
  - Use `--mtls-p12-password your-pkcs12-password` to provide the password for the PKCS#12 file.
  - Use `--dsma-app-id dsm-app-uuid` to specify the UUID of the DSM app configured for certificate-based authentication.

### 7.7 Combined Authentication

The **Combined Authentication** feature in Fortanix DSM Accelerator Webservice helps make inbound connections more secure.

This feature enables Fortanix DSM Accelerator Webservice to authenticate client apps by combining two methods:

- Using a Mutual TLS (mTLS) client certificate
- Using an in-band credential such as an API key or JSON Web Token (JWT).

This indicates that the Fortanix DSM Accelerator Webservice validates the client’s identity at two levels to ensure that only trusted apps with valid certificates and credentials can access the Webservice:

- Network level: The mTLS client certificate is validated.
- Application level: The application’s configured authentication method is verified.

#### 7.7.1 Architecture and Authentication Flow

Refer to the following before enabling the combined authentication support in Fortanix DSM Accelerator Webservice:

- The Fortanix DSM Accelerator Webservice must be configured as a dedicated app in Fortanix DSM to establish its identity.
- When a client app in Fortanix DSM is configured with a Certificate, Trusted CA, or Combined authentication credential, Fortanix DSM issues a special type of token on `/auth` request that can be bound to another app’s certificate credential. This type of token is called an **app-bound token**. This allows the client apps to share an app-bound token (bound to Fortanix DSM Accelerator Webservice app) with Fortanix DSM Accelerator Webservice.
- Initially, the client app requests an app-bound token from Fortanix DSM to use it with Fortanix DSM Accelerator Webservice. The Fortanix DSM Accelerator Webservice then attaches its own certificate credential to support the received app-bound token.
- The Fortanix DSM Accelerator Webservice uses the same authentication method when exporting the security objects from Fortanix DSM.

#### 7.7.2 Configuration and Usage

Perform the following steps to configure and use the combined authentication feature in Fortanix DSM Accelerator Webservice:

1. Create an app in Fortanix DSM that is dedicated to Fortanix DSM Accelerator Webservice operations. This app serves as the identity for the Fortanix DSM Accelerator Webservice and is used to support app-bound tokens received from client applications.
2. Deploy Fortanix DSM Accelerator Webservice with the following parameters, either as **environment variables** or **CLI arguments**,****to enable combined authentication:

```bash
# as environment variables
-e DSMA_APP_ID="<dsma-app-uuid>"
-e USE_APP_BOUND_SESSION_TOKENS="true"
-e MTLS_CLIENT_CERT_AND_KEY_FILES="/path/to/cert /path/
to/private/key"
-e BEARER_AUTH_ENABLED="true"

# as CLI arguments
--dsma-app-id "<dsma-app-uuid>" \
--use-app-bound-session-tokens \
--mtls-client-files "/path/to/cert /path/to/private/key" \
--bearer-auth-enabled
```

Example:

```bash
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 TLS_CERT_AND_KEY_FILES="/path/to/cert /path/to/tls/private/key" \
-e FORTANIX_API_ENDPOINT=https://amer.smartkey.io \
-e PORT=PORT_NUMBER \
-e CACHE_TTL=1800 \
-e BEARER_AUTH_ENABLED="true" \
-e DSMA_APP_ID="<dsma-app-uuid>"\
-e USE_APP_BOUND_SESSION_TOKENS="true"\
-e MTLS_CLIENT_CERT_AND_KEY_FILES="/path/to/mtls/cert /path/to/mtls/private/key"\
dsma:VERSION
```

Where,
  - `BEARER_AUTH_ENABLED` (Optional): Enables Fortanix DSM Accelerator Webservice to accept bearer authentication from client applications. The default value is set to `false`.
  - `USE_APP_BOUND_SESSION_TOKEN` (Optional): Allows Fortanix DSM Accelerator Webservice to attach its app credentials to app-bound tokens in outgoing requests. The default value is set to `false`.
  - `DSMA_APP_ID` (Optional): The app UUID dedicated to Fortanix DSM Accelerator Webservice. This parameter is **mandatory** for SGX, Nitro, mTLS-based exports, and app-bound tokens.
  - `MTLS_CLIENT_CERT_AND_KEY_FILES` (Optional): Absolute paths (space-separated) to the mTLS client certificate and key files in the `.pem` format. This parameter is **mandatory** when using app-bound tokens.
3. Run the following commands so that the client app can request the app ID from Fortanix DSM Accelerator Webservice:

```bash
curl "https://<dsma_url>/accelerator/v1/app/info" -k`
```

Example Response:

```bash
{"app_id":"<dsma_app_id>","dsm_url":"<dsm_url>"}
```

Extract the Fortanix DSM Accelerator Webservice app ID and Fortanix DSM URL from the response.
4. Use the Fortanix DSM Accelerator Webservice app ID obtained in the previous step to request a session token bound to the Fortanix DSM Accelerator Webservice app:

```bash
curl -X POST https://<dsm_url>/sys/v1/session/auth \
   --cert "/path/to/client/mtls/cert/" --key "/path/to/client/mtls/key" \
   --header "Authorization: Basic <api_key>"  \
   --data '{"bind_to":{"app":"<dsma_app_id>"},"token_type":"Bearer"}'
```

Example Response:

```bash
{"token_type":"Bearer","expires_in":3600,"access_token":"<bearer_token>","entity_id":"<client_app_id>","allowed_mfa_methods":[]}
```
5. Fortanix DSM Accelerator Webservice supports the **CONNECT API**, enabling it to act as a secure proxy to Fortanix DSM. This ensures that mTLS authentication is preserved between the client and Fortanix DSM Accelerator Webservice.

A client application can send a proxied request to Fortanix DSM Accelerator Webservice using the CONNECT API as follows:

```bash
curl -x https://<dsma_url> \
  -X POST https://<dsm_url>/sys/v1/session/auth \
  --cert "/path/to/client/mtls/cert/" --key "/path/to/client/mtls/key" \
  --header "Authorization: Basic <api_key>" \ 
  --data '{"bind_to":{"app":"<dsma_app_id>"},"token_type":"Bearer"}'
```

Example Response:

```bash
{"token_type":"Bearer","expires_in":3600,"access_token":"<bearer_token>","entity_id":"<client_app_id>","allowed_mfa_methods":[]}
```
6. Use the Bearer token generated in the previous step to perform cryptographic operations. The client app extracts the **Bearer token** and uses it to send cryptographic requests to Fortanix DSM Accelerator Webservice. Fortanix DSM Accelerator Webservice then attaches its own certificate and private key to the request before forwarding it to Fortanix DSM. The Fortanix DSM accepts the request because the token is bound to the Fortanix DSM Accelerator Webservice app, whose credentials are included in the request. The subsequent requests will be served from cache.

**Example – Encrypt Request:**

```bash
# request body for encrypt request
encrypt_data=$(echo '{
    "alg":"AES",
    "key":{"name":"<key_name>"},
    "plain":"SGVsbG8gd29ybGQ=","mode":"CBC"
}')
# issue an encrypt request using the bearer token to the dsma host
curl -k -X POST https://<dsma_url>/crypto/v1/encrypt\
 --header "Authorization: Bearer <bearer_token>" \
 --data "$encrypt_data"
```

Example Response:

```bash
{"kid":"<kid>","cipher":"<cipher>","iv":"<iv>"}
```

### 7.8 Certificate Authentication

Fortanix DSM Accelerator Webservice supports certificate-based client application authentication, enabling client applications to authenticate using mTLS instead of API keys.

#### 7.8.1 Architecture and Authentication Flow

Certificate-based authentication relies on app-bound tokens issued by Fortanix DSM and bound to the Fortanix DSM Accelerator Webservice application identity.

Refer to the following before enabling the Certificate authentication support in Fortanix DSM Accelerator Webservice:

- The Fortanix DSM Accelerator Webservice must be configured as a dedicated app in Fortanix DSM to establish its identity.
- When a client app in Fortanix DSM is configured with Certificate, Trusted CA, or Combined authentication, Fortanix DSM issues a special token type on `/auth` requests. This token, called an **app-bound token**, can be bound to another application’s certificate credential.
- The client app initially requests an app-bound token bound to the DSM Accelerator Webservice app.
- The DSM Accelerator Webservice validates the token and attaches its own certificate credential to complete authentication.
- The same certificate-based authentication mechanism is used by the DSM Accelerator Webservice when exporting security objects from Fortanix DSM.

#### 7.8.2 Configuration and Usage

**Prerequisites**

- The client application is configured with Certificate, Trusted CA, or Combined authentication.
- mTLS certificates and private keys are available for both the client app and DSM Accelerator Webservice.

Perform the following steps to configure and use the certificate authentication feature in Fortanix DSM Accelerator Webservice:

1. Perform *Steps 1 to 3* from [*Section 7.7.2: Configuration and Usage*](/v1/docs/dsm-accelerator-webservice-developer-guide#772-configuration-and-usage).

> [!NOTE]
> NOTE
> 
> The environment variable `MTLS_CLIENT_CERT_AND_KEY_FILES` is mandatory when using certificate-based authentication with app-bound tokens.
2. Use the Fortanix DSM Accelerator Webservice app ID obtained in the previous step to request a session token bound to the Fortanix DSM Accelerator Webservice app:

```bash
curl -X POST https://<dsm_url>/sys/v1/session/auth \
   --cert "/path/to/client/mtls/cert/" --key "/path/to/client/mtls/key" \
   --user "<client_app_id>:" \
   --data '{"bind_to":{"app":"<dsma_app_id>"},"token_type":"Bearer"}'
```

Example Response:

```bash
{"token_type":"Bearer","expires_in":3600,"access_token":"<bearer_token>","entity_id":"<client_app_id>","allowed_mfa_methods":[]}
```
3. Fortanix DSM Accelerator Webservice supports the **CONNECT API**, enabling it to act as a secure proxy to Fortanix DSM.

With**Certificate Authentication**:

A client application can send a proxied request to Fortanix DSM Accelerator Webservice using the CONNECT API as follows:

```bash
curl -x https://<dsma_url> \
  -X POST https://<dsm_url>/sys/v1/session/auth \
  --cert "/path/to/client/mtls/cert/" \
  --key "/path/to/client/mtls/key" \
  --user "<client_app_id>:" \
  --data '{"bind_to":{"app":"<dsma_app_id>"},"token_type":"Bearer"}'
```

Example Response:

```bash
{"token_type":"Bearer","expires_in":3600,"access_token":"<bearer_token>","entity_id":"<client_app_id>","allowed_mfa_methods":[]}
```
  - API keys are used.
  - Authentication is performed exclusively using mTLS credentials.
4. Perform *Step 6* from [*Section 7.7.2: Configuration and Usage*](/v1/docs/dsm-accelerator-webservice-developer-guide#772-configuration-and-usage) to finalize the configuration.

## 8.0 Examples

The Fortanix DSM Accelerator Webservice APIs have the same data model as the DSM. *For information on request and response bodies for each API, refer to*[*Fortanix DSM REST API*](https://www.fortanix.com/fortanix-restful-api-references/dsm)*.*

This section provides some examples using curl that show how to call these APIs using Basic authentication.

In the following examples, replace `&lt;dsma_url&gt;` with the appropriate Fortanix DSM Accelerator URL. For example, `dsma.fortanix.com`.

### 8.1 Encryption and Tokenization Using Key Name

```bash
curl --location --request POST 'https://<dsma_url>/crypto/v1/encrypt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MDc.....TBSdEdn' \
--data-raw '{
  "key" : {
      "name" : "tokey1"
  },  
  "alg": "AES",
  "mode": "FF1 (or FPE)",
  "plain": "RmFpc2FsRmFydXF1aQ=="
}'
```

### 8.2 Encryption Using a Private Key with Key Name

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/encrypt' \
--header 'Authorization: Basic Njk0ZGIyMTgtZWFlNS00Y2VhLTh...wUEpheHFPMjVRa2FyTmotbnR2cmh1Ti1R' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "alg": "AES",
  "key": {
    "name": "DSMA-SO-f4r1cpesulm"
  },
  "plain": "testing123",
  "mode": "CBC"
}'
```

### 8.3 Batch Encryption Using Key Name

> [!NOTE]
> NOTE
> 
> The batch APIs (`crypto/v1/keys/batch`) support key lookup by `name`. To use this, include the **optional** key field (`SobjectDescriptor`) in the request, but the `kid` field is still **required**. If both are provided, the `key` field takes priority. You can use a dummy UUID for `kid` and specify the `key` field to use batch encrypt or decrypt by `name`.

In the following example, the first batch item uses `kid`, and the second batch item uses `key.name`

```bash
curl --location 'https://<dsma-url>/crypto/v1/keys/batch/encrypt' \
--header 'Authorization: Basic <api-key>' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '[
    {
        "kid": "c7fd4bdc-7deb-44b2-9d55-f9ffab6db691",
        "request": {
            "alg": "AES",
            "plain": "SGVsbG8gd29ybGQ=",
 "mode": "CBC"
        }
    },
    {
        "kid": "00000000-0000-0000-0000-000000000000",
        "request": {
            "alg": "AES",
            "key": {
                "name": "aes-ff1"           
            },
            "plain": "SGVsbG8gd29ybGQ=",
 "mode": "CBC"
        }
    }
]'
```

### 8.4 Decryption and Tokenization Using KID

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/decrypt' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MDc3ZjUzZTYtMjc3My00YmE.....dEdn' \
--data-raw '{
  "key" : {
      "kid" : "f07c3441-a846-4414-8f95-752e4a919b19"
  },  
  "alg": "AES",
  "mode": "FF1 (or FPE)",
  "cipher": "RVljVkVvS0NOMUJXRA=="
}'
```

### 8.5 Decryption Using a Private Key with Key Name

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/decrypt' \
--header 'Authorization: Basic NDZjOGIwODctMDQ1My00OTk5....5ajVjYmlMQzM2OHU3Unh2WDRQQ2FHMzgtY0tR' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "alg": "AES",
    "key": {
        "name": "DSMA-SO-4bunbmrs5uk"
    },
    "mode": "CBC",
    "cipher": "j+jMEw5gviLSSuLbWzueoQ==",
    "iv": "Y67JRBCCQsTsNjvpzZvV7g=="
}'
```

### 8.6 Signing Operation Using a Private Key with Key Name

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/sign' \
--header 'Authorization: Basic NDZjOGIwODctMDQ1My00OTk5LWE2OGEtNjAz...hzbGQ5ajVjYmlMQzM2OHU3Unh2WDRQQ2FHMzgtY0tR' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key": {
        "name": "RSA_SO-fvm872fngyh"
    },
    "data": "testing123",
    "hash_alg": "SHA224"
}'
```

### 8.7 Signing Operation Using a Private Key with KID in the API Endpoint

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/keys/<kid>/sign' \
--header 'Authorization: Basic NDUyN2NiN2MtN2QzNC00YWE3LWJlYWUtMDg5NzgdGNB.....tOXlSLTUzVkRn' \
--header 'Content-Type: application/json' \
--data-raw '{
    "hash_alg": "<hash_alg>",
    "data": "<data>"
}'
```

### 8.8 Signing Operation Using a Private Key with KID in the API Request

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/sign' \
--header 'Authorization: Basic NDUyN2NiN2MtN2QzNC00YWE3LWJlYWUtMDg5...UzVkRn' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key": {
        "kid": "<kid>"
    },
    "hash": "<hash_value>",
    "hash_alg": "<hash_alg>"
}'
```

### 8.9 Batch Signing Using a Private Key with Key Name

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/keys/batch/sign' \
--header 'Authorization: Basic NDZjOGIwODctMDQ1My00OTk5LWE2OGEtNjAzMGY1...HhzbGQ5ajVjYmlMQzM2OHU3Unh2WDRQQ2FHMzgtY0tR' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "key": {
            "name": "RSA_SO-fvm872fngyh"
        },
        "data": "testing123",
        "hash_alg": "SHA224"
    }
]'
```

### 8.10 Batch Signing Using a Private Key with KID in the API Request

```bash
curl --location --request POST 'https://<dsma_url>/crypto/v1/keys/batch/sign' \
--header 'Authorization: Basic NjI5ODY3ODgtMzBkYi00ODUzLWI0MjktZDMyZ....RWlDNEZFcXRR' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "key": {
            "kid": "<kid>"
        },
        "data": "<data>",
        "hash_alg": "SHA224"
    }
]'
```

### 8.11 Signature Verification Using a Private Key with Key Name

```bash
curl --location --request POST 'https://dsmatest.fortanix.com:8080/crypto/v1/keys/batch/verify' \
--header 'Authorization: Basic NjI5ODY3ODgtMzBkYi00ODUzLWI0MjktZDMyZWEzYzUwYTg5On...NHRxbDl5MjJBRWlDNEZFcXRR' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '[
{
"key": {
"kid": "<kid>"
},
"data": "<data>",
"signature": "<signature>",
"hash_alg": "SHA224"
}
]'
```

### 8.12 Signature Verification Using a Private Key with KID in the API Endpoint

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/verify' \
--header 'Authorization: Basic NDZjOGIwODctMDQ1My00OTk5LWE2OG...3TVA2THhzbGQ5ajVjYmlMQzM2OHU3Unh2WDRQQ2FHMzgtY0tR' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key": {
        "name": "RSA_SO-fvm872fngyh"
    },
    "data": "testing123",
    "signature": "h9O9cQ9uxzp/1BvpVZ+fLUMifSLQPnMaiRIbufrWfXJi5dGVgzUEKvn4K5BQH/xT2miiSQ8xuH1kLy3dia920XJnXI8zbkSrVF6lBWEFkJ9kr8co1/SsHIsQMZMB2eq9gi+n6tiLAsKbvkpjA5qgA2g8fS6HoJMMW6ZrVAP+FvjUJpHQlXSFrI7g8CskqCjoTl/urwvBnv1AW0i1EKBPwfkr87KKJkA/TN22XED+Bgrvm/pZLUU7DFbYc+w8J7FkkMmtwvKIQxBJYlJ5LVptGF9JTMm3GwqI243TbeGM0b8sylpxaWcLHLUuKlGP2Rl7eK0wzuvROO5XxeboKmzVVQ==",
    "hash_alg": "SHA224"
}'
```

### 8.13 Signature Verification Using a Private Key with KID in the API Request

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/keys/<kid>/verify' \
--header 'Authorization: Basic NDUyN2NiN2MtN2QzNC00YWE3LWJlYWUtMDg5NzgdGNB.....tOXlSLTUzVkRn' \
--header 'Content-Type: application/json' \
--data-raw '{
    "signature": "<signature>",
    "hash_alg": "<hash_alg>",
    "data": "<data>"
}'
```

### 8.14 Batch Signature Verification Using a Private Key with Key Name

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/verify' \
--header 'Authorization: Basic NDUyN2NiN2MtN2QzNC00YWE3LWJlYWUtMDg5NzgwZDQ4Y...SLTUzVkRn' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key": {
        "kid": "0b94c19f-c2f4-4f34-b55c-e2a6740a8867"
    },
    "hash": "<hash_value>",
    "signature": "<signature>",
    "hash_alg": "SHA512"
}'
```

### 8.15 Batch Signature Verification Using a Private Key with KID in the API Request

```bash
curl --location --request POST 'https://<dsma_url> /crypto/v1/keys/batch/verify' \
--header 'Authorization: Basic NDZjOGIwODctMDQ1My00OTk5LWE2OGEtNjAzMGY1NGFj...A2THhzbGQ5ajVjYmlMQzM2OHU3Unh2WDRQQ2FHMzgtY0tR' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "key": {
            "name": "RSA_SO-fvm872fngyh"
        },
        "data": "testing123",
        "signature": "h9O9cQ9uxzp/1BvpVZ+fLUMifSLQPnMaiRIbufrWfXJi5dGVgzUEKvn4K5BQH/xT2miiSQ8xuH1kLy3dia920XJnXI8zbkSrVF6lBWEFkJ9kr8co1/SsHIsQMZMB2eq9gi+n6tiLAsKbvkpjA5qgA2g8fS6HoJMMW6ZrVAP+FvjUJpHQlXSFrI7g8CskqCjoTl/urwvBnv1AW0i1EKBPwfkr87KKJkA/TN22XED+Bgrvm/pZLUU7DFbYc+w8J7FkkMmtwvKIQxBJYlJ5LVptGF9JTMm3GwqI243TbeGM0b8sylpxaWcLHLUuKlGP2Rl7eK0wzuvROO5XxeboKmzVVQ==",
        "hash_alg": "SHA224"
    }
]'
```

### 8.16 Authentication Using API Proxied to Fortanix DSM

```bash
curl --location --request POST 'https://<dsma_url> /sys/v1/session/auth' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MDc3ZjUzZTYtM....dEdn' \
--data-raw ''
```

### 8.17 Key Listing Using API Proxied to Fortanix DSM

```bash
curl --location --request GET 'https://<dsma_url> /crypto/v1/keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer kKjgN9...Q'
```

### 8.18 HMAC Key Generation Using a Key ID

```bash
curl --location --request POST 'https://<dsma_url>/crypto/v1/mac' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MDc3ZjUzZTYtMjc3My00YmE.....dEdn' \
--data-raw '{
  "key": {
      "kid": "f07c3441-a846-4414-8f95-752e4a919b19"
  },  
  "alg": "SHA256",
  "data": "Hello World"
}'
```

### 8.19 HMAC Key Verification Using a Key ID

```bash
curl --location --request POST 'https://<dsma_url>/crypto/v1/macverify' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic MDc3ZjUzZTYtMjc3My00YmE.....dEdn' \
--data-raw '{
  "key": {
      "kid": "f07c3441-a846-4414-8f95-752e4a919b19"
  },  
  "alg": "SHA256",
  "data": "Hello World",
  "mac": "af97ddbde25b.....b5fcbece9d7d46aa"
}'
```

### 8.20 Encryption Using an RSA Key

```bash
curl --location 'https: //<dsma_url>/crypto/v1/encrypt' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <app-api-key>' \
--data '{
"alg": "RSA",
"key": {
"kid": "<rsa-key-id>"
},
"mode": "PKCS1_V15",
"plain": "SGVsbG8gd29ybGQ="
}'
```

```bash
curl --location 'https: //<dsma_url>/crypto/v1/encrypt' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <app-api-key>' \
--data '{
"key": {
"kid": "<rsa-key-kid>",
},
"alg": "RSA",
"mode": "OAEP_MGF1_SHA512",
"label": "ds",           // Optional: only applicable for OAEP modes
"plain": "SGVsbG8gd29ybGQ="
}'
```

### 8.21 Decryption Using an RSA Key

```bash
curl --location 'https: //<dsma_url>/crypto/v1/decrypt' \
--header 'Authorization: Basic <app-api-key>' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"alg": "RSA",
"key": {
"kid": "<rsa-key-id>"
},
"mode": "PKCS1_V15",
"cipher": "{{cipher}}"
}'
```

```bash
curl --location 'https: //<dsma_url>/crypto/v1/decrypt' \
--header 'Authorization: Basic <app-api-key>' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"key": {
"kid": "<rsa-key-id>"
},
"alg": "RSA",
"mode": "OAEP_MGF1_SHA512",
"label": "ds",         // Optional: only applicable for OAEP modes
"cipher": "{{cipher}}"
}'
```

## 9.0 Troubleshooting

| **Problem** | **Solution** |
| --- | --- |
| DSM Accelerator 1.8.2276 (4.20 Release) is crashing while in a quiescent state. | Verify and set Linger mode on the service user account. 1. Run the following command to verify Linger mode: ```bash loginctl show-user <service account user> ``` 2. Run the following command to set Linger mode: ```bash loginctl enable-linger <service account user> ``` > [!NOTE] > NOTE > > For Amazon Web Service (AWS) RHEL 8.6 installation, it is necessary to configure Linger mode to ensure proper operation. However, in other installations, Linger mode is not required. Fortanix recommends setting Linger mode as a precautionary measure. |

Fortanix Data Security Manager (DSM) is the world’s first cloud service secured with Intel® SGX. With Fortanix DSM, you can securely generate, store, and use cryptographic keys and certificates, as well as other secrets such as passwords, API keys, tokens, or any blob of data. Your business-critical applications and containers can integrate with Fortanix DSM using legacy cryptographic interfaces (PKCS#11, CNG, and JCE) or using the native Fortanix DSM RESTful interface.