# IBM HSM wrapping key rotation 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. Important 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: 1. 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. 2. If Step 1 is successful, load and commit the master key rotation in the IBM HSM. 3. Trigger the intent to start vault wrapping key rotation. 4. Activate the new master key in the IBM HSM. The details are as follows: ## Prerequisites ### Choose the method for rotating the IBM master keys 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: * [Master key rotation - Standard Plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-master-key-rotation-intro) * [Master key rotation - Unified Key Orchestrator Plan](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-master-key-rotation-intro) For the instructions for the key rotation procedures, see: * [Rotating master keys by using smart cards and the Management Utilities](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-smart-cards) * [Rotating master keys by using recovery crypto units](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-cli-recovery-crypto-unit) * [Rotating master keys by using key part files](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-rotate-master-key-cli-key-part) * [Recovering a master key from a recovery crypto unit](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-recover-master-key-recovery-crypto-unit) ### A note about downtime during key rotation 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 business operations 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. ## Step 1: Do a dry run of the intent for vault wrapping key rotation 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: 1. In the Custody API, call the [Perform a dry run for a given intent payload](/products/custody/reference/api/openapi/intents/intentdryrun) operation with the `v0_RewrapVaultKeyMaterial` intent. (For more information about dry runs, see [Dry run intents](/products/custody/governance/intents/manage-intents-and-approvals#dry-run-an-intent-with-the-api).) 2. You will need to provide the `vaultId` for the vault for which you are rotating the vault key. 3. Approve and sign the intent. If the dry run is successful, proceed to Step 2. ## Step 2: Load and commit the master key in the IBM HSM Follow the procedure you are using — based on your IBM HSM deployment — for loading and committing the master key in the IBM HSM. Important 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. ## Step 3: Execute the intent to start vault wrapping key rotation The next step is to execute the intent to complete the key rotation. To execute the intent: 1. In the Custody API, call the [Propose an intent](/products/custody/reference/api/openapi/intents/createintent) operation with the `v0_RewrapVaultKeyMaterial` intent. (For more information about requesting intents, see [Manage intents and approvals](/products/custody/governance/intents/manage-intents-and-approvals).) 2. You will need to provide the `vaultId` for the vault for which you are rotating the vault key. 3. 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. ## Step 4: Activate the new master key On the IBM HSM, complete the rotation to activate the new master key. Important 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.