Version 26.2.9623

• Understanding Data Encryption Keys and Master Keys
• Defining a Custom Master Key
• Changing the Master Key
• Using Safe Mode

CData Sync 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. Sync 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 Sync’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

Important: If you lose access to a custom master key, Sync 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 Sync, 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 Sync 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 Sync by configuring encryption properties. Configure these settings in Sync 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. Sync uses the currently configured key for all encryption operations.

To change the master key:

1. Stop the Sync 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:

     java -jar sync.jar -ChangeMasterKey <NewMasterKeyFilePath>
     

   • To change the master key if it is a PFX file that requires a password:

     java -jar sync.jar -ChangeMasterKey <NewMasterKeyFilePath> <NewMasterKeyPassword>
     

3. Restart Sync 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 Sync 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:

java -jar arc.jar -safemode