There are several reasons why you may need to rotate the vault keys for a vault that uses an IBM HSM on s390x architecture:
- To satisfy compliance and regulatory requirements, such as the Digital Operational Resilience Act (DORA).
- To comply with cybersecurity policies within your institution.
You can rotate the HSM wrapping key only for vaults that do not have random accounts generated with the vault.
This page describes the vault key rotation process, which involves the following steps:
- Do a dry run of the intent for vault wrapping key rotation. This checks that the vault does not have any random accounts generated, to make sure that it is possible to proceed.
- If Step 1 is successful, load and commit the master key rotation in the IBM HSM.
- Trigger the intent to start vault wrapping key rotation.
- Activate the new master key in the IBM HSM.
The details are as follows:
Before beginning, make sure that you know which of the four IBM key rotation methods you are using, based on the Service Plan — the Standard Plan or the Unified Key Orchestrator Plan — that you are using.
For a description of the master key rotation strategies under the two plans, see:
For the instructions for the key rotation procedures, see:
- Rotating master keys by using smart cards and the Management Utilities
- Rotating master keys by using recovery crypto units
- Rotating master keys by using key part files
- Recovering a master key from a recovery crypto unit
Although performed rarely, key rotation involves some downtime for normal operations. For this reason, we recommend performing key rotation outside of usual business hours.
Suspend any business operations during the key rotation process. If you submit an intent that the vault needs to sign, this intent will be stuck in retrial indefinitely.
The first step is to do a dry run for an intent to execute the key rotation. This checks that the vault does not have any random accounts generated, to make sure that it is possible to proceed.
To do the dry run:
In the Custody API, call the Perform a dry run for a given intent payload operation with the
v0_RewrapVaultKeyMaterialintent. (For more information about dry runs, see Dry run intents.)You will need to provide the
vaultIdfor the vault for which you are rotating the vault key.Approve and sign the intent.
If the dry run is successful, proceed to Step 2.
Follow the procedure you are using — based on your IBM HSM deployment — for loading and committing the master key in the IBM HSM.
Before proceeding with Step 3, verify that the New Master Key Register contains the new master key and is in Full committed state. The Current Master Key Register should contain the old master key and be in the Valid state.
The next step is to execute the intent to complete the key rotation.
To execute the intent:
In the Custody API, call the Propose an intent operation with the
v0_RewrapVaultKeyMaterialintent. (For more information about requesting intents, see Manage intents and approvals.)You will need to provide the
vaultIdfor the vault for which you are rotating the vault key.Approve and sign the intent.
During the rotation of the vault key, Ripple Custody rewraps and updates two keys: the seed used for the generation of derived account keys, and the vault signing key.
Ripple Custody lazy rotates account keys — the next time you use a key for a signature, Ripple Custody checks lastKeyMaterialRewrappingDate and determines if it has updated the key material with the rewrapped seed.
On the IBM HSM, complete the rotation to activate the new master key.
Following the key rotation, make sure that the New Master Key Register is now in Empty state, and that the Current Master Key Register now contains the new master key and is in the Valid state.
If you do not complete the IBM key rotation correctly, the vault will not be able to sign transactions and normal operations will be interrupted.