Test the integration between the Entrust nShield HSM and CyberArk PAS EPV

Regenerate the CyberArk PAS EPV Vault key on the HSM

If you are using a FIPS 140 Level 3 Security World, ensure that a recognized OCS card is inserted into an available slot of the HSM to provide FIPS authorization before running the following commands. An ACS cannot be used for FIPS authorization for this application. If you are using module protection for your Vault key in a FIPS 140 Level 3 world, you still need to create and use an OCS for FIPS authorization, but not key protection. If loadsharing across multiple HSMs is enabled while using module protection, insert an OCS into slot 0 of each HSM sharing the Security World. The K/N quorum must be 1/N.

  1. Open a command prompt as administrator.

  2. Got to either:

Generate a new Vault Server key on the HSM

  1. Make the required directory current:

    % cd "C:\Program Files (x86)\PrivateArk\Server"

  2. If you are generating a new key using module protection, or OCS K-of-N with K=1:

    C:\Program Files (x86)\PrivateArk\Server>CAVaultManager GenerateKeyonHSM /ServerKey
ITADB518W MaxConcurrentUsersByClientID activated in dbparm.ini.
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).

  3. If you are generating a new key using OCS K-of-N with K>1, use preload to launch CAVaultManager. Enter the OCS passphrase when prompted. For example:

    % preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> CAVaultManager GenerateKeyonHSM /ServerKey

2021-07-20 07:54:32: [2432]: INFO: Preload running with: -m1 -f <preload FilePath> --cardset-name=<OCS Cardset-Name> CAVaultManager.exe GenerateKeyOnHSM /ServerKey
...
2021-07-20 07:55:17: [2432]: INFO: Loading complete. Executing subprocess CAVaultManager.exe GenerateKeyOnHSM /ServerKey
...
CAVLT187I Server Key was successfully generated on HSM device (KeyID=HSM#1).

Note down the KeyID that is at the end of the command output. It is required for modifying the ServerKey directive in dbparam.ini and later steps.

Load an existing Vault Server key to the HSM

An Entrust nShield HSM configured with a FIPS 140 Level 3 Security World does not permit the import of existing keys. For enhanced security, Entrust recommends using keys created and protected by the nShield HSM. The use of an HSM assures customers that keys created by the Entrust nShield HSM are protected from issuance.

  1. If you are using module protection or OCS K-of-N with K=1:

    % CAVaultManager LoadServerKeyToHSM /WrapKey
...
CAVLT143I Server Key was successfully uploaded to HSM device

  2. If you are loading an existing software key using OCS K-of-N with K>1, use preload to launch CAVaultManager:

    % preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> CAVaultManager LoadServerKeyToHSM /WrapKey

  3. Open the C:\Program Files (x86)\PrivateArk\Server\Conf\dbparm.ini file and change the ServerKey line now.

    Change from:

    ServerKey=C:\keys\server.key

    Change to:

    ServerKey=HSM

Verify the Vault Server key

Verify the new generated or loaded key with the following command, a PKCS #11 key called Cyber-Ark Server Key:

Using the rocs utility.

C:\Program Files (x86)\PrivateArk\Server>rocs
`rocs' key recovery tool
Useful commands: `help', `help intro', `quit'.
rocs> list keys
  No. Name                     App        Protected by
    1 Cyber-Ark Server Key     pkcs11     testOCS
rocs> exit

Using the nfkminfo utility.

C:\Users\Administrator>nfkminfo -l

Keys protected by cardsets:
 key_pkcs11_ucedb3d45a28e5a6b22b033684ce589d9e198272c2-1438e9e578e8f89d5eb5a20163459586801a3cb0 `Cyber-Ark Server Key'

  • If you used OCS, the key should be listed under Keys protected by cardsets.

  • If you used module protection, the key should be listed under Keys with module protection.

Modify dbparm.ini to point to the recovery private key

In the C:\Program Files (x86)\PrivateArk\Server\Conf\dbparm.ini file, modify the RecoveryPrvKey line in the [main] section to point to the master private key so that the PAS key can be rewrapped from the software key to the HSM key.

  • Change from:

    RecoveryPrvKey=D:\RecPrv.key

  • Change to:

    RecoveryPrvKey=C:\keys-master\RecPrv.key

If you are keeping your Recovery Private Key on removable media as recommended, set the RecoveryPrvKey attribute to the appropriate location rather than using C:\keys-master\RecPrv.key.

Rewrap the CyberArk PAS Vault key from the software to HSM

If you are using OCS protected keys, ensure that a card from the relevant OCS is available to the HSM.

  1. Back up the content of the keys folder (default location: C:\keys) to another location.

  2. Open a command prompt as administrator.

  3. Make the required directory current:

    % cd "C:\Program Files (x86)\PrivateArk\Server"

  4. Rewrap the Vault secrets.

    If you are keeping your Recovery Private Key on removable media as recommended, use the appropriate path instead of C:\keys-master.

    The KeyID (HSM#1) in the following command should match the output of Regenerate the CyberArk PAS EPV Vault key on the HSM. If not, change it in the command to match it.

    If you loaded an existing key to the HSM using CAVaultManager LoadServerKeyToHSM /WrapKey in Regenerate the CyberArk PAS EPV Vault key on the HSM, change HSM#1 to HSM.

    • For a module-protected key, or for an OCS with K=1:

      C:\Program Files (x86)\PrivateArk\Server>ChangeServerKeys C:\keys-master C:\keys\VaultEmergency.pass HSM#1
17/09/2024 15:33:26 CHSRVK041I ChangeServerKeys process started.
ITADB518W MaxConcurrentUsersByClientID activated in dbparm.ini.
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:\keys-master\RecPrv.key, and press any key.
Verify new server's master key is at C:\keys-master, and press any key.

17/09/2024 15:34:10 CHSRVK043I Signing entropy file C:\PrivateArk\Safes\entropy.rnd with new keys.
...
17/09/2024 15:34:14 CHSRVK054I ChangeServerKeys process was successful. DBParm.ini must be updated to point to new keys for Vault to start.
17/09/2024 15:34:14 CHSRVK042I ChangeServerKeys process ended.

    • If you are using OCS keys and K-of-N with K>1, you must use the preload command. Insert the OCS cards and enter the OCS passphrase when prompted.

      % preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> ChangeServerKeys C:\keys-master C:\keys\VaultEmergency.pass HSM#1

  5. Verify the following files in C:\keys changed during this process:

    • Backup.key

    • ReplicationUser.pass

    • Server.pvk

    • VaultemErgency.pass

    • VaultUser.pass

Modify dbparm.ini to use the new HSM key

  1. Edit the C:\Program Files (x86)\PrivateArk\Server\Conf\dbparm.ini file.

  2. Modify the ServerKey line in the [main] section to point to the new HSM key.

    HSM#1 is the KeyID taken from the output of the CAVaultManager GenerateKeyonHSM /ServerKey command executed in Regenerate the CyberArk PAS EPV Vault key on the HSM:

    • Change from:

      ServerKey=C:\keys\Server.key

    • Change to:

      ServerKey=HSM#1
    If the server key was loaded to the HSM using CAVaultManager LoadServerKeyToHSM /WrapKey in Regenerate the CyberArk PAS EPV Vault key on the HSM, change HSM#1 to HSM.

  3. Save and close the dbparm.ini file.

Start the Vault Server

If you are using OCS-protected keys, ensure that a card from the relevant OCS is available to the HSM.

  1. If you are using OCS key protection with K>1 for K-of-N, you have to use the preload command every time the Vault Server is started. Otherwise, skip this step.

    1. Open a command prompt as administrator.

    2. Run the following preload command:

      % preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> pause

    3. Insert the OCS cards and enter the OCS passphrase when prompted.

  2. Open the PrivateArk Server application.

  3. Start the PrivateArk Server by selecting the green stoplight button.

  4. Ensure the server starts with no errors in the output.

  5. Verify you can log in to the Vault web access using CyberArk authentication:

    1. From the Components server, browse to the Password Vault Web Access URL defined during installation of the PAS Password Vault Web Access Component.

    2. Log in using the credentials specified during installation.

      verify vault login

  6. Open the Windows Event Viewer on the Vault server to show that a client connection was made to the HSM to access the key:

    1. Start Windows Event Viewer and navigate to Windows Logs > Application.

    2. The following is an example of the Windows Event Viewer Windows Logs > Application Event Log:

      2021-07-16 09:30:44 t1124: Hardserver [FP]: Notice: CreateClient (v1) pid: 2660, process name: C:\Program Files (x86)\PrivateArk\Server\dbmain.exe

Rotate and migrate CyberArk Vault Server keys

  1. Stop the Vault Server:

    1. Open the PrivateArk Server application.

    2. Select the red stoplight button.

    3. Select Normal shutdown.

    4. Select OK.

    5. Select Yes.

  2. Back up the original HSM keys from the C:\ProgramData\nCipher\Key Management Data\local and the CyberArk C:\keys directories.

  3. Create another HSM key.

    If the existing key is HSM#1, the new one should be HSM#2.

    • If you are generating a new HSM key using module protection, or OCS K-of-N with K=1:

      % CAVaultManager GenerateKeyonHSM /ServerKey
...
CAVLT187I Server Key was successfully generated on HSM device (KeyID=HSM#2)

    • If you are generating a new HSM key using OCS K-of-N with K>1, use preload to launch CAVaultManager. Insert the OCS cards and enter the passphrase when prompted.

      % preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> CAVaultManager GenerateKeyonHSM /ServerKey

  4. Rotate the server keys to the new HSM key:

    • For a module-protected key, or for an OCS with K=1, rewrap the Vault secrets with the following:

      % C:\Program Files (x86)\PrivateArk\Server>ChangeServerKeys C:\keys-master C:\keys\VaultEmergency.pass HSM#2
07/10/2024 10:27:06 CHSRVK041I ChangeServerKeys process started.
ITADB518W MaxConcurrentUsersByClientID activated in dbparm.ini.
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 2 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:\keys-master\RecPrv.key, and press any key.
Verify new server's master key is at C:\keys-master, and press any key.

07/10/2024 10:27:39 CHSRVK043I Signing entropy file C:\PrivateArk\Safes\entropy.rnd with new keys.
07/10/2024 10:27:39 CHSRVK034I Encrypting server private key.
07/10/2024 10:27:39 CHSRVK058I Encrypting Backup key.
07/10/2024 10:27:39 CHSRVK057I Encrypting Database access passwords.
...
07/10/2024 10:27:44 CHSRVK054I ChangeServerKeys process was successful. DBParm.ini must be updated to point to new keys for Vault to start.
07/10/2024 10:27:44 CHSRVK042I ChangeServerKeys process ended.

    • If you are using OCS keys and K-of-N k>1, you have to use the preload command. Insert the OCS cards and enter the passphrase when prompted.

      % preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> ChangeServerKeys C:\keys-master C:\keys\VaultEmergency.pass HSM#2

  5. Update C:\Program Files (x86)\PrivateArk\Server\Conf\dbparm.ini to point to the new key.

    • Change from:

      ServerKey=HSM#1

    • Change to:

      ServerKey=HSM#2
    If a key was loaded to the HSM using CAVaultManager LoadServerKeyToHSM /WrapKey, then change HSM to HSM#2, and not HSM#1 to HSM#2.

  6. Save and close the dbparm.ini file.

  7. Confirm that your original HSM key has been backed up.

  8. Remove the original HSM key from C:\ProgramData\nCipher\Key Management Data\local to ensure that the Vault starts with the new key.

  9. If you are using OCS key protection with K>1 for K-of-N:

    1. Open a command prompt as administrator.

    2. Run the following command:

      % preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> pause

    3. Insert the OCS cards and enter the passphrase when prompted.

  10. Start the Vault server by selecting the green stoplight button in the PrivateArk Server application.

  11. Verify the Vault server starts with no errors in the console output.

  12. Optionally, open Windows Event Viewer. Verify in Windows Logs > Application the following line is present, indicating the new Vault server key was retrieved from the HSM to start the server:

    Hardserver [FP]: Notice: CreateClient (v1) pid: 3788, process name: C:\Program Files (x86)\PrivateArk\Server\dbmain.exe