Encryption Keys Overview
You can now enable a centralized, two-tier envelope encryption model based on 256-bit AES Key Encryption Keys (KEKs) and 256-bit AES Data Encryption Keys (DEKs) to protect sensitive data stored by the Controller (such as passwords and sensitive parameters for Credentials, OAuth Single Sign-On settings, SAML Single Sign-On settings, OAuth Client configurations, etc.).
When enabled, this model replaces the internally managed encryption keys used by earlier releases. Master keys now live in an external keyring rather than being managed internally by the Controller, and DEKs are directly manageable, with their own rotation and lifecycle. Together these changes place both tiers of the envelope under your control, whereas in earlier releases neither layer was exposed for management.
Backward compatibility is preserved in mixed environments. A DEK-enabled Controller can still decrypt legacy encrypted values produced by older Controllers, and it can continue to operate alongside other Controllers that have not yet been DEK-enabled. When you transition to managing your own keys, all encrypted values are re-encrypted under the new model. See Credentials Compatibility for backward-compatibility details.
Envelope Encryption Model
Encryption is layered in two tiers:
- Sensitive data is encrypted with a Data Encryption Key (DEK).
- Each DEK is itself encrypted ("wrapped") by a Key Encryption Key (KEK).
The encrypted DEKs are stored in the Controller database, while the KEKs are stored in an external keyring file. This ensures that the KEKs never reside alongside the DEKs they encrypt, maintaining separation between the two tiers of the envelope.
Key Encryption Keys and Data Encryption Keys
| Key Type | Where it lives | What it protects |
|---|---|---|
| Key Encryption Key (KEK) | An external keyring file, loaded from the path specified by uc.keyring.file or from the UC_KEYRING_BASE64 environment variable. Created and rotated with the Keyring Manager. | Wraps (encrypts) the Data Encryption Keys, and encrypts sensitive values in the Controller's uc.properties configuration file. |
| Data Encryption Key (DEK) | The Controller database, wrapped by a KEK. Managed through Data Encryption Key Settings. | Encrypts the actual sensitive data records (credentials, secrets, and similar values). |
Data Encryption Key Types
A separate DEK is maintained for each type of data it protects. Each type appears as its own tab in Data Encryption Key Settings, which corresponds to the value of the Type field on a Data Encryption Key record.
| Type | Protects |
|---|---|
| Standard | Standard Credentials (passwords, passphrases, and Secrets Provider parameters); Agent auth keys; Email Connection passwords; LDAP bind password; Bundle Target and Promotion Schedule passwords and auth tokens; SAML Single Sign-On keystore passwords; AI Settings API keys. |
| Resolvable | Resolvable Credentials (passwords, passphrases, tokens, and Secrets Provider parameters). |
| Web Service | Web Service Credentials (passwords, passphrases, and Secrets Provider parameters). |
| Email Credentials (passwords, passphrases, and Secrets Provider parameters). | |
| SAP | SAP Credentials (passwords, passphrases, and Secrets Provider parameters). |
| OAuth Client | OAuth Single Sign-On settings client secrets and OAuth Client configuration client secrets. |
| Data Store | OAuth2 tokens (access and refresh tokens) that the Controller obtains and stores when authenticating to external OAuth2 providers, such as Email Connections using OAuth2. |
Key Statuses
Every Data Encryption Key has one of the following statuses:
| Status | Description |
|---|---|
| Primary | There is exactly one Primary key per type. The Primary key is used to encrypt all new and updated values of that type. |
| Available | A valid key that is not the Primary. Available keys are retained so that values they previously encrypted remain decryptable. For example, a Data Encryption Key promoted in from another Controller is created with a status of Available, because each type can have only one Primary key. |
| Deprecated | A key that has been retired from encrypting new values (typically the result of a Rotate or Deprecate operation). Deprecated keys remain available for decryption. |
Rotation, Deprecation, and Re-encryption
The key lifecycle is managed from Data Encryption Key Settings and the Rotate, Deprecate, and Promote commands:
- Rotate deprecates the current Primary key and generates a new Primary key for that type.
- Deprecate retires an Available key.
- Promote copies a Primary key to another Controller. See Promotion and Import/Export.
Enabling Data Encryption Keys, rotating a key, or deprecating a key triggers a background process that re-encrypts stored values of the affected type with the current Primary key. Over time, this migrates your encrypted data onto the latest keys.
Deprecation
Deprecating a key retires it from encrypting new values while keeping it available for decryption, so previously-encrypted data remains readable. For details, including the grace period that governs deprecated-key logging, see Deprecation and the Grace Period.
Cluster Considerations
Only the active cluster node makes changes to Data Encryption Keys; insert, update, delete, rotation, and deprecation operations are rejected on passive nodes. Passive nodes reload Data Encryption Keys from the database as needed.
Roles and Permissions
Access to encryption keys is governed by roles:
| Action | Required role |
|---|---|
| View Data Encryption Key Settings and keys | ops_admin or ops_service |
| Enable Data Encryption Keys and update settings | ops_admin |
| Rotate, Deprecate, and Promote keys | ops_admin |
Getting Started
- Configure the Keyring Manager and put a valid keyring file in place. A configured keyring is required to enable Data Encryption Keys.
- Enable Data Encryption Keys from Data Encryption Key Settings. A Primary key is generated for each type, and existing sensitive values are re-encrypted under the new keys.
- Manage keys over time using the Rotate, Deprecate, and Promote commands.