--- title: "DSM Accelerator EKM Developer Guide" slug: "dsm-accelerator-ekm-developer-guide" updated: 2026-06-11T09:52:33Z published: 2026-06-11T09:52:33Z --- > ## 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 EKM Developer Guide ## 1.0 Introduction Fortanix-Data-Security-Manager (DSM), together with the Fortanix DSM Accelerator, provides a powerful solution for integrating with Microsoft SQL Server Extensible Key Management (EKM). Fortanix DSM enables you to securely generate, store, and manage cryptographic keys, certificates, and secrets such as passwords, API keys, tokens, or any sensitive data. Fortanix DSM can be deployed in SaaS, on-premises, or cloud-native environments, and scaled across geographically distributed clusters to meet enterprise security requirements. While Fortanix DSM ensures centralized key management and robust security controls, Microsoft SQL Server workloads that use EKM often require very high performance with low latency and high throughput. The Fortanix DSM Accelerator for EKM addresses this by offloading and accelerating cryptographic operations, enabling organizations to meet stringent performance SLAs while continuing to enforce centralized control and security policies through Fortanix DSM. This article describes the **Fortanix DSM Accelerator EKM configurations, installations, and supported features**. ## 2.0 Downloads The latest version of the Fortanix DSM Accelerator EKM can be downloaded [*here*](https://fortanix.zendesk.com/hc/en-us/articles/40609786404500-DSM-Accelerator-EKM). ## 3.0 Installation `FortanixKmsDsmaClient.msi` installs the Fortanix DSM EKM provider. The Fortanix DSM Accelerator EKM is installed at `C:\Program Files\Fortanix\KmsDsmaClient` and is registered with Windows during installation. *For information on Cyberark, SQL Server, and MS PKI, refer to the following:* - [*Fortanix DSM with CyberArk Enterprise Password Vault*](/v1/docs/using-fortanix-data-security-manager-with-cyberark-enterprise-password-vault) - [*Fortanix DSM with Microsoft SQL Server TDE*](/v1/docs/using-fortanix-data-security-manager-with-microsoft-sql-server-tde) - [*Fortanix DSM with Microsoft PKI*](/v1/docs/using-fortanix-data-security-manager-with-microsoft-pki) ## 4.0 Operating System Compatibility *For information on the Fortanix DSM Accelerator EKM OS compatibility matrix, refer to*[*DSM Accelerator - Compatibility Matrix*](https://support.fortanix.com/docs/dsm-accelerator-compatibility-matrix)*.* ## 5.0 Uninstallation Uninstall `FortanixKmsDsmaClient.msi` using any of the following: - Click **Uninstall** from the context menu. - Windows’ Programs and Features manager. ## 6.0 Configuration The Fortanix Key Management Service (KMS) Server URL and proxy information are configured in the Windows registry for the local machine or current user with: `C:\Program Files\Fortanix\KmsClient\FortanixKmsDsmaClientConfig.exe` Fortanix DSM supports certificate-based authentication or API key-based authentication for an EKM client. ### 6.1 API Key-Based Authentication The machine key store uses the local machine configuration, and the user key store uses the current user configuration. For example, run the following command to configure the Fortanix KMS Server URL for the local machine: ```bash FortanixKmsDsmaClientConfig.exe machine --api-endpoint https://amer.smartkey.io ``` Run the following command to configure the Fortanix KMS Server URL for the current user: ```bash FortanixKmsDsmaClientConfig.exe user --api-endpoint https://amer.smartkey.io ``` The API endpoints for other regions are: - [https://uk.smartkey.io](https://uk.smartkey.io/) - [https://eu.smartkey.io](https://eu.smartkey.io/) - [https://apac.smartkey.io](https://apac.smartkey.io/) - [https://au.smartkey.io](https://au.smartkey.io/) To configure proxy information, add `--proxy http://proxy.com`. To unconfigure the proxy, add `--proxy none`. The EKM does not provide an API for logging in with a credential, so the API Key for the Fortanix KMS EKM Provider is stored in the Windows registry, encrypted using the Windows Data Protection API. The API key needs to be generated ahead of time by adding an application to Fortanix Data Security Manager. *For more information on adding an application, refer to*[*Getting Started with Fortanix DSM - UI*](/v1/docs/users-guide-getting-started-with-fortanix-data-security-manager-ui)*.* Then, it may be configured for: - The machine key store: ```bash FortanixKmsDsmaClientConfig.exe machine --api-key ``` - The user key store: ```bash FortanixKmsDsmaClientConfig.exe user --api-key ``` ### 6.2 Certificate-Based Authentication The machine key store uses the local machine configuration, and the user key store uses the current user configuration. For example, run the following command to configure the Fortanix KMS Server URL for the local machine: ```bash FortanixKmsDsmaClientConfig.exe machine --api-endpoint https://amer.smartkey.io ``` Run the following command to configure the Fortanix KMS Server URL for the current user: ```bash FortanixKmsDsmaClientConfig.exe user --api-endpoint https://amer.smartkey.io ``` The API endpoints for other regions are: - [https://uk.smartkey.io](https://uk.smartkey.io/) - [https://eu.smartkey.io](https://eu.smartkey.io/) - [https://apac.smartkey.io](https://apac.smartkey.io/) - [https://au.smartkey.io](https://au.smartkey.io/) To use certificate-based authentication, you must specify a client certificate, its corresponding private key, and the app ID. (All three are needed for the EKM client to authenticate with Fortanix DSM.) Once specified, these will be added to the Windows registry, encrypted using the Windows Data Protection API. - The app in question should already be set up to use client-based authentication, for example, by creating an app using Fortanix DSM UI and specifying "**Certificate**" as the authentication method. - The client certificate should be a PEM-formatted X.509 certificate, and the private key should be a PEM-formatted unencrypted PKCS #8 key. (Encrypted PKCS #8 keys, or keys not in PKCS #8 format, are not supported.) - The EKM provider is designed so that it will first attempt to use certificate-based authentication if possible and will then attempt authentication using an API key (if an API key exists). Here are some example scenarios: - If only the API key is present in the registry, then the API key is used. - If the certificate, private key, and app ID are in the registry, then certificate-based authentication is used. - If the certificate and private key are in the registry, but no app ID, then an API key is used if present. - If a certificate, private key, and an invalid app ID are in the registry, then certificate-based authentication is attempted, fails (due to the invalid app ID), and then API key authentication is tried next (presuming an API key exists). - Nothing is in the registry, and the EKM provider cannot authenticate with Fortanix DSM. Run the following commands to configure the certificate, private key, and app ID: - For the machine key store: ```bash FortanixKmsDsmaClientConfig.exe machine --app-id --client-cert --client-key ``` - For the user key store: ```bash FortanixKmsDsmaClientConfig.exe user --app-id --client-cert --client-key ``` Where, `cert-file` and `key-file` are the paths to the client certificate and key, respectively. > [!NOTE] > NOTE > > When you store the cert and key in the registry, you store the contents of the files, not the file paths themselves. You can also specify the client certificate, private key, and app ID one at a time. Example: ```bash FortanixKmsDsmaClientConfig.exe machine --app-id FortanixKmsDsmaClientConfig.exe machine --client-cert FortanixKmsDsmaClientConfig.exe machine --client-key ``` > [!NOTE] > NOTE > > Since `FortanixKmsDsmaClientConfig.exe` will attempt to test out the configuration each time it has been modified, the first two commands above (that is, setting the app ID and certificate) may result in warnings about certiticate-based authentication not being configured properly, since you have not finished setting up certificate-based authentication. ### 6.3 Enable the Export Key Operation During Key Creation To ensure the caching works, the key should always be exportable, you must enable the `EXPORT` key operation during key creation. Run the following commands to enable the `EXPORT` key operation when creating a key from EKM: - For machine context: ```bash FortanixKmsDsmaClientConfig.exe machine --add-key-ops-override EXPORT ``` - For user context: ```bash FortanixKmsDsmaClientConfig.exe user --add-key-ops-override EXPORT ``` The `--add-key-ops-override` parameter ensures that the `EXPORT` key operation is always included during key creation from EKM. > [!NOTE] > NOTE > > If the cryptographic policy on the Fortanix DSM account disallows the `EXPORT` operation, the key creation request in EKM will result in the error: `Some requested operations (EXPORT) is not allowed by policy`. ### 6.4 Configure Cache Expiration You can configure how long a cached key remains valid by setting the cache expiration time. By default, the cache expiry is 1 hour (3600 ms). - For machine context: ```bash FortanixKmsDsmaClientConfig.exe machine --cache-ttl ``` - For user context: ```bash FortanixKmsDsmaClientConfig.exe user --cache-ttl ``` ### 6.5 Configure Availability of Cached Key The `availability` setting ensures that cached keys continue to be accessible during network disruptions or temporary connectivity issues with the Fortanix DSM service, allowing applications to run smoothly without interruption. When enabled (`--availability true`), the client will re-cache an already cached key after its expiry time, instead of discarding it. This allows applications to continue functioning without immediately depending on Fortanix DSM: - For machine context: ```bash FortanixKmsDsmaClientConfig.exe machine --availability true ``` - For user context: ```bash FortanixKmsDsmaClientConfig.exe user --availability true ``` ## 7.0 Configure Retry Timeout You can configure the retry timeout parameter. To configure the error, retry limit, run the following commands, where `xxxx` is the value of time in milliseconds. This is the maximum duration for which the library will do any number of retries in case of API failures from the service. For example, the retry time `6000` sets the retry limit to 6 seconds. In EKM, the default retry timeout is 30 seconds. - For machine context: ```bash FortanixKmsDsmaClientConfig.exe machine --retry-timeout xxxx ``` - For user context: ```bash FortanixKmsDsmaClientConfig.exe user --retry-timeout xxxx ``` ## 8.0 Configure Quorum Policy Approval Run the following commands to configure the EKM provider to manage operations that need quorum approval: - For machine context: ```bash FortanixKmsDsmaClientConfig.exe machine --wait-for-quorum-approval true FortanixKmsDsmaClientConfig.exe machine --poll-interval-for-quorum-status-secs 10 FortanixKmsDsmaClientConfig.exe machine --max-wait-for-quorum-response-secs 100 ``` - For user context: ```bash FortanixKmsDsmaClientConfig.exe user --wait-for-quorum-approval true FortanixKmsDsmaClientConfig.exe user --poll-interval-for-quorum-status-secs 10 FortanixKmsDsmaClientConfig.exe user --max-wait-for-quorum-response-secs 100 ``` Here, - `wait-for-quorum-approval` is the boolean parameter to approve the quorum policy associated with the Fortanix DSM group. By default, the value is `false`. You can set it to `true` to enable quorum policy approval. - `poll-interval-for-quorum-status-secs` is the time gap between each quorum status check-in. The polling interval must not surpass 600 seconds (10 minutes). The default value is 5 seconds. - `max-wait-for-quorum-response-secs` is the maximum duration for the client library to await a response from the server in seconds. The default value is 120 seconds. ## 9.0 Troubleshooting ### 9.1 Logging #### 9.1.1 EKM Provider If any issues or failures occur during the operations mentioned above, the Fortanix EKM provider logs errors to the default file located in the Windows folder: `C:\Windows\System32\config\systemprofile\AppData\Roaming\Fortanix` or `C:\Users\Administrator\AppData\Roaming\Fortanix` The location of the custom log file and additional logging details can be configured for the EKM provider using the following commands: > [!NOTE] > NOTE > > The following additional logging parameters can be set either at the machine or user context. If both user and machine logging parameters are configured, the machine context parameters take precedence. > > - `log-file` > - `log-level` > - `max-log-files` > - `log-file-size-kb` For machine context: ```bash FortanixKmsDsmaClientConfig.exe machine ekm --log-file  /path/to/log/file FortanixKmsDsmaClientConfig.exe machine ekm --log-level  info FortanixKmsDsmaClientConfig.exe machine ekm --max-log-files 5 FortanixKmsDsmaClientConfig.exe machine ekm --log-file-size-kb 1024 ``` For user context: ```bash FortanixKmsDsmaClientConfig.exe user ekm --log-file  /path/to/log/file FortanixKmsDsmaClientConfig.exe user ekm --log-level  info FortanixKmsDsmaClientConfig.exe user ekm --max-log-files 5 FortanixKmsDsmaClientConfig.exe user ekm --log-file-size-kb 1024 ``` Here, - `log-file`: Specifies the custom log file path. - `log-level`: Determines the log level. The valid values are `debug, info, error, warn,` and `trace`. The default is `info`. - `max-log-files`: Defines the maximum number of log files. After log rotation, the logs are archived in these files. The default value is 5. - `log-file-size-kb`: Sets the maximum size of the log file in kilobytes (KB). Once the size limit is reached, log rotation occurs. The default value is 1024 KB. > [!NOTE] > NOTE > > - Automatic log rotation is enabled only when using a custom log file location. By default, logs are rotated every 1MB, and 5 copies of the log are retained. To configure the log rotation, include the following additional parameters in your EKM provider setup: > - `max-log-files` > - `log-file-size-kb` > - If you are using the Encryption Key Management (EKM) provider, ensure that the Microsoft SQL Server Transparent Data Encryption (TDE) integration has the necessary file permissions to modify the location of the custom log file. 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.