How to move the CyberArk Vault server key into a Thales Luna HSM

This is the command-level companion to our chapter on HSM-protecting the CyberArk Vault server key. That chapter covers whether you should do this and what it costs operationally; this one covers how. The walkthrough follows the flow validated in Thales’s CyberArk Vault integration guide and CyberArk’s PAM Self-Hosted documentation. Command syntax below matches the Thales integration guide (tested against Vault 12.1 on Windows Server 2016); the same commands appear in current CyberArk documentation for v12 through v14, but confirm flags against the docs for your exact version before you cut the change record — where behaviour is known to vary by version, we say so inline.

One framing note before the first command: this change re-roots the vault’s entire encryption hierarchy. It is a full change-controlled activity with a tested rollback, done on the DR vault first where one exists, never live on a primary during business hours. Plan the vault downtime honestly — the migration itself is quick, but the ChangeServerKeys path re-encrypts vault data, and on a large vault that is hours, not minutes.

Prerequisites

Have all of these in place before touching the vault:

• Luna client installed on the vault server, with the client registered to the appliance and assigned a dedicated partition over NTLS (certificates exchanged both ways). Partition creation, client registration and role initialisation are covered in our Luna HSM design and operational guide.
• Crypto Officer credentials for that partition. The CO credential is what the vault will authenticate with, unattended, at every start. On a PED-authenticated partition, activation and auto-activation (partition policies 22 and 23) must be enabled or the vault cannot start without a human presenting a PED key — see the chapter on activation and unattended services.
• A network path for NTLS — TCP 1792 from the vault server to the HSM appliance — through every firewall in between, including the vault’s own hardened firewall (step 2 below handles that one).
• A verified, restorable backup of the vault, plus the existing server key material and the recovery key pair, secured offline. If this change goes wrong, these are the road back.
• An agreed outage window sized for re-encryption if you are generating a new key, and a DR/HA plan for the same change — in a Primary-DR pair the vaults must end up using the same HSM-held key, and CyberArk documents a specific ordering for cluster and distributed-vault environments. Do not improvise it; pull the HSM key-management procedure for your topology and version.

Step 1 — verify the Luna client sees the partition

From the vault server, confirm the partition is visible before involving CyberArk at all:

C:\Program Files\SafeNet\LunaClient>lunacm.exe

Available HSMs:
  Slot Id ->              0
  Label ->                CyberArk
  Serial Number ->        1238696044904
  Model ->                LunaSA 7.4.0

If the slot is missing, fix NTLS first — check vtl verify, certificate validity and the network path. Nothing in the CyberArk configuration will work until this does. If you run two appliances in an HA group, verify the virtual HA slot is the one you will point the vault at, and that HAOnly is enabled so a single appliance failure does not surface as a slot change.

Step 2 — open the vault’s hardened firewall for NTLS

The vault manages its own firewall and closes everything it does not recognise. Declare the HSM explicitly in DBParm.ini (in the PrivateArk Server installation directory):

AllowNonStandardFWAddresses=[HSM-IP],Yes,1792:inbound/tcp,1792:outbound/tcp

Multiple rules are comma-separated on the same line. Two version notes. First, the inbound entry appears in Thales’s tested configuration even though NTLS is client-initiated; follow the documented form for your version rather than minimising it by hand. Second, practitioner reporting indicates the handling of this parameter changed around vault v12.6 on Windows Server 2019 as CyberArk reworked the hardening — on current v13/v14 builds, verify in the release documentation whether the parameter is still required for outbound HSM traffic on your baseline. The test is simple: after a vault service restart, confirm you can establish NTLS from the vault server.

Step 3 — configure the PKCS#11 provider and secure the partition credential

Point the vault at the Luna client’s PKCS#11 library in the [main] section of DBParm.ini:

PKCS11ProviderPath="C:\Program Files\SafeNet\LunaClient\cryptoki.dll"

Then store the partition credential so the vault can authenticate unattended. From the PrivateArk Server directory:

CAVaultManager.exe SecureSecretFiles /SecretType HSM /Secret <partition_password>

This writes an HSMPinCode parameter into DBParm.ini containing the encrypted credential — the plaintext partition password never sits in the file. Verify the parameter appeared, then restart the vault service to apply the firewall and provider changes, and shut it down again cleanly for the key work. The credential is machine-bound secured storage: it does not survive being copied to another server, which is exactly the property you want and a thing to remember when you build the DR vault.

Step 4 — path A: generate a new server key on the HSM

This is the cleaner path cryptographically — the key is born inside the HSM and never exists outside it. It requires re-encrypting the vault with the new key, which is where the downtime goes. With the vault service stopped:

CAVaultManager.exe GenerateKeyOnHSM /ServerKey

The command returns a key generation identifier — HSM#1 for the first generation, incrementing with each subsequent generation (the numbering wraps after 255). Confirm the key exists on the partition using the Luna client’s CMU utility:

cmu.exe list

Check that RecoveryPrvKey in DBParm.ini points at the correct private recovery key (recprv.key), then re-encrypt the vault under the new key:

ChangeServerKeys <PathToKeys> <PathToEmergencyFile> HSM#1

REM Example:
ChangeServerKeys C:\Keys C:\Keys\VaultEmergency.pass HSM#1

Size this step honestly: on a large vault, community-reported re-encryption times run to many hours and in extreme cases days. Finally, point the vault at the HSM-held generation in DBParm.ini:

ServerKey=HSM#1

Step 5 — path B: migrate the existing server key into the HSM

If re-encryption downtime is unaffordable, wrap the existing key into the HSM instead. With the vault service stopped:

CAVaultManager.exe LoadServerKeyToHSM /WrapKey

The command generates a key pair on the HSM, encrypts the on-disk server key to the public half, and unwraps it inside the partition — the wrapping private key is deleted from the HSM once the server key is unwrapped, so the key cannot be extracted the same way it went in. Verify with cmu.exe list, then set:

ServerKey=HSM

Note the difference: path A references a specific generation (ServerKey=HSM#1); path B’s migrated key is referenced as ServerKey=HSM. Path B’s trade-off is that the key previously lived on disk — any historical copy, backup or snapshot of the old key file remains a copy of your current server key. If you choose path B, schedule a path-A key generation at the next available window, and treat every backup containing the old key file as in-scope until then.

Step 6 — verify start, stop and failure behaviour

Start the PrivateArk Server service and log in via the PrivateArk client. Success is necessary but not sufficient — before you call the change complete, prove the behaviours you will one day depend on:

• Clean restart with HSM in path: stop and start the vault service twice; confirm unattended startup with no PED or console interaction.
• Full server reboot: the OS-level restart exercises service ordering — the vault must not race the Luna client or the network stack.
• HSM unreachable at startup: block 1792, attempt a vault start, and record exactly what the failure looks like in the vault logs. This is the signature your on-call will need to recognise at 3am. Unblock and confirm clean recovery.
• HSM unreachable mid-operation: with the vault running, block 1792 and observe. Expect degraded behaviour — key-dependent operations failing with errors that masquerade as safe-key or authentication faults — rather than a clean crash. Restore the path and confirm the vault recovers without a restart. CyberArk supports automatic reconnection on specific HSM error codes via a ReconnectHSMOnErrorCodes parameter in DBParm.ini; the parameter name and the applicable error-code list are version-dependent, so take both from your version’s documentation rather than from this post.
• HA failover at the Luna layer (if fitted): fail the primary appliance and confirm the vault rides through on the HA group.

For diagnosis during these tests, CyberArk’s crypto trace levels (debug levels CRYPT(1,2) in the server logging configuration) show the vault’s PKCS#11 calls and are the fastest way to distinguish “vault cannot reach HSM” from “vault reached HSM and was refused”.

Rollback plan

Write the rollback before the change, and rehearse the first step of it. The shape depends on which path you took:

• Path B (migrated key): rollback is simple because the vault data was never re-encrypted — restore the original ServerKey file path in DBParm.ini, reinstate the on-disk key from secured backup, and start the vault.
• Path A (new key, vault re-encrypted): there is no quick config-level rollback once ChangeServerKeys has run — the data is encrypted under the HSM-held key. Reverting means either running ChangeServerKeys again back to a file-based key (a second full re-encryption window) or restoring the pre-change vault backup and accepting the data loss window. This asymmetry is why path A belongs in a generous window with the backup verified, not squeezed into a Friday night.

In both cases, keep the pre-change DBParm.ini alongside the change record, and do not delete the old key material or recovery files until the vault has run a full backup cycle on the new key.

Where this leaves you

Your primary vault now starts against the HSM, you know what both failure modes look like, and your rollback is written down. The next problem is the one the change record quietly deferred: the DR vault needs this same key served from an HSM at the DR site, and whether the key can be cloned there was decided when the partition’s cloning domain was set — long before this project existed. That, plus keeping Primary and DR key generations in lockstep, is the next chapter. The series lives at The Luna Field Guide.