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.

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:

4.0 Operating System Compatibility

For information on the Fortanix DSM Accelerator EKM OS compatibility matrix, refer to 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:

FortanixKmsDsmaClientConfig.exe machine --api-endpoint https://amer.smartkey.io

Run the following command to configure the Fortanix KMS Server URL for the current user:

FortanixKmsDsmaClientConfig.exe user --api-endpoint https://amer.smartkey.io

The API endpoints for other regions are:

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.

Then, it may be configured for:

The machine key store:

FortanixKmsDsmaClientConfig.exe machine --api-key

The user key store:

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:

FortanixKmsDsmaClientConfig.exe machine --api-endpoint https://amer.smartkey.io

Run the following command to configure the Fortanix KMS Server URL for the current user:

FortanixKmsDsmaClientConfig.exe user --api-endpoint https://amer.smartkey.io

The API endpoints for other regions are:

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:

FortanixKmsDsmaClientConfig.exe machine --app-id <id> --client-cert <cert-file> --client-key <key-file>

For the user key store:
```
FortanixKmsDsmaClientConfig.exe user --app-id <id> --client-cert <cert-file> --client-key <key-file>
```
Where, cert-file and key-file are the paths to the client certificate and key, respectively.
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:

FortanixKmsDsmaClientConfig.exe machine --app-id
FortanixKmsDsmaClientConfig.exe machine --client-cert <cert-file>
FortanixKmsDsmaClientConfig.exe machine --client-key <key-file>

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:

FortanixKmsDsmaClientConfig.exe machine --add-key-ops-override EXPORT

For user context:
```
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
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:

FortanixKmsDsmaClientConfig.exe machine --cache-ttl <milliseconds>

For user context:

FortanixKmsDsmaClientConfig.exe user --cache-ttl <milliseconds>

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:

FortanixKmsDsmaClientConfig.exe machine --availability true

For user context:

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:

FortanixKmsDsmaClientConfig.exe machine --retry-timeout xxxx

For user context:

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:

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:

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

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

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:

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