Clients: Microsoft CNG Key Storage Provider

1.0 Introduction

This article provides an overview of the Fortanix-Data-Security-Manager (DSM) Microsoft Cryptographic Next Generation (CNG) Provider, including its installation, configuration, features, supported operations, and platform compatibility.

2.0 Download

Download the Microsoft CNG Key Storage Provider (KSP) for Windows 64-bit here.

3.0 Installation

FortanixKmsClient.msi installs the Fortanix CNG Provider, as well as an Enterprise Key Management (EKM) provider and PKCS#11 library.

The Fortanix CNG Provider is installed at C:\Windows\System32\FortanixKmsCngProvider.dll and is registered with Windows during installation.

The certutil command on Windows can be used to verify that the CNG provider is registered.

Run the following command to display all registered cryptographic service providers on the system:

certutil -csplist

You should be able to locate Fortanix KMS CNG Provider in this list.

For information on CyberArk, SQL Server, and MS PKI, refer to the following articles:

4.0 Operating System Compatibility

For information on the Fortanix CNG Provider client OS compatibility matrix, refer to Clients: Compatibility Matrix.

5.0 Uninstallation

Uninstall FortanixKmsClient.msi using any of the following methods:

Click Uninstall from the context menu.
Using the 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\FortanixKmsClientConfig.ex

Fortanix DSM supports certificate-based authentication or API key-based authentication for the Fortanix CNG Provider 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:

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

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

FortanixKmsClientConfig.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, use --proxy none.

Run the following command to set the proxy:

FortanixKmsClientConfig.exe machine --proxy <proxy URL>

Example:

FortanixKmsClientConfig.exe machine --proxy http://proxy.com:3128

The Fortanix CNG Provider client does not provide an API for logging in with a credential, so the API key for the Fortanix KMS CNG 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 DSM. For more information on adding an application to Fortanix DSM, refer to the User's Guide: Getting Started with Fortanix Data Security Manager - UI.

Then, configure it for the following:

Machine key store

FortanixKmsClientConfig.exe machine --api-key

User key store:

FortanixKmsClientConfig.exe user --api-key

certutil may be used to verify that the Fortanix KMS CNG Provider is configured correctly.

Run the following command to list the keys in the machine key store:

certutil -csp "Fortanix KMS CNG Provider" -key

Run the following command to list the keys in the user key store for the current user:

certutil -csp "Fortanix KMS CNG Provider" -key -user

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:

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

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

FortanixKmsClientConfig.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 CNG 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 CNG 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 there is 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; the CNG provider cannot authenticate with Fortanix DSM.

Run the following commands to configure the certificate, private key, and app ID:

Machine keystore:

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

User keystore:
```
FortanixKmsClientConfig.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:

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

NOTE
Since FortanixKmsClientConfig.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 key is always exportable, you must enable the EXPORT key operation during key creation.

Use the following commands to enable the EXPORT key operation when creating a key from CNG/EKM/CSP:

For machine context:

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

For user context:

FortanixKmsClientConfig.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 CNG/EKM/CSP.

NOTE
If --add-key-ops-override is enabled but no longer needed, you can disable it by setting --disable-add-key-ops-override to true. To re-enable it, set --disable-add-key-ops-override to false.
Example:
FortanixKmsClientConfig.exe user --disable-add-key-ops-override true
If the cryptographic policy on the Fortanix DSM account disallows the EXPORT operation, the key creation request in CNG/EKM/CSP will result in the error: Some requested operations (EXPORT) is not allowed by policy.

6.4 Verify Server Certificate Chain Revocation

The --check-server-cert-revocation parameter enables verification of the revocation status of the Fortanix DSM server certificate chain. When enabled, the Fortanix CNG/EKM client validates the DSM server certificate and its trust chain using supported revocation mechanisms (CRL and/or OCSP) during TLS connection establishment.

Use the following commands to verify the server certificate chain revocation in CNG/EKM/CSP:

For machine context:

FortanixKmsClientConfig.exe machine --check-server-cert-revocation true

For user context:

FortanixKmsClientConfig.exe user --check-server-cert-revocation true

NOTE
Server certificate revocation check details are available when the log level is set to debug.

7.0 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 the Fortanix CNG Provider client, the default retry timeout is 60 seconds, and in the EKM provider, it is 30 seconds.

For machine context:

FortanixKmsClientConfig.exe machine --retry-timeout xxxx

For user context:

FortanixKmsClientConfig.exe user --retry-timeout xxxx

8.0 Quorum Policy Approval Configuration

Run the following commands to configure the CNG provider to manage operations that need quorum approval:

For machine context:

FortanixKmsClientConfig.exe machine --wait-for-quorum-approval true
FortanixKmsClientConfig.exe machine --poll-interval-for-quorum-status-secs 10
FortanixKmsClientConfig.exe machine --max-wait-for-quorum-response-secs 100

For user context:

FortanixKmsClientConfig.exe user --wait-for-quorum-approval true
FortanixKmsClientConfig.exe user --poll-interval-for-quorum-status-secs 10
FortanixKmsClientConfig.exe user --max-wait-for-quorum-response-secs 100

Where,

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 CNG/EKM/CSP Provider

If any issues or failures occur during the operations mentioned above, the Fortanix CNG/EKM/CSP 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 CNG/EKM/CSP 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:

FortanixKmsClientConfig.exe machine cng --log-file  /path/to/log/file
FortanixKmsClientConfig.exe machine cng --log-level  info
FortanixKmsClientConfig.exe machine cng --max-log-files 5
FortanixKmsClientConfig.exe machine cng --log-file-size-kb 1024

For user context:

FortanixKmsClientConfig.exe user cng --log-file  /path/to/log/file
FortanixKmsClientConfig.exe user cng --log-level  info
FortanixKmsClientConfig.exe user cng --max-log-files 5
FortanixKmsClientConfig.exe user cng --log-file-size-kb 1024

NOTE
For EKM and CSP providers, replace cng with ekm and csp in the commands above, respectively.

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

9.1.2 PKCS#11

The log file location can also be configured for Windows PKCS#11 clients by adding the following to your client configuration file:

api_key = "FEL/ME...j+bt7"
api_endpoint = "<ENDPOINT URL>" or "<ENDPOINT IP>"  # default is "https://apps.smartkey.io"

[log]
system = true      # Unix only, logs to syslog
file = "/path/to/log/file"

10.0 Changelog

For a complete list of updates and changes in the CNG/EKM/CSP provider, refer to the CNG/EKM Changelog.