Clients: Microsoft CNG Key Storage Provider

  • Updated on Mar 12, 2025
  • Published on Jun 19, 2024
  • 7 minute(s) read
Prev Next

1.0 Download

The Microsoft Cryptographic Next Generation (CNG) Key Storage Provider (KSP) for Windows 64-bit can be downloaded here.

2.0 Installation

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

The Fortanix KMS 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. To display all registered cryptographic service providers on the system, run

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:

3.0 Operating System Compatibility Matrix

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

4.0 Uninstallation

Uninstall FortanixKmsClient.msi (click Uninstall from the context menu or uninstall using Windows’s Programs and Features manager).

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

Fortanix-Data-Security-Manager (DSM) supports certificate-based authentication or API key-based authentication for a CNG client.

5.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, to configure the Fortanix KMS Server URL for the local machine, run:

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

To configure the Fortanix KMS Server URL for the current user, run:

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 or --proxy none to unconfigure proxy.

The CNG 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 Data Security Manager. Then, it may be configured for the machine key store:

FortanixKmsClientConfig.exe machine --api-key

or the user key store:

FortanixKmsClientConfig.exe user --api-key

certutil maybe used to verify that the Fortanix KMS CNG Provider is configured correctly. To list the keys in the machine key store, run:

certutil -csp "Fortanix KMS CNG Provider" -key

To list the keys in the user key store for the current user, run:

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

5.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, to configure the Fortanix KMS Server URL for the local machine, run:

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

To configure the Fortanix KMS Server URL for the current user, run:

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

To configure the certificate, private key, and app ID:

  • For the machine key store:

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

  • For the user key store:

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

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

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

7.0 Quorum Policy Approval Configuration

You can use 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

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

8.0 Troubleshooting

8.1 Logging

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

or

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.

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

Related articles