> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sync.cdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Defining a Custom Master Key

export const siteNameShortLower = "sync";

export const siteNameShort = "Sync";

export const siteName = "CData Sync";

<Note>This page has content that is only applicable to {siteNameShort} Self-Hosted deployments.</Note>

{siteName} 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. {siteNameShort} 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 {siteNameShort}'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

<Warning>If you lose access to a custom master key, {siteNameShort} 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.</Warning>

## Understanding Data Encryption Keys and Master Keys

Encryption uses a key to convert plaintext into ciphertext. When you first begin using {siteNameShort}, 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 {siteNameShort} 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 {siteNameShort} by configuring encryption properties. Configure these settings in {siteNameShort} 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. {siteNameShort} uses the currently configured key for all encryption operations.

To change the master key:

1. Stop the {siteNameShort} 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:

     ```bash theme={null}
     java -jar sync.jar -ChangeMasterKey <NewMasterKeyFilePath>
     ```

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

     ```bash theme={null}
     java -jar sync.jar -ChangeMasterKey <NewMasterKeyFilePath> <NewMasterKeyPassword>
     ```

3. Restart {siteNameShort} 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 {siteNameShort} 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:

```bash theme={null}
java -jar arc.jar -safemode
```