Rotating your root keys

It is a best practice to rotate your root keys (that is, to create a new version of the key) on a regular basis. Regular rotations reduce what is known as the "cryptoperiod" of the key, and can also be used in specific cases such as personnel turnover, process malfunctions, or the detection of a security issue.

If you suspect a key has been compromised, disable it as soon as possible. Check out Disabling root keys for more information.

Recall that root keys are not just used to create data encryption keys (DEKs), they are also used in conjunction with a master key (secured by IBM using a Hardware Security Module) to create a "wrap" of a DEK. The resulting "wrapped data encryption key" (WDEK) protects the DEK, which is used to encrypt data. If a user has a DEK they want to use, that key can be passed when creating a WDEK using the wrap call. If no DEK is specified, Key Protect creates the DEK for you.

Rotating to a new version of the root key does not immediately create a new WDEK, but it does mean that on the next wrap and re-wrap initiated by the user that the new root key will be used to create the new WDEK. Note that the new WDEK can also be unwrapped and used to read data encrypted with older versions of the DEK, and that old versions of the WDEK can still be unwrapped to obtain the DEK.

Each rotation creates a new "version" of the key, and you are charged on your IBM Cloud account per key version. Check out Pricing for more information.

Rotating manually or automatically

Only root keys can be rotated using Key Protect. Standard keys cannot be rotated.

Root keys can be rotated manually or on a schedule set by the owner of the key. The option you choose depends on your preferences and the needs of your use case.

Setting a rotation policy
The simplest key rotation option, setting an automatic rotation interval means root keys are updated without further effort from the user. These rotations can be set at 30 day intervals (in other words, every 30 days, or 60 days, or 90 days, up to 12 months, or 720 days). This policy can be managed in the UI or by using the Key Protect API. For more information about how to set a rotation policy, check out Setting a rotation policy. The process can also be set using the CLI.

To rotate a key that you initially imported to the service, you must generate and provide new key material for the key with each rotation. As a result, automatic rotation policies are not available for keys that have imported key material. Imported root keys must therefore be rotated manually. Note that the metadata for imported keys, such as the key ID, do not change when the key is rotated, just as with a key generated with Key Protect.
Rotating keys manually
As a security admin, you might want to have more control over the frequency of rotation for your root keys. If you don't want to set an automatic rotation policy for a key, you can manually create a new key to replace an existing key, and then update your applications so that they reference the new key.

To simplify this process, you can use Key Protect to rotate the root key at any time. In this scenario, Key Protect creates and replaces the key on your behalf with each rotation request. The metadata and key ID of the key will not change. For more information about to manually rotate a key, check out Manually rotating keys.

Manually rotating a root key does not disturb any rotation policy that might currently exist for the key. As a result, a good option is to set a regular rotation policy and then manually update keys more often as needed.

How often should keys be rotated?

After you generate a root key in Key Protect, you decide how often it is rotated. The best practice is to rotate your keys regularly.

Rotation frequency options for rotating keys in Key Protect
Rotation type	Frequency	Description
Policy-based key rotation	Intervals of 30 days (in other words, every 30 days, or 60 days, or 90 days, etc)	Choose a rotation interval between one and 12 months for your root key based on your security needs. After you set a rotation policy for a root key, the clock starts immediately based on the initial creation date for the key. If you choose at any time to manually rotate this key, the rotation period resets based on that rotation.
Manual key rotation	Up to one rotation per hour	Key Protect allows no more than one rotation per hour for each key.

It is possible to learn the last date a key was rotated by using the lastRotateDate field available in APIs such as getkey, getkeymetadata, and getkeys.

How key rotation works

During a root key rotation, the key remains in an active state. However, older versions are deactivated and can be considered "retired". This latest version of the root key will then be used for all future actions. While unwraps can still be done with WDEKs which were generated with an older version of the root key, wraps and re-wraps use the latest version of the root key. Note that a previous key version can only be used to unwrap and access data encrypted using that particular key version or lower. An old version of a root key cannot be used to create a new DEK or to wrap the DEK and create a WDEK. For more information, check out Managing retired key versions.

For more information about how key rotation works, check out Understanding the key rotation process.

To enable key rotation options for your IBM Cloud data service, the data service must be integrated with Key Protect. Refer to the documentation for your IBM Cloud data service, or check out our list of integrated services to learn more.

Monitoring key rotations

After you rotate a root key, Key Protect notifies the IBM Cloud data services that use the key to protect your data. This notification triggers actions in those services to rewrap the key's associated data encryption keys (DEKs) with the latest key version.

After Key Protect receives confirmation from those services that all associated DEKs are rewrapped, you receive an event in your IBM Cloud Activity Tracker UI to show that the rotation is complete.

Managing retired key versions

Key Protect creates a new version of the root key with each rotation request. The service retires the old key versions and retains them until the key is deleted. The retired key versions can no longer be used to wrap keys, but they remain available for unwrap operations.

If Key Protect detects that you're using a retired root key version to unwrap DEKs, the service provides a newly wrapped DEK that's based on the latest key version.

Rewrapping data after rotating a key

Because retired key versions can only be used to access older DEKs, to secure your envelope encryption workflow, rewrap your DEKs after you rotate a key so that your at rest data is protected by the newest key.

Alternatively, if Key Protect detects that you're using a retired key version to unwrap a DEK, the service automatically re-encrypts the DEK and returns a wrapped data encryption key (WDEK) that is based on the latest root key.

Store and use the new WDEK for future unwrap operations so that the DEKs are protected with the newest key version.

To learn how to use the Key Protect API to rewrap data encryption keys, see Rewrapping keys.

Understanding the key rotation process

Behind the scenes, the Key Protect API drives the key rotation process. To learn how to use the Key Protect API to rotate your keys, see Rotating keys.

The following diagram shows a contextual view of how keys are rotated.

The diagram shows a contextual view of key rotation. — Contextual view of key rotation.

With each rotation request, Key Protect creates a new root key version by associating new key material with your key.

The diagram shows a micro view the key stack. — Micro view of a key stack.

Keys do not rotate at precisely the same time of the day the key was created. That is, if a key was originally created at 8 a.m., it will not necessarily be rotated at 8 a.m. on the day the rotation is scheduled. Instead, the rotation can happen at any point during a 24-hour window.

What's next

For more information about how to use Key Protect to set an automatic rotation policy for an individual root key, see Setting a rotation policy.
For more information about manually rotating root keys, check out Manually rotating keys.
For more information about viewing the key versions that are available for a root key, check out Viewing key versions.