Using Fortanix Data Security Manager with CyberArk Enterprise Password Vault

1.0 Overview

The CyberArk Privilege Account Security Solution seamlessly integrates with the Fortanix Data Security Manager (DSM) to enhance the security and accessibility of encryption keys. This document provides essential information for deploying the Fortanix DSM service in conjunction with the CyberArk Enterprise Password Vault (EPV®) solution. For more information, refer to the Integration Guide available in the Resources section.

2.0 Prerequisites

Before proceeding, ensure to include the following in the Windows environment variables. For a comprehensive list of prerequisites and deployment procedures for new installations, refer to the Installation Guide.

• FORTANIX_API_ENDPOINT=https://<fortanix_dsm_url>
• FORTANIX_PKCS11_LOG_FILE=C:\Program Files\Fortanix\KmsClient\logs\debug_pkcs.txt
• FORTANIX_PKCS11_LOG_LEVEL=debug
• FORTANIX_PKCS11_NUM_SLOTS=1
• CyberArk EPV configuration

3.0 Add an Application Corresponding to EPV

An application can use Fortanix DSM to generate, store, and use security objects, such as cryptographic keys, certificates, or an arbitrary secret. Examples of applications include web servers, PKI servers, key vaults, and so on. An application can interact with Fortanix DSM using the REST APIs or PKCS#11, JCE, or CNG providers. EPV integrates with Fortanix DSM using the PKCS#11 interface.

To add an application, specify the following:

• Name of the application (required).
• A short description of the application.
• Choose API Key as the form of authentication.
• Select the group created in the previous step for this application.

4.0 Download and Configure Fortanix DSM Windows Client

An application has the capability to leverage Fortanix DSM for the generation, storage, and utilization of security objects such as cryptographic keys, certificates, or arbitrary secrets. Examples of such applications encompass web servers, PKI servers, key vaults, and more. Interactions between an application and Fortanix DSM can occur through REST APIs or various providers like PKCS#11, JCE, or CNG. The EPV and Fortanix DSM integrate using the PKCS#11 interface.

When adding an application, it is necessary to specify the following details:

• Name of the application (mandatory): Enter the name of the application.
• Short description of the application: Provide a description of the application.
• Authentication method: Select the API Key option as the preferred authentication form.
• Group selection: Assign the group created in the preceding step to this application.

Perform the following steps:

1. The Fortanix DSM client for Windows 64-bit can be downloaded from link. 
2. Install the FortanixKmsClient.msi, which installs the Fortanix DSM PKCS#11 library.
3. Configure the Fortanix DSM URL for communication with the PKCS#11 DLL. Execute the following commands to store the correct values in the registry. Alternatively, you can choose to store entries in the user registry instead of HKLM (HKEY_LOCAL_MACHINE). Refer to this link for more information.
   • Fortanix DSM Endpoint
     1. To configure the Fortanix KMS Server URL for the local machine, run the following command:

        C:\Program Files\Fortanix\KmsClient\FortanixKmsClientConfig.exe machine --api-endpoint https://<fortanix_dsm_url> 

     2. To configure the Fortanix KMS Server URL for the current user, run the following command:

        C:\Program Files\Fortanix\KmsClient>FortanixKmsClientConfig.exe user --api-endpoint https://<fortanix_dsm_url>

   • Fortanix DSM API Key
     1. To configure the Fortanix <>, run the following command:

        C:\Program Files\Fortanix\KmsClient>FortanixKMSClientConfig.exe machine --api-key <dsm_app_api_key>

     2. To configure the Fortanix KMS Client for the current user, run the following command:

        C:\Program Files\Fortanix\KmsClient>FortanixKMSClientConfig.exe user --api-key <dsm_app_api_key>

4. Confirm proper communication between the Fortanix PKCS#11 client and Fortanix DSM: 

   C:\Program Files\Fortanix\KMSClient\certutil -csplist

5. The PKCS#11 DLL is installed in C:\Program Files\Fortanix\KmsClient\FortanixKmsPkcs11.dll. 

Configure the path to this file in the CyberArk EPV software in the subsequent steps.

5.0 Configure CyberArk EPV

This section outlines the essential configuration steps required in CyberArk EPV to utilize Fortanix DSM.

5.1 Network Connectivity

Before implementing CyberArk hardening procedures, it is advisable to install PKCS11 drivers to facilitate HSM integrations, such as Fortanix DSM. The CyberArk hardening process, executed through PowerShell scripts, restricts communication to external systems unless explicitly allowed. If server hardening is performed prior to the steps outlined below, communication with Fortanix DSM may be disrupted, leading to operational issues. It is recommended to apply future CyberArk hardening scripts in a development environment before implementing them in a production setting, as they have the potential to disrupt communication with Fortanix DSM.

Perform the following steps to enable communication with Fortanix DSM:

1. Add the following entry to your Windows host file, located at %SystemRoot%\System32\drivers\etc\hosts, replacing <IP Address> and <fortanix_dsm_url> with the appropriate DSM IP address and URL: <IP Address> <fortanix_dsm_url>
2. In the section of dbparm.ini, found at C:\Program Files (x86)\PrivateArk\Server\conf\dbparm.ini, allow connectivity to Fortanix DSM to be added to the Windows Firewall. Add a non-standard address entry with the DSM IP address, as shown in the following example:
   

   AllowNonStandardFWAddresses=[xx.xxx.xxx.xxx],Yes,443:inbound/tcp,443:outbound/tcp

3. The CyberArk hardening process modifies the TLS Cipher Suite, restricting the accepted ciphers for TLS on the host server. Execute the following step after the CyberArk hardening process to restore a common cipher agreed upon by both the host server and Fortanix DSM during TLS connection establishment.
   • To restore the TLS Cipher Suite, run the following command in Windows PowerShell as the administrator:
     

     Enable-TlsCipherSuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

   • To verify the restoration of the cipher, check the list of ciphers, including the one added with the above command, in the Windows Registry under:
     

     Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Cryptography\Configuration\Local\SSL

5.2 Configure Path to PKCS#11 DLL

Perform the following steps:

1. Open the C:\Program Files (x86)\PrivateArk\Server\conf\dbparm.ini using a text editor and add the following entry to the dbparm.ini under the HSM section:

   [HSM]
   PKCS11ProviderPath="C:\Program Files\Fortanix\KmsClient\FortanixKmsPkcs11.dll"
   

2. Restart the PrivateArk Server.

5.3 Configure PKCS#11 PIN

Perform the following steps to configure the path to the PKCS#11 DLL:

1. Run the following command to configure the PIN for Fortanix DSM. The program CAVaultManager is located at:
   

   c:\'program files (x86)'\privateark\server\CAVaultManager.exe SecureSecretFiles /SecretType HSM /Secret file://C:\key\api_key.txt

   The hsmpincode corresponds to the API key generated for the application in Section 3.0: Add an Application Corresponding to EPV. CyberArk restricts the length of the hsmpincode to 50 characters. To address this limitation, create a file C:\key\api_key.txt with the following content, replacing the quoted API key with your own API key created for the CyberArk integration APP from your Fortanix DSM account:

   api_key = "OWNlOTcxNGMtZjA3Yi00NTUxLWEyYjMtOTEyOWExODlkZjk2OkRiNTY1emstSmNGVk5vcG5NOx9LOXPtUG1JNDNzS3lrOFFLZ29BeURJc0JBc3dOSlpPUm1YNi1NckFNREI0ZXVmZ2RmQ014SzhSQWFDd0hXTXJESUVn"

2. Use file file://C:\key\api_key.txt as the hsmpincode. Open dbparm.ini to verify that the HSMPinCode parameter was added with the encrypted value of the PIN.
3. Stop the PrivateArk Server.

5.4 Generate a New Server Key in Fortanix DSM

Perform the following steps:

1. Run the following command to generate a new server key:
   

   CAVaultManager.exe GenerateKeyOnHSM /ServerKey

   For example:
   

   C:\Program Files (x86)\PrivateArk\Server>CAVaultManager.exe GenerateKeyOnHSM /ServerKey
   ITADB399I Using encryption algorithms: Advanced Encryption Standard (AES), 256 bit, RSA (2048 bit), SHA2-512 (Protocol Integrity), SHA2-512 (Files Integrity).
   ITADM114I Successfully connected to Database, Database id 0.
   CAVLT187I Server Key was successfully generated on HSM device (KeyID=HSM#1).

2. Verify that the new key has been generated in Fortanix DSM:
   1. Log in to the web interface of Fortanix DSM using your user credentials.
   2. Navigate to the Groups menu in the left-navigation bar and click on the group created earlier during the application creation.
   3. Click the Security Objects tab for the group and locate the new security object created by CyberArk EPV.
   4. Click the security object to view its detailed information. The audit log at the bottom right should indicate that the CyberArk EPV application created the key at a specified time.
3. Modify the ServerKey=HSM#1 in dbparm.ini and start the vault service using the PrivateArk server.

5.5 Re-encrypt Vault

Perform the following steps:

1. Run the following command to re-encrypt the vault database with the new key:

   ChangeServerKeys.exe [keys directory] [full path to VaultEmergency.pass] HSM

   Sample Output:

   PS C:\WINDOWS\system32> C:\"Program Files (x86)"\Privateark\server\ChangeServerKeys.exe C:\DemoOperatorKeys C:\DemoOperatorKeys\VaultEmergency.pass HSM#1
   30/08/2023 11:51:30 CHSRVK041I ChangeServerKeys process started.
   ITADB399I Using encryption algorithms: Advanced Encryption Standard (AES), 256 bit, RSA (2048 bit), SHA2-512 (Protocol Integrity), SHA2-512 (Files Integrity).
   ITADM114I Successfully connected to Database, Database id 0.
   ITAQS031I Object cache is loaded.
   HSM generation 1 was chosen, are you sure you want to change server keys to HSM (y/n)?
   y
   Verify that the current master key is at C:\DemoOperatorKeys\RecPrv.key, and press any key.
   
   Verify new server's master key is at C:\DemoOperatorKeys, and press any key.
   
   30/08/2023 11:51:53 CHSRVK043I Signing entropy file C:\PrivateArk\Safes\entropy.rnd with new keys.
   30/08/2023 11:51:54 CHSRVK034I Encrypting server private key.
   30/08/2023 11:51:54 CHSRVK058I Encrypting Backup key.
   30/08/2023 11:51:54 CHSRVK057I Encrypting Database access passwords.
   30/08/2023 11:51:58 CHSRVK020I Keys of Safe System changed successfully.
   30/08/2023 11:51:58 CHSRVK040I Changing keys for Safe System.
   ........
   ...
   30/08/2023 11:53:54 CHSRVK020I Keys of Safe AppProviderCacheSafe changed successfully.
   30/08/2023 11:53:54 CHSRVK040I Changing keys for Safe ItamarSafe.
   .
   30/08/2023 11:53:54 CHSRVK020I Keys of Safe ItamarSafe changed successfully.
   30/08/2023 11:53:54 CHSRVK040I Changing keys for Safe PasswordManager_Accounts.
   .
   30/08/2023 11:53:54 CHSRVK020I Keys of Safe PasswordManager_Accounts changed successfully.
   30/08/2023 11:53:54 CHSRVK054I ChangeServerKeys process was successful. DBParm.ini must be updated to point to new keys for Vault to start.
   30/08/2023 11:53:54 CHSRVK042I ChangeServerKeys process ended.

2. Modify the ServerKey=HSM#1 in dbparm.ini.
3. Start the vault service using the PrivateArk server.

5.6 Revert to the Local Server Key

Perform the following steps:

1. Stop the PrivateArk server.

2. Run the following command to revert back to local server key:

   ChangeServerKeys.exe <keys_directory> <vault_emergency_password_full_path>

   The <keys_directory> should include the local server.key in the path. The following is a sample output:

   C:\Program Files (x86)\PrivateArk\Server>ChangeServerKeys.exe C:\Users\sysadmin\Downloads\keys\DemoMasterKeys C:\Users\sysadmin\Downloads\keys\DemoOperatorKeys\VaultEmergency.pass
   Enter HSM keyset or the Cloud Vendor key management (empty if support not needed):
   12/10/2020 13:52:26 CHSRVK041I ChangeServerKeys process started.
   ITADB399I Using encryption algorithms: Advanced Encryption Standard (AES), 256 bit, RSA (2048 bit), SHA2-512 (Protocol Integrity), SHA2-512 (Files Integrity).
   ITADM114I Successfully connected to Database, Database id 0.
   ITAQS031I Object cache is loaded.
   Verify that the current master key is at C:\Users\sysadmin\Downloads\keys\DemoMasterKeys\recprv.key, and press any key.
   Verify new server's master key is at C:\Users\sysadmin\Downloads\keys\DemoMasterKeys, and press any key.
   12/10/2020 13:52:41 CHSRVK043I Signing entropy file C:\PrivateArk\Safes\entropy.rnd with new keys.
   12/10/2020 13:52:42 CHSRVK034I Encrypting server private key.
   12/10/2020 13:52:42 CHSRVK058I Encrypting Backup key.
   12/10/2020 13:52:42 CHSRVK057I Encrypting Database access passwords.
   12/10/2020 13:52:45 CHSRVK020I Keys of Safe System changed successfully.
   12/10/2020 13:52:45 CHSRVK040I Changing keys for Safe System.
   ......
   12/10/2020 13:52:45 CHSRVK020I Keys of Safe System changed successfully.
   12/10/2020 13:52:45 CHSRVK040I Changing keys for Safe Pictures.
   12/10/2020 13:52:45 CHSRVK020I Keys of Safe Pictures changed successfully.
   12/10/2020 13:52:45 CHSRVK040I Changing keys for Safe VaultInternal.
   12/10/2020 13:52:45 CHSRVK020I Keys of Safe VaultInternal changed successfully.
   12/10/2020 13:52:45 CHSRVK040I Changing keys for Safe Notification Engine.
   ......
   12/10/2020 13:52:46 CHSRVK020I Keys of Safe Notification Engine changed successfully.
   12/10/2020 13:52:46 CHSRVK040I Changing keys for Safe newSafe.
   .....
   12/10/2020 13:52:46 CHSRVK020I Keys of Safe newSafe changed successfully.
   12/10/2020 13:52:46 CHSRVK054I ChangeServerKeys process was successful. DBParm.ini must be updated to point to new keys for Vault to start.
   12/10/2020 13:52:46 CHSRVK042I ChangeServerKeys process ended.

6.0 References

You can refer to the following documents for more information:

• Configure HSM Key Management in a Distributed Vaults Environment
• Configure HSM Key Management for a Primary-DR Environment
• Configure HSM Key Management for a Primary-DR Cluster
• Administer HSM Key Management Integration in Distributed Vaults
• Change an HSM Vendor (migrate from one HSM to another)