Migrating keystores

This section describes the process for rotating or migrating encryption keys used to encrypt data at rest in the PostgreSQL metastore. The process for rotating keys includes the following steps:

  • Create your keystore. The keystore must be in one of the following formats: BCFKS, JCEKS, or PKCS12. Note that BCFKS is required for FIPS compliance. Both the keystore and the private key must be password-protected. The keystore file must be located in a path accessible by the running application. For more information on creating an initial keystore, go to Setting up a custom keystore in Collibra DQ.

  • Choose a method for providing secrets:

    • Environment variables (recommended for self-hosted Kubernetes): The best practice for cloud-native and containerized environments. For this, simply set the relevant environment variables.

    • File-based configuration tree (recommended for Standalone servers): A secure alternative for single-server or non-containerized deployments or an alternative approach for containerized deployments.

  • Set the properties. The following sections describe the necessary properties.

Set migration properties

Declare the following migration properties.

Environment variable Description
DQ_APP_ENCRYPTION_AT_REST_MODE

Specifies whether to use the legacy or hybrid cryptosystem. To migrate keystores, set to hybrid.

Default is legacy.
DQ_APP_ENCRYPTION_AT_REST_MIGRATION

For existing customers that need to migrate from legacy to hybrid encryption at rest mode. When set to true, performs migration to new encryption key during startup. After completing the initial migration, disable this setting.

Default is false.

Set new keystore properties

Declare the following information about the new keystore.

Environment variable Description
KEYSTORE_SECRETS_SOURCE The type of keystore secrets source. For example, file.

KEYSTORE_FILEPATH

The path to the new keystore file. For example, /app/config/new-keystore.jceks.

KEYSTORE_TYPE

The type of the new keystore file. Allowable values are BCFKS, PKCS12 (extension .p12) or JCEKS.

KEYSTORE_PASSWORD

The password for the new keystore file. We recommend using a configuration tree file for this value.

KEYSTORE_PRIVATEKEY_PASSWORD

The password for the new private key. We recommend using a configuration tree file for this value.

Note Because of a standard java implementation detail, for PKCS12 format only, the private key password and the keystore pass often need to be the same value.

KEYSTORE_PRIVATEKEY_ALIAS

The alias for the new private key.

KEYSTORE_PUBLICKEY_ALIAS

The alias for the new public key.

Set prior keystore properties

If migrating to a new keystore, you must declare information about the prior keystore.

Environment variable Description

KEYSTORE_PRIOR_SECRETS_SOURCE

The type of the prior keystore secrets source. For example, file.

KEYSTORE_PRIOR_FILEPATH

The path to the old (prior) keystore file. For example, /app/config/old-keystore.jceks.

KEYSTORE_PRIOR_TYPE

The type of the prior keystore file. Allowable values are BCFKS, PKCS12, or JCEKS.

KEYSTORE_PRIOR_PASSWORD

The password for the prior keystore file. We recommend using a configuration tree file for this value.

KEYSTORE_PRIOR_PRIVATEKEY_PASSWORD

The password for the prior private key.

KEYSTORE_PRIOR_PRIVATEKEY_ALIAS

The alias for the prior private key.

Secure the master password

For enhanced security, we recommend using a file-based configuration tree to store critical secrets like passwords. This is a powerful feature of Spring Boot. For more details, go to the Spring Boot documentation on external configuration.

To use this method, specify the path to your secret directory in your primary configuration file, application.properties.

Copy 
spring.config.import=optional:configtree:/opt/owl/config/secrets/

The passwords will be read from files with the same name as their keys. For example, the contents of a file at the location keystore/privatekey/password relative to the spring.config.import path will be used for the KEYSTORE_PRIVATEKEY_PASSWORD variable.

Perform the migration

After setting the properties, start your DQ Application. The migration runner automatically detects the configuration and executes the migration scripts. Once the migration is complete, remove the migration properties and the prior keystore properties to return the application to its normal operational state.

Note If multi-tenant mode is enabled, note that Data Quality & Observability Classic supports only one keystore for the entire installation, across all tenants. Accordingly, the migration for multi-tenant mode applies to all tenants, both enabled and disabled tenants will be migrated.