Skip to main content

Managing Keys

Once Data Encryption Keys are enabled, you can manage them over time using the following commands, available from the action menu of Data Encryption Key Settings, the Encryption Keys tabs, and Data Encryption Key records:

  • Rotate: Deprecates the current Primary key for a specific type and generates a new Primary key in its place.
  • Rotate All: Deprecates the current Primary key for every type and generates new Primary keys in their place.
  • Deprecate: Retires an Available key.
  • Promote: Promotes a Primary key to another Controller.
  • Promote All: Promotes the Primary key of every type to another Controller.

All of these commands require the ops_admin role.

Rotate​

Rotating a key retires the current Primary key for a type and generates a new one. Use rotation to periodically replace your keys, or to respond to a suspected key compromise.

  • Rotate is available per Encryption Keys tab and rotates the key for that one type.
  • Rotate All, available on Data Encryption Key Settings, rotates the keys for every type.

A confirmation dialog displays when you select Rotate or Rotate All.

When a key is rotated:

  1. A new key is generated and becomes the Primary key for that type. All new and updated values of that type are encrypted with it.
  2. The previous Primary key is marked Deprecated.
  3. Existing encrypted values are re-encrypted with the new Primary key.

Deprecate​

Deprecating a key retires it from encrypting new values, while keeping it available for decryption. The Deprecate command is available from the action menu of a Data Encryption Key record (on the form or in the list), and is enabled only for a key with a status of Available.

When a key is deprecated, the key's status is set to Deprecated, and the Deprecated and Deprecated By fields are set.

An Available key is not used to encrypt any active secrets on a Controller (it exists only to decrypt values arriving from other sources), so no re-encryption of existing data should be required when it is deprecated. The Controller initiates a re-encryption sweep anyway, as a precaution.

Deprecation and the Grace Period​

Deprecating a key never makes its data unreadable. A deprecated Data Encryption Key remains fully capable of decryption indefinitely.

The configurable grace period (set with the Grace Period (days) setting, 30 days by default) controls only the severity of the log messages produced when a deprecated key is used to decrypt a value:

  • Within the grace period, use of a deprecated key is logged as a warning.
  • After the grace period elapses, it is logged as an error.

In normal operation, the automatic re-encryption sweep migrates existing values onto the current Primary key, so a deprecated key is typically no longer used for decryption well before the grace period matters.

Re-encryption​

Both Rotate and Deprecate trigger a background process that re-encrypts stored values of the affected type using the current Primary key. Any value that is not already encrypted with the current Primary key is re-encrypted.

Re-encryption can also be triggered manually via the Reload Keyring server operation.

Promote​

The Promote command uses the standard Promotion mechanism to copy a Data Encryption Key to another Controller, where its status is set to Available. This is the recommended way to make Data Encryption Keys available on other Controllers.

  • Promote is available from the action menu of a Data Encryption Key record and is enabled only for a Primary key.
  • Promote All, available on Data Encryption Key Settings, promotes the Primary key of every type.

Prerequisites​

Before you promote a Data Encryption Key, the target Controller must meet the following conditions, or the promotion is rejected:

  • The target Controller must be running Universal Controller 8.0.1.0 or later. A Data Encryption Key cannot be promoted to an earlier release.
  • The target Controller must have Data Encryption Keys enabled.
  • The Key Encryption Key (KEK) that wraps the promoted key must already be present in the target Controller's keyring. You must add it manually and either restart or run the Reload Keyring server operation on the target so it loads the new KEK. See Sharing Keys Between Controllers.
  • You must have the ops_admin role on the source Controller, and the user accepting the promotion on the target Controller must have the ops_admin role.
info

If a Data Encryption Key with the same UUID already exists on the target Controller, it is excluded from the promotion. In that case, the referenced KEK is not required on the target.

After Acceptance​

When a promoted Data Encryption Key is accepted on the target Controller:

  • It is created with a status of Available, because each type can have only one Primary key.
  • Its key value is decrypted and re-encrypted with the Primary KEK on the target Controller. Note that the DEK is not overwritten if it already exists in the target system.

For how records that contain encrypted data behave during promotion and Import/Export, see Promotion and Import/Export.