CyberArk Privilege Access Security Enterprise Password Vault: nShield HSM Integration Guide
Table of Contents
- Introduction
- Procedures
- Stop the Vault Server
- Install and configure the nshield HSM
- Configure the CyberArk dbparm.ini configuration file
- Start and stop the Vault Server
- Configure the CyberArk PAS Vault for OCS key protection
- Regenerate the CyberArk PAS Vault key on the HSM
- Modify dbparm.ini to point to the recovery private key
- Rewrap the CyberArk PAS Vault key from the software to HSM
- Modify dbparm.ini to use the new HSM key
- Start the Vault Server
- Rotate and migrate CyberArk Vault Server keys
Introduction
CyberArk Privilege Access Security Enterprise Password Vault (CyberArk PAS EPV) manages privileged credentials and access rights. This integration guide provides the steps to integrate CyberArk PAS EPV with an Entrust nshield Hardware Security Modules (HSM). The integration uses the PKCS#11 cryptographic API.
Requirements
The CyberArk PAS EPV installation requires two Windows Server virtual machines (VMs), one for the Vault, and one for the components. You can download the product binaries from https://support.cyberark.com/SFE/files.aspx.
Component | Minimum Requirement |
---|---|
Memory |
4 GB |
Processor |
1 CPU |
Processor Cores |
2 |
Hard Disk |
60 GB |
CD or DVD |
Optional |
Network Adapter |
1 (to communicate with the HSM and between the two CyberArk PAS server VMs) |
USB Controller |
Optional (if nshield Remote Administration is used) |
Display |
Standard configuration |
System components required for installation:
On the Vault Server | On the Components Server |
---|---|
Windows Server 2016 or Windows Server 2019 |
Windows Server 2016 or Windows Server 2019 |
Cannot be part of a domain |
Active Directory (optional)1 |
Windows Firewall must be active |
Windows Firewall must be active (optional) |
Static IP |
Static IP |
Disable IPv6 |
Disable IPv6 |
.NET Framework 4.8 |
.NET Framework 4.8 |
Microsoft Visual C++ Redistributable for Visual Studio 2015-2019 |
ASP .NET 4.6 |
IIS 10 |
nshield components required for installation:
On the Vault Server | On the Components Server |
---|---|
nshield Security World software |
None |
CyberArk components required for installation:
On the Vault Server | On the Components Server |
---|---|
CyberArk PAS PrivateArk Vault Server v12.6 |
CyberArk Central Policy Manager (CPM) v12.6 |
CyberArk PAS PrivateArk Client v12.6 |
CyberArk Password Vault Web Access (PVWA) v12.6 |
CyberArk PrivateArk Client (optional)2 |
|
CyberArk Privileged Session Manager (optional)3 |
1 If you want this to be a domain to serve CyberArk clients.
2 If you plan to use this server as a CyberArk client as well. Not required if only hosting the PAS web server.
3 This component requires Microsoft Remote Desktop Services (RDS) Session Host and Windows update KB2999226.
Familiarize yourself with:
-
The documentation for the nshield Connect HSM.
-
The documentation and set-up process for CyberArk PAS EPV.
The following preparations need to be made before starting to use nshield products:
-
For creation of the Security World, determine who within the organization act as custodians of the administrator card set (ACS).
-
Obtain enough blank smartcards to create the ACS. 6 cards are delivered with the nshield Connect HSM.
-
Define the Security World parameters. For details of the security implications of the choices, see the nshield Security Manual.
Licensing
Copy the keys
folder provided by CyberArk to the C:\
directory of the VM for the CyberArk PAS Vault server.
This is the location to which the installer points for the keys and license.xml
file.
The keys-master
folder should be kept on removable media, for example a CD.
Note
|
The CyberArk Digital Vault Security Standard states the following about the keys-master folder:
The Recovery Private Key (Master CD) should be stored in a physical safe.
The recprv.key file in this folder is considered extremely sensitive.
It is normally never stored on the server.
Rather, it is kept on removable media and stored in a safe until needed for the ChangeServerKeys.exe command in Rewrap the CyberArk PAS Vault key from the software to HSM.
|
Product configurations
Entrust has successfully tested nshield HSM integration with CyberArk PAS in the following configurations:
CyberArk PAS | nshield Hardware | nshield (Connect) Image | nshield HSM Firmware | Security World Software |
---|---|---|---|---|
12.1 |
Connect XC |
12.60.10 |
12.50.11 (FIPS Certified) |
12.60.11 |
12.1 |
Connect Plus |
12.60.10 |
12.50.8 (FIPS Certified) |
12.60.11 |
12.6 |
Connect XC |
12.80.4 |
12.50.11 (FIPS Certified) |
12.80.4 |
12.6 |
Connect Plus |
12.80.4 |
12.50.8 (FIPS Certified) |
12.80.4 |
12.6 |
Connect XC |
12.80.5 |
12.72.1 (FIPS Certified) |
12.80.4 |
12.6 |
Connect Plus |
12.80.5 |
12.72.0 (FIPS Certified) |
12.80.4 |
12.6 |
nShield Edge 1 |
N/A |
12.50.8 (FIPS Certified) |
12.71.0 |
12.6 |
nShield 5c |
13.2.2 |
13.2.2 (FIPS Pending) |
13.2.2 |
1 nShield Edge test case tested by CyberArk.
Supported nshield functionality
Feature | Support |
---|---|
Key Generation |
Yes |
1-of-N Operator Card Set |
Yes |
FIPS 140-2 Level 3 mode support |
Yes |
Key Management |
Yes |
K-of-N Operator Card Set |
Yes |
Common Criteria mode support |
N/A |
Key Import |
Yes |
Softcards |
No |
Load Sharing |
Yes |
Key Recovery |
N/A |
Module-only keys |
Yes |
Failover |
Yes |
Procedures
Configure CyberArk to use the nshield HSM from the Vault VM.
Stop the Vault Server
To stop the Vault Server:
-
Open the PrivateArk Server application.
-
Select the red stoplight button.
-
Select Normal shutdown.
-
Select OK.
-
Select Yes.
Install and configure the nshield HSM
This guide does not cover the basic installation and configuration of the nshield HSM or the nshield Security World client software. For instructions, see the Installation Guide for your HSM.
The following lines need to be added to cknfastrc
configuration file of the Security World.
The file is in the %NFAST_HOME% directory, which is typically C:\Program Files\nCipher\nfast
.
Note
|
If you get a permissions error trying to edit the file, right select cknfastrc > Properties > Security > Edit Users and check Allow for Full Control. After editing the file, you can remove full control. Ensure that the Read and Read & execute options are selected. |
-
If you are using module-protected keys:
CKNFAST_OVERRIDE_SECURITY_ASSURANCES=none CKNFAST_LOADSHARING=1 CKNFAST_FAKE_ACCELERATOR_LOGIN=1
-
If you are using OCS-protected keys and K=1:
CKNFAST_OVERRIDE_SECURITY_ASSURANCES=none CKNFAST_LOADSHARING=1
-
If you are using OCS-protected keys and K>1:
CKNFAST_OVERRIDE_SECURITY_ASSURANCES=none CKNFAST_LOADSHARING=1 NFAST_NFKM_TOKENSFILE=C:\ProgramData\nCipher\nfast-nfkm-tokensfile
In this example,
C:\ProgramData\nCipher\nfast-nfkm-tokensfile
is the location for creating thepreload
file. You can change it to another location as required.
Configure the CyberArk dbparm.ini configuration file
To configure the CyberArk dbparm.ini
configuration file:
-
Edit the Vault Server file in
C:\Program Files (x86)\PrivateArk\Server\Conf\dbparm.ini
.To comment out items in the
dbparm.ini
file, use an asterisk (*) at the beginning of the line. -
Add the following
AllowNonStandardFWAddresses
directives to the end of the[main]
section. This tells the Vault server to create firewall rules for this IP/port combination.AllowNonStandardFWAddresses=[HSM.IP.ADD.RESS],Yes,9004:outbound/tcp AllowNonStandardFWAddresses=[HSM.IP.ADD.RESS],Yes,9005:outbound/tcp
-
Repeat the previous step for each HSM that needs to communicate with the Vault server.
-
Add the location of the PKCS#11 provider for the nshield HSM at the end of the file.
-
For 12.50.xx and earlier nshield Security World clients:
[HSM] PKCS11ProviderPath="C:\Program Files (x86)\nCipher\nfast\toolkits\pkcs11\cknfast-64.dll"
-
For 12.60.xx and later nshield Security World clients:
[HSM] PKCS11ProviderPath="C:\Program Files\nCipher\nfast\toolkits\pkcs11\cknfast.dll"
-
-
Save and close the
dbparm.ini
file.
Start and stop the Vault Server
Start then stop the Vault server to process the new firewall rules from the AllowNonStandardFWAddresses
directives just added to the dbparm.ini
file:
-
Open the PrivateArk Server application.
-
Select the green stoplight button.
-
When the server starts, you should the following output indicating the new firewall rules were processed:
Firewall contains external rules. Firewall is open for client communication Firewall is open for non standard address. Firewall is open for non standard address. Firewall is open for non standard address. Firewall is open for non standard address.
-
Select the red stoplight button after the server comes up.
-
Select Normal shutdown.
-
Select OK.
-
Select Yes.
-
Validate that the HSM communication works:
-
Run the
enquiry
andnfkminfo
commands in a command prompt. -
Verify that the module is operational and the world state is Usable and Initialized.
-
Configure the CyberArk PAS Vault for OCS key protection
If you are using module-protected keys, skip this section and continue with Regenerate the CyberArk PAS Vault key on the HSM.
If you are using OCS-protected keys:
-
Open a command prompt as administrator.
-
Run the following command:
% cd "C:\Program Files (x86)\PrivateArk\Server"
-
Run CAVautManager providing the OCS passphrase as shown:
% CAVaultManager SecureSecretFiles /SecretType HSM /Secret "<OCS passphrase>" ... CAVLT146I HSM secret was secured successfully.
NoteThis command does not validate the passphrase against the OCS card, it only encrypts the passphrase and adds it to dbparm.ini
. If you want to validate the passphrase against the OCS card to make sure have it correct, usecardpp -m1 --check
and enter the passphrase when prompted. -
Open the
C:\Program Files (x86)\PrivateArk\Server\Conf\dbparm.ini
file and verify that the following line appears towards the end:HSMPinCode=<encrypted OCS passphrase>
-
Close the
dbparm.ini
file.
Regenerate the CyberArk PAS Vault key on the HSM
Note
|
If you are using a FIPS 140-2 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-2 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. |
-
Open a command prompt as administrator.
-
Either:
Generate a new Vault Server key on the HSM
To generate a new Vault Server key on the HSM:
-
Make the required directory current:
% cd "C:\Program Files (x86)\PrivateArk\Server"
-
If you are generating a new 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#1)
-
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
To load an existing Vault Server key to the HSM:
Note
|
An Entrust nshield HSM configured with a FIPS 140-2 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 nshield are protected from issuance. |
-
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
-
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
-
Open the
C:\Program Files (x86)\PrivateArk\Server\Conf\dbparm.ini
file and change theServerKey
line now.-
Change from:
ServerKey=C:\keys\server.key
-
Change to:
ServerKey=HSM
-
-
Check the new key with the following command:
% nfkminfo -l
Verify the Vault Server key
Verify in the output there is a PKCS#11 key called Cyber-Ark Server Key
:
Keys protected by cardsets:
key_pkcs11_uc... '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.
-
Back up the content of the
keys
folder (default location:C:\keys
) to another location. -
Open a command prompt as administrator.
-
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
.If you loaded an existing key to the HSM using
CAVaultManager LoadServerKeyToHSM /WrapKey
in Regenerate the CyberArk PAS Vault key on the HSM, changeHSM#1
toHSM
.-
For a module-protected key, or for an OCS with K=1:
% ChangeServerKeys C:\keys-master C:\keys\VaultEmergency.pass HSM#1 ... 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. [ENTER] Verify new server's master key is at C:\keys-master, and press any key.[ENTER] ... ChangeServerKeys process was successful. DBParm.ini must be updated to point to new keys for Vault to start.
-
If you are using OCS keys and K-of-N with K>1, you must use the
preload
command.% preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> ChangeServerKeys C:\keys-master C:\keys\VaultEmergency.pass HSM#1
Insert the OCS cards and enter the OCS passphrase when prompted.
-
-
Verify that the
KeyID
(HSM#1
) matches the output of Regenerate the CyberArk PAS Vault key on the HSM. If not, change it in the command to match it.
The following files in C:\keys
change during this process:
-
backup.key
-
replicationuser.pass
-
server.pvk
-
vaultemergency.pass
-
vaultuser.pass
Modify dbparm.ini to use the new HSM key
To modify dbparm.ini to use the new HSM key:
-
Edit the
C:\Program Files (x86)\PrivateArk\Server\Conf\dbparm.ini
file. -
Modify the
ServerKey
line in the[main]
section to point to the new HSM key.HSM#1
is theKeyID
taken from the output of theCAVaultManager GenerateKeyonHSM /ServerKey
command executed in Regenerate the CyberArk PAS Vault key on the HSM:-
Change from:
ServerKey=C:\keys\Server.key
-
Change to:
ServerKey=HSM#1
NoteIf the server key was loaded to the HSM using CAVaultManager LoadServerKeyToHSM /WrapKey
in Regenerate the CyberArk PAS Vault key on the HSM, changeHSM#1
toHSM
.This step may have already been completed if the
ChangeServerKeys
command ran successfully. -
-
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.
-
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.-
Open a command prompt as administrator.
-
Run the following
preload
command:% preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> pause
-
Insert the OCS cards and enter the OCS passphrase when prompted.
-
-
Open the PrivateArk Server application.
-
Start the PrivateArk Server by selecting the green stoplight button.
-
Ensure the server starts with no errors in the output.
-
Once the Vault has started, you can end the paused
preload
session and close the command prompt if one was used. -
Verify you can log in to the Vault web access using CyberArk authentication:
-
From the Components server, browse to the Password Vault Web Access URL defined during installation of the PAS Password Vault Web Access Component.
-
Log in using the credentials specified during installation.
-
-
Open the Windows Event Viewer on the Vault server to show that a client connection was made to the HSM to access the key:
-
Start Windows Event Viewer and navigate to Windows Logs > Application.
-
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
To rotate and migrate CyberArk Server Keys:
-
Stop the Vault Server:
-
Open the PrivateArk Server application.
-
Select the red stoplight button.
-
Select Normal shutdown.
-
Select OK.
-
Select Yes.
-
-
Back up the original HSM keys from the
C:\ProgramData\nCipher\Key Management Data\local
and the CyberArkC:\keys
directories. -
Create another HSM key.
If the existing key is
HSM#1
, the new one should beHSM#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
-
-
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:
% ChangeServerKeys C:\keys-master C:\keys\VaultEmergency.pass HSM#2
-
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
-
-
Update
dbparm.ini
to point to the new key.-
Change from:
ServerKey=HSM#1
-
Change to:
ServerKey=HSM#2
NoteIf a key was loaded to the HSM using CAVaultManager LoadServerKeyToHSM /WrapKey
, then changeHSM
toHSM#2
, and notHSM#1
toHSM#2
. -
-
Save and close the
dbparm.ini
file. -
Confirm that your original HSM key has been backed up.
-
Remove the original HSM key from
C:\ProgramData\nCipher\Key Management Data\local
to ensure that the Vault starts with the new key. -
If you are using OCS key protection with K>1 for K-of-N:
-
Open a command prompt as administrator.
-
Run the following command:
% preload -m <module number> -f "<preload FilePath>" --cardset-name=<OCS Cardset-Name> pause
-
Insert the OCS cards and enter the passphrase when prompted.
-
-
Start the Vault server by selecting the green stoplight button in the PrivateArk Server application.
-
Verify the Vault server starts with no errors in the console output.
-
Once the Vault has started, you can end the paused
preload
session and close the command prompt if one was used. -
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
-
ProductsnShield Connect
-
ProductsnShield Container
-
ProductsnShield as a Service