MPC wrapping key rotation

There are several reasons why you may need to rotate the vault keys for an on-premises vault that uses Multi-party Computation (MPC):

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

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, for each node, create new enclave contract with a new symmetric key.
3. Trigger the intent to start vault wrapping key rotation.
4. Update the enclave contract and use the new symmetric key to restart the enclaves.

The details are as follows:

Although performed rarely, key rotation involves some downtime for normal operations. For this reason, we recommend performing key rotation outside of usual business hours.

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 operation with the v0_RewrapVaultKeyMaterial intent. (For more information about dry runs, see Dry run intents.)

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.

The next step is to create a new key encryption key (KEK) and to update the MPC nodes.

As described in the Multi-party computation (MPC) overview, the KEK is an AES symmetric key that is securely stored and never leaves the MPC node's secure environment.

Generate a new node contract with NEXT_KEK_PROVIDER_EMBED containing a new symmetric key, along with the existing key in KEK_PROVIDER_EMBED, for each node.

For each customer-hosted node:

1. The customer generates a new symmetric key and stores it in the Secrets Manager.

2. The customer provides this new key in the new node contract as NEXT_KEK_PROVIDER_EMBED. The current key encryption key is still present in the contract in KEK_PROVIDER_EMBED.

3. The customer deploys the updated node contract.

For each Ripple-hosted node:

1. The Ripple DevOps representative creates a new enclave contract with NEXT_KEK_PROVIDER_EMBED containing a new symmetric key.

2. The Ripple DevOps representative deploys the updated node contract, in the same way as the customer.

After you update and deploy the node contracts for all four MPC nodes, proceed with Step 3 below.

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 operation with the v0_RewrapVaultKeyMaterial intent. (For more information about requesting intents, see 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.

For the final step, generate and deploy a new node contract with NEXT_KEK_PROVIDER_EMBED empty and KEK_PROVIDER_EMBED containing the newly rotated KEK, for each node.

For each customer-hosted node:

1. The customer puts the new KEK in KEK_PROVIDER_EMBED and sets NEXT_KEK_PROVIDER_EMBED to an empty value.

2. The customer deploys the updated node contract.

For each Ripple-hosted node:

1. The Ripple DevOps representative creates a new enclave contract with NEXT_KEK_PROVIDER_EMBED empty and KEK_PROVIDER_EMBED containing the newly rotated KEK.

2. The Ripple DevOps representative deploys the updated node contract, in the same way as the customer.

After you update and deploy node contracts for all four MPC nodes, the wrapping key rotation is complete.