Encryption Key Rotation

USP Manager uses a two-layer encryption model to safeguard sensitive information stored in its database—whether is the built-in SQLite engine or an external Oracle instance. 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 applies this approach through a two-tier key hierarchy:

• Key Encryption Key (KEK): It encrypts the DEKs, effectively "enveloping" them to ensure that only a valid KEK can unlock access to the underlying data.
• Data Encryption Keys (DEKs): They encrypt the actual data stored in the USP Manager database.

In addition, USP Manager supports KEK rotation, enabling administrators to replace the KEK securely while automatically re-encrypting all DEKs with the new key. This ensures long-term protection of sensitive data without disruption to database operations.

KEK Configuration

The Key Encryption Key (KEK) is defined in the USP Manager configuration file under the encryption block and is used to encrypt all Data Encryption Keys (DEKs):

/opt/udmg/etc/usp-manager.hcl

encryption {
  kek_source = "config" # Default and only supported value.
  kek = "my-secret-encoded-key" # Must be a base64-encoded 256-bit key (32 bytes).
}

tip

You can generate your own base64-encoded 256-bit key (32 bytes) by running this command:

openssl rand -base64 32

KEK 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, follow these steps:

1. Add a rotation block

Update the encryption block in the configuration file to include a rotation block with the new KEK. The existing KEK remains in place as the active key, while the rotation block defines the key that will be rotated in.

/opt/udmg/etc/usp-manager.hcl

encryption {
  kek_source = "config"
  kek = "my-secret-encoded-key" # Currently active KEK
  rotation {
    kek_source = "config"
    kek = "my-future-secret-encoded-key" # New KEK to rotate in
  }
}

2. Run the rotation command

From the directory containing the configuration file, 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 data itself does not need to be re-encrypted, since DEKs continue to handle data encryption.

3. Promote the new KEK

After the rotation completes successfully, move the new KEK from the rotation block into the main encryption block.

/opt/udmg/etc/usp-manager.hcl

encryption {
  kek_source = "config"
  kek = "my-future-secret-encoded-key"
}

The rotation block can then be removed, or left in place and prepared with another KEK for future rotation.

DEK Management

The Data Encryption Keys (DEKs) are generated and maintained by USP Manager. Each DEK is encrypted with the KEK and then used to encrypt sensitive values stored in the USP Manager database. When data is accessed, the DEK is decrypted with the KEK.

Admins can inspect and manage DEKs using the following API endpoints:

GET   /v1/system/keys       # List encryption keys with filtering and pagination
GET   /v1/system/keys/{id}  # Get specific encryption key details
POST  /v1/system/keys       # Create new encryption key (auto-rotates active key)
PATCH /v1/system/keys/{id}  # Update encryption key metadata and status
GET   /v1/system/key-usage  # View encryption key usage across all tables

info

• Creating a new DEK using the POST /v1/system/keys API endpoint will automatically set the newly created DEK with an active status and force the existing active DEK to change to deprecated.
• Using the /v1/system/key-usage endpoint will show what DEK each entity is currently using as well as information on the status of that DEK (active, deprecated, or inactive).

DEK Statuses and Rotation

DEKs are rotated more frequently than KEKs and are designed to ensure that sensitive data in the USP Manager database is always protected by up-to-date keys. Understanding their lifecycle and rotation mechanisms is key to maintaining a secure deployment.

USP Manager provides three mechanisms for rotating DEKs:

1. Background job

You can configure USP Manager to automatically re-encrypt entities on a schedule by uncommenting the deprecated_key_janitor block in the configuration file:

/opt/udmg/etc/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 interval, USP Manager checks for entities still using a deprecated DEK. Their data is decrypted with the old DEK and re-encrypted with the active one.

2. Updating or creating an entity

When you create a new Credential or Configuration Item—such as a TLS Certificate, Private Key, or Inbound Node—it is always encrypted with the active DEK. Updating an existing entity also re-encrypts its data with the active DEK, as deprecated DEKs cannot be used for new encryption.

3. CLI re-encryption

You can also trigger a full re-encryption cycle manually using the reencrypt command from the directory containing the configuration file:

usp-manager reencrypt

This command iterates through all encrypted entities and forces re-encryption with the currently active DEK.