Clients: Microsoft CNG Key Storage Provider

Download

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

Installation

FortanixKmsClient.msi installs the Fortanix CNG Provider, as well as an 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 Using Fortanix Data Security Manager with Microsoft PKI Using Fortanix Data Security Manager with Microsoft SQL Server TDE  Using Fortanix Data Security Manager with CyberArk Enterprise Password Vault.

Uninstallation

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

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 DSM supports certificate-based authentication or API key-based authentication for a CNG client.

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://sdkms.fortanix.com

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

FortanixKmsClientConfig.exe user --api-endpoint https://sdkms.fortanix.com

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

or the user key store:

FortanixKmsClientConfig.exe user --api-key <key>

certutil may be 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

Certificate-Based Authentication

• In order to use certificate-based authentication, you must specify a client certificate, its corresponding private key, and the app ID. (All three are needed in order 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 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 API key is used if present.
  • If 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>

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 of 6000 sets the retry limit to 6 secs. 

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

Troubleshooting

Logging

In case of any issues or failures during the above operations, the Fortanix CNG provider writes error logs to a file that can be located in the Windows folder:

C:\Windows\System32\config\systemprofile\AppData\Roaming\Fortanix

or

C:\Users\Administrator\AppData\Roaming\Fortanix