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. 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

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.

For information on Fortanix DSM Accelerator Webservice deployment and installation, refer to DSM Accelerator Webservice Deployment.

3.0 Supported Features

4.0 Supported Algorithms and Modes

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

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

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

  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

  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

  • 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.  

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

• 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:    

  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.    

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

  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:

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

  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.

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:    

   WRAPPED_EXPORTS_ENABLED=true

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

   --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

   You must specify a value for UNWRAPPING_KEYS if WRAPPED_EXPORTS_ENABLED is set to true.  

   • Using environment variables:

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

     Or

     UNWRAPPING_KEYS="file <file-1-path> <file-2-path> ...."

   • Using command line arguments:

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

     Or

     --unwrapping-keys "file <file-1-path> <file-2-path> ..."

   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:    

   [
       {
           "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": "MIIG4gIBAAKCAYEArgATnIEtv6Kf6+lBwJ+lWPv4XqV4yNR3MAr8VHjhbsBi1E6Pbh9cbU35sfUPb6JkaCLFuiejGqQxWUfhXhGIOz0k3R7ss4tY9TaZPI6zTVn6KbtD2ky8IqeQqPrMBFb6xtSMWk9UZtgjM+breqtMO1s77IfUvyk9DFTjbn8YAeM0VdWv396WMO4A7LhLGonCTfYji3uniGrJUkIxkEpcBOfiKV1XlTxN/DwZM146PoWQd7JjttjCeHPUzUSlAht/6UdiECnd3JiPtokRwVhNTu9dFgEl2bkRjdvcTr/kzghkKZfjeCoVNrDwta1tPs0I5hl8a8znZHEsiAsekmzj7RHYeosnqwJTCj47z7fBwRaCjrPbDUslkh317b52FscmR1Eje/DYImXpRZN4WgvTZhQji/+ubzzl7M21eAjOp+n8OWBH1zj/OHXLzU/OM5H21VKCtFqauiJFDu/doKRRpjW14f2iUY2DlO0JG92FexdoyBJd4x8JHIKezJBf7PtlAgMBAAECggGAA5D6Veya4rDjXLs67wcGpVCCynPTSjB6oegzvEp++l1kmSvkCjKH2zCsM77NWnEmZDEEQvjBgdAIN+d+gcZTt70c1pBl8xch02LTWLenCqiTtUvCjASjHYW4NBJx4Ivk13LvToGOPg5jiFKNFIZSyWupCoPNMz7V4r0RrUfbFtzQi4rV8D14cBfMuo1bcreMnTr0hw0ZhbUEm9RB/k5b3PjgvI7Odv9VrNwReylNAc+MgruMCikesUfUfoGP7T9hgti1n1Wq2nAWS3HMTrLSQYTDO3YDPeifOSXw3djoBUpseURxPxWbmJjkc6JKOALJy49/GkyYk7h49rBn2Q/bRXgDPmy3LIpo3TvYg8lnV3bRRC2XMlMQFcp/zF7sP8rrTXpmJ2ZeGS+L0OVLdxIjjN2sh01Y8PFte6K6pttVBrHSAvqjqvZji0EKsW1oOwFKZXepMxWECp2qIwhoma1iqsXZOY5x7RTDQ4r7ISJSPsnzey7oWhPGp6DKjnc02kJxAoHBAOVuLgi0LXZOYfwS1j6AVDoEGUN7zUC23146BoPezBZWpbcs2msxStGDWVSiSHuQXmuGJcLCAz2c3MXYupmkW5Mhud6cN1WnwgJ2dFK17Jv5DEwdTRlKG5sq5SpysKE4Ru8GcMXVg0nRlVoTCBshcJRllRyixTO5xEnObuBMdECso3eqAT10R/uN/wb50fUemCq7OCLUFbvBUdmb5gdLgQTQpQ8AGEMY4JzrV4+JU2WNrzza82mkaPQF7oi9ZK+p8QKBwQDCJpXuuVuR/f8f+h1+uLni72jxfdO6n+zz/wb0nMxBo5cmiNvgpDucHZ7m7erQ3L6dNLsWr1cDOoYjnAOLEGn8l/t1ZVHEfr9o7/4QoP4Aosc1/UE2UzJ9xULQyQJC+VefPs8lf4fREk1zgkaIprTExloHhOMUFi4PZfHo+YE6uGBGeLy+EEfQr5aPVW5fOhIlXOTALVnBBP5R2+wlzxnhGBIg9DQ93+qeAUeP9Zgq8OvhML0kgKHkRNALE2KjFLUCgcA8t6v3IbfmV1gXHeUVJWEk+XC2K01mkv8KMNEIlS3tu4CfuX8UXzctu1Uo0Mnd6ZcTXa0gnbe91oWW1oSLpLOXfJV0FGOQh5UQkci3Gu5DWOWoPxjoWHR13CRJ15BnGj2rhEjUEm1sW8rqy56Zj3/7xeZwbaNCzSblYXx2X8VkWEvqn1M0sFFcgXe8oOCvvikHJgT1MquNxNuke12lEJZUb+M+1QeWuj63SJEjq3QmrBh0Qn2ot5oO+oLmLTk4RAECgcBa+iXL5cPJF5KTc2qa1QkWFEXC08mBbCtm8pxZx5fXMkdD4WHXVF4ye5bYc6hTEv2nQOxiZuuJMcVlrlfitGBV4woMKtw0DYi4La2KMUaVGbHr1K7YPAgu816p42dR5vFuR8pdsfL8v2zXsbZHloaipqfNWjHmWbZftM+08iXiVD+ZBj67eXmNipostEWyDc4u/+aZPycN0b8ysLFpzjA8UEE+e/B3BhQ00jisdtNFW/vMXEBleHlkM/KhHgZckPkCgcBIsBEGlwoOsXZ9lo4MUgpWaKAonqcX5ZY7UuZS/tTXEumVQrfMRCIa/yHfftbi5Blt8PwZwZhxqqEcsDCC0VXSquG7Sfc0hno9S6rXS8HagI8XBI1AQfLFq/iv4OLO313gn/pe9ETnw1RsGnU2krW/xvBCReQVibyG1fUKogKHqDQ/vwBl/oJCwVzQnJs3xC80NkZVjYEYyVbPlORA97owrMTr3cgq0XSk5S+nRcrheahnHP/DRwX8K0BYMleRdc4="
       }
   ]

   • 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:

<path/to/cert> <path/to/key>

Example:

"/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:

"/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

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.  

• 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

  • 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:    

  • 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.      

  Alternatively, you can use the following command-line arguments to configure the same settings:    

  • 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:    

   # 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:

   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:    

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

   Example Response:

   {"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:    

   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:

   {"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:    

   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:

   {"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:    

   # 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:

   {"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.    

   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:    

   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:

   {"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:    

   • API keys are used.

   • Authentication is performed exclusively using mTLS credentials.      

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

   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:

   {"token_type":"Bearer","expires_in":3600,"access_token":"<bearer_token>","entity_id":"<client_app_id>","allowed_mfa_methods":[]}

4. Perform Step 6 from Section 7.7.2: 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.

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

In the following examples, replace <dsma_url> with the appropriate Fortanix DSM Accelerator URL. For example, dsma.fortanix.com.

8.1 Encryption and Tokenization Using Key Name

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

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

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

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

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

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"
}'

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>"
}'

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>"
}'

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"
    }
]'

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"
    }
]'

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"
}
]'

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

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

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

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

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

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

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

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

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="
}'

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

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}}"
}'

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