# IBM HSM wrapping key rotation

You might need to rotate the wrapping key in IBM HSM on s390x architecture for several reasons:

* To satisfy compliance and regulatory requirements, such as the Digital Operational Resilience Act (DORA).
* To comply with cybersecurity policies within your institution.


Note
For vaults, rotating the IBM HSM wrapping key means rewrapping the previously wrapped seed with the new master key. This document refers to this process as **vault key rotation**.

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 vault wrapping key rotation intent to confirm that the vault hasn't generated random accounts, so that rotation can proceed.
2. If Step 1 fails, see [Troubleshooting](#troubleshooting).
3. If Step 1 succeeds, load and commit the new master key into the HSM so that the new master key is in the `Full committed` state while the old master key remains in the `Valid` state. For example:
![HSM Master Key State](/assets/new-master-key-in-committed-state.890ca3e5dc17bf01dd9ceafb28037b830d4642c5da97a83ccb8dc99e0e9e9509.22e37df8.png)
4. Trigger the intent to start vault wrapping key rotation.
5. Wait for the `VaultKeyMaterialRewrapCompleted` or `VaultKeyMaterialRewrapFailed` event.
6. Activate the new master key in the IBM HSM.


The details are as follows:

## Prerequisites

### Choose the method for rotating the IBM master keys

Important
The links in this section refer to IBM Hyper Protect Crypto Service. For an on-premises HSM, contact IBM for the correct procedure.

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

First, do a dry run of the intent that executes the key rotation. The dry run confirms that the vault hasn't generated random accounts, so that rotation can proceed.

To do the dry run:

1. In the Custody API, call the [Perform a dry run for a given intent payload](/products/custody/v1.39/reference/api/openapi/intents/intentdryrun) operation with the following `v0_RewrapVaultKeyMaterial` intent payload. For more information about dry runs, see [Dry run intents](/products/custody/v1.39/governance/intents/manage-intents-and-approvals#dry-run-an-intent-with-the-api).


```
{
  "type": "v0_RewrapVaultKeyMaterial",
  "vaultId": "insert-vault-uuid-here",
  "customProperties": {}
}
```

1. Provide the `vaultId` of the vault whose key you're rotating.
2. Approve and sign the intent.


If the dry run succeeds, proceed to [Step 2](#step-2-load-and-commit-the-master-key-in-the-ibm-hsm).

If the dry run fails, see [Troubleshooting](#troubleshooting).

## 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 you proceed to Step 3, verify that the **New Master Key Register** contains the new master key and is in the `Full committed` state, and that the **Current Master Key Register** contains the old master key and is in the `Valid` state. For example:

![HSM Master Key State](/assets/new-master-key-in-committed-state.890ca3e5dc17bf01dd9ceafb28037b830d4642c5da97a83ccb8dc99e0e9e9509.22e37df8.png)

## Step 3: Execute the intent to start vault wrapping key rotation

Next, execute the intent to complete the vault key rotation.

To execute the intent:

1. In the Custody API, call the [Propose an intent](/products/custody/v1.39/reference/api/openapi/intents/createintent) operation with the following `v0_RewrapVaultKeyMaterial` intent payload. For more information about requesting intents, see [Manage intents and approvals](/products/custody/v1.39/governance/intents/manage-intents-and-approvals).


```
{
  "type": "v0_RewrapVaultKeyMaterial",
  "vaultId": "insert-vault-uuid-here",
  "customProperties": {}
}
```

1. Provide the `vaultId` of the vault whose key you're rotating.
2. Approve and sign the intent.


During vault key rotation, Ripple Custody asks the HSM to rewrap the seed and the vault signing key with the key in the **New Master Key Register**.

Ripple Custody *lazy rotates* account keys — the next time you use a key to sign, Ripple Custody checks `lastKeyMaterialRewrappingDate` and determines whether it has already updated the key material with the rewrapped seed.

## Step 4: Wait for the `VaultKeyMaterialRewrapCompleted` or `VaultKeyMaterialRewrapFailed` event

After you approve the intent, wait for the intent state to change to **Executed**. If the operation succeeds, Ripple Custody emits a `VaultKeyMaterialRewrapCompleted` event. If it fails, Ripple Custody emits a `VaultKeyMaterialRewrapFailed` event.

If you see the `VaultKeyMaterialRewrapCompleted` event, proceed to [Step 5](#step-5-activate-the-new-master-key).

If you see the `VaultKeyMaterialRewrapFailed` event, see [Troubleshooting](#troubleshooting).

If no event appears within a minute or two, see [Troubleshooting](#troubleshooting).

## Step 5: Activate the new master key

On the IBM HSM, complete the rotation to activate the new master key.

Important
After the key rotation, verify that the **New Master Key Register** is in the `Empty` state, and that the **Current Master Key Register** contains the new master key and is in the `Valid` state. For example:

![HSM Master Key State](/assets/new-master-key-in-valid-state.cab0ae6a1f921b4a10bbbbc9e8d36d5d0a9a70d49f7a5b64e5d9511137b868e0.22e37df8.png)

If you don't complete the IBM key rotation correctly, the vault can't sign transactions, and normal operations are interrupted.

## Troubleshooting

If you haven't loaded the new master key, key rotation hasn't started. Continue to work with the old master key.

If the rewrapping intent fails with a `VaultKeyMaterialRewrapFailed` event, Ripple Custody is still using the old master key of the IBM HSM. Retry the intent until vault key rotation succeeds, which Ripple Custody signals with a `VaultKeyMaterialRewrapCompleted` event.

If the intent continues to fail, treat the HSM master key rotation as **not completed**, and continue to use the previous master key until you investigate the issue. The HSM must remain in the state shown in the following example. Ripple Custody continues to use the HSM in this state, and the existing vault continues to work as before.

![HSM Master Key State](/assets/new-master-key-in-committed-state.890ca3e5dc17bf01dd9ceafb28037b830d4642c5da97a83ccb8dc99e0e9e9509.22e37df8.png)

If no event appears, the vault didn't receive the request. For a connected vault, check the connection between the vault and Ripple Custody. For a cold vault, perform the required manual operation. Also, make sure that the versions of the vault and KMS match the Ripple Custody version.

If the rewrapping intent succeeds (indicated by a `VaultKeyMaterialRewrapCompleted` event) but the final rotation step fails on the IBM HSM side, work with IBM to make sure that the HSM Master Key Register matches the example in [Step 5](#step-5-activate-the-new-master-key).

Don't modify Ripple Custody, and don't submit any business intents, because they get stuck. Ripple Custody works only after you activate the new master key on the IBM side, as shown in [Step 5](#step-5-activate-the-new-master-key).