Encryption Key Rotation

USP Manager uses a two-layer encryption model to safeguard sensitive information stored in its database. This model implements industry-standard envelope encryption, which separates the encryption of data from the encryption of the keys themselves.

Envelope encryption provides two main benefits:

• It limits the exposure of the master key by using it only to protect other keys, not bulk data.
• It allows keys to be rotated or replaced without having to re-encrypt the entire database.

USP Manager implements envelope encryption using two types of encryption keys:

• Key Encryption Key (KEK): Encrypts and protects DEKs.
• Data Encryption Keys (DEKs): Encrypt sensitive data stored in the USP Manager database.

Key Encryption Key (KEK)

The Key Encryption Key (KEK) is the top-level encryption key in USP Manager's encryption architecture. It is used to encrypt and protect Data Encryption Keys (DEKs), which in turn encrypt sensitive data stored in the database.

Configuration

The KEK is configured in the USP Manager Configuration File using kek argument within the encryption block:

usp-manager.hcl

encryption {
  kek_source = "config"
  # Must be a Base64-encoded 256-bit key (32 bytes).
  kek = "JvQMSVkI33KWimSo7kjqqrp8O7zv9zPbqy5R9jE1Qjs="
}

tip

To generate a Base64-encoded 256-bit encryption key (32 random bytes), you can use one of the following commands:

Linux

openssl rand -base64 32

Windows (PowerShell)

$bytes = New-Object byte[] 32; [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes); [Convert]::ToBase64String($bytes)

Rotation

danger

Not following the described rotation procedure can lead to permanent data loss. Always ensure you have a secure backup of your KEK before performing key rotation.

Rotating the KEK is a recommended security practice to reduce the risk of long-term key exposure. By periodically replacing the KEK, you ensure that all DEKs remain protected, without requiring re-encryption of the underlying database data.

To rotate the KEK, complete the following steps:

Step 1. Add the rotation block

Update the encryption block in the USP Manager Configuration File to include a rotation block with the new KEK.

The existing KEK remains the active key, while the rotation block defines the new KEK that will replace it after rotation.

usp-manager.hcl

encryption {
  kek_source = "config"
  # Current active KEK.
  kek = "JvQMSVkI33KWimSo7kjqqrp8O7zv9zPbqy5R9jE1Qjs=" 

  rotation {
    # Currently only "config" is supported.
    kek_source = "config"
    # New KEK that will become active after rotation.
    kek = "nFRxNzeqV06Zjdit/Z1WhxxRzXSgHHwJiAbtlqjDlXE="
  }
}

Step 2. Run the rotate command

Execute the following command:

usp-manager rotate

This operation decrypts all existing DEKs with the current KEK and immediately re-encrypts them with the new KEK. The database Records do not need to be re-encrypted, since DEKs continue to handle data encryption.

info

If the Configuration File is not located in the current working directory, specify its path using the --config (-c) option.

For additional guidance and flags, refer to Commands Usage.

Step 3. Promote the new KEK

After the rotation completes successfully, update the encryption block to use the new KEK and remove the encryption.rotation block:

usp-manager.hcl

encryption {
  kek_source = "config"
  # New KEK moved from the encryption.rotation block.
  kek = "nFRxNzeqV06Zjdit/Z1WhxxRzXSgHHwJiAbtlqjDlXE="
}

Data Encryption Keys (DEKs)

Data Encryption Keys (DEKs) are responsible for encrypting sensitive data stored in the USP Manager database. Each DEK is encrypted and protected by the Key Encryption Key (KEK).

Each encrypted Record maintains a reference to the DEK used to encrypt it, allowing USP Manager to decrypt existing data even after a new active DEK is created.

During initial startup, USP Manager automatically creates a DEK named Default-encryption-key and sets it as the active encryption key. This DEK uses the AES-GCM-256 algorithm and is used to encrypt all newly created sensitive data.

Administrators can add new DEKs through the USP Admin UI to create a new active encryption key. Existing Records remain encrypted with their current DEKs until they are re-encrypted through one of the available re-encryption mechanisms.

Status Lifecycle

Each DEK exists in one of the following statuses. Understanding the DEK lifecycle is important because it determines whether a DEK can be used for encryption, decryption, or retirement.

Status	Description	Encryption	Decryption
Active	The current DEK used by USP Manager for all new and updated entities. Only one active DEK can exist at a time.	Yes	Yes
Deprecated	A DEK automatically transitions to Deprecated when it is replaced by a newer active DEK. It is still required because some Records remain encrypted with it. Multiple deprecated DEKs can exist simultaneously.	No	Yes
Inactive	A DEK that is no longer used by any Records can be manually set to Inactive. An inactive DEK has been fully retired after all data has been migrated to a newer active DEK.	No	No

Management

Adding a DEK

Adding a new DEK creates a new active encryption key and marks the previous active DEK as Deprecated. To add a new DEK, follow these steps:

1. From the Sidebar, click General > Encryption Keys.
2. Click Add Key.
3. Complete the details for the new DEK using the Field Descriptions table as a guide.
4. Click Save.

Field Descriptions

Name	Description	Specifications	Required
Name	The name of the DEK.	Must be unique. Must follow the Standard Naming Pattern.	Yes
Description	The description of the DEK.		No
Algorithm	The encryption algorithm used to encrypt data with this DEK. Options: AES-GCM-256 AES-GCM-128	Default is AES-GCM-256.	Yes
Scope	The scope for this DEK.	Currently, the only supported value is Default.	Yes

Editing a DEK

To edit a DEK, follow these steps:

1. From the Sidebar, click General > Encryption Keys.
2. Click the row of the DEK you want to edit.
3. Click the Edit button above the DEK details.
4. Edit the details of the DEK using the Field Descriptions table as a guide. Note that only the Name, Description, and Status fields are editable, while Algorithm and Scope are immutable after creation.
5. Click Save.

info

The Status can only be changed from Deprecated to Inactive, and only when no Records are using the DEK.

DEK Metadata

DEK details include all parameters given in the Field Descriptions table above, plus the following read-only metadata:

Name	Description
ID	Universally Unique Identifier of this DEK.
Created At	Date and time this DEK was created.
Updated At	Date and time this DEK was last updated.
Version	Version number of the DEK configuration. Every change increases the number.

Viewing DEK Usage

To view DEK usage across all entities in the USP Manager database, follow these steps:

1. From the Sidebar, click General > Encryption Keys.
2. Click the row of the DEK you want to view usage for.
3. Click the Usage tab to see a list of all entities currently encrypted. Details for each usage include:
   • Usage ID: The UUID of the entity.
   • Usage Type: The type of entity. Examples include usp_tls_certificate, usp_private_key, usp_sftp_rule, etc.
   • Usage Name: The name of the entity.
   • Version: The version of the entity configuration.
   • Created: The date and time when the entity was created.
   • Updated: The date and time when the entity was last updated.

Inactivating a DEK

To inactivate a deprecated DEK, follow these steps:

1. From the Sidebar, click General > Encryption Keys.
2. Click the row of the DEK you want to inactivate.
3. Click the Edit button above the DEK details.
4. Change the Status to Inactive.
5. Click Save.

Only deprecated DEKs that are not currently in use by any Records can be set to Inactive. To check whether a DEK is still in use, view its usage as described in the previous section.

Record Re-Encryption Mechanisms

USP Manager provides three mechanisms for migrating encrypted Records from deprecated DEKs to the active DEK:

Option 1: Background job

You can configure USP Manager to automatically re-encrypt Records on a schedule by editing the deprecated_key_janitor block in the USP Manager Configuration File:

usp-manager.hcl

deprecated_key_janitor {
  # How often to run a re-encryption cycle (default: "30m").
  interval = "30m"
  # Maximum number of Records to process per rotation cycle (default: 100).
  limit = 100
}

At each configured interval, USP Manager searches for Records that are still encrypted with a deprecated DEK. It then decrypts those Records using the deprecated DEK and re-encrypts them using the active DEK.

The deprecated_key_janitor process does not create, rotate, or manage DEKs. It only re-encrypts existing Records after a DEK rotation has occurred.

Option 2: Creating or updating a Record

When you create a new Credential or Configuration Item—such as a TLS Certificate, Private Key, or Rule—it is always encrypted with the active DEK.

Updating an existing Record also re-encrypts its data with the active DEK, as deprecated DEKs cannot be used for new encryption.

Option 3: CLI re-encryption

You can also trigger a full re-encryption cycle manually using the reencrypt command:

usp-manager reencrypt

This command iterates through all encrypted Records and re-encrypts them using the currently active DEK.

info

If the Configuration File is not located in the current working directory, specify its path using the --config (-c) option.

For additional guidance and flags, refer to Commands Usage.