Skip to main content
This page has content that is only applicable to Self-Hosted deployments.
uses a master key to encrypt sensitive configuration data , including passwords, API keys, and connection credentials. This key is part of the application’s encryption framework and is applied automatically to protect stored values. includes a built-in master key by default, but you can configure a custom master key if your environment requires direct control over encryption and key management. Custom master keys enable you to align ‘s encryption practices with internal security policies, comply with regulatory requirements, and integrate with existing key management systems. They also enable you to rotate encryption keys as part of standard security operations. Master keys can be provided in the following formats:
  • an AES key file that contains a random character string
  • a PFX (PKCS#12) certificate file with optional password protection
If you lose access to a custom master key, cannot decrypt stored credentials or configuration data. To avoid this issue, you should implement secure key backup and recovery procedures before you configure a custom master key.

​
Understanding Data Encryption Keys and Master Keys

Encryption uses a key to convert plaintext into ciphertext. When you first begin using , the application generates a random data encryption key (DEK). This key is not stored in plaintext and is used to encrypt all sensitive data. A master key, also known as a key encryption key (KEK), does not encrypt data directly. Instead, it encrypts the DEK. This approach allows to protect sensitive data while enabling key rotation without requiring all stored data to be re-encrypted.

​
Defining a Custom Master Key

You can define a custom master key in by configuring encryption properties. Configure these settings in in either the sync.properties file configuration file or as environment variables.
  • If you are using a PFX certificate that requires a password, set the cdata.encryption.key.password property in sync.properties.
  • If you are using an AES key file, you can supply the key path in the sync.properties file or by using the APP_KEY environment variable.

​
Changing the Master Key

You can change the master key file, if necessary. uses the currently configured key for all encryption operations. To change the master key:
  1. Stop the service and ensure that the new key file is securely stored and backed up.
  2. Use one of the following commands to update the master key without disrupting operations:
    • To change the master key to a new key file:
    • To change the master key if it is a PFX file that requires a password:
  3. Restart to apply the changes.

​
Using Safe Mode

If you lose access to your custom master key and need to reconfigure sensitive values, you can start in safe mode. Safe mode disables most background services and allows limited features so you try to recover your settings and other tasks. To enable safe mode, run the following command: