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

# Defining a Custom Master Key

> How to configure and rotate custom master keys for encrypting sensitive data in CData Arc.

export const siteNameShort = "Arc";

export const siteName = "CData Arc";

{siteName} uses a master key to secure sensitive encrypted data such as passwords, API keys, and connection credentials stored in connector configurations. By default, {siteNameShort} provides a built-in master key, but organizations with strict security requirements can define custom master keys to maintain full control over their encryption infrastructure. This enables you to easily rotate user-defined master keys.

Master keys can be provided in two formats: As a random character string in an AES key file or as a PFX (PKCS#12) certificate file with optional password protection. Custom master keys enable enterprises to align {siteNameShort}'s encryption practices with their internal security policies, comply with regulatory requirements, and integrate with existing key management systems.

<Warning>Losing access to a custom master key prevents {siteNameShort} from decrypting stored credentials and configuration data. You should implement secure key backup and recovery procedures before configuring a custom master key.</Warning>

### Understanding Data Encryption Keys and Master Keys

Encryption works by using a *key*, which is a piece of data, to scramble plaintext into ciphertext. When you first begin using the application, {siteNameShort} generates a random key that is never saved in plaintext anywhere. That is the *data encryption key*, or DEK. All data is encrypted using this key.

A *master key* (also known as a Key Encryption Key or KEK) does not encrypt data directly. Instead, it is a wrapper which encrypts other keys. {siteNameShort} also provides a built-in master key, but as mentioned above, you can define your own master key instead. The remainder of this topic describes how to create or update your user-defined master key.

## Define Custom Master Key

The way in which you define a master key varies by {siteNameShort} edition type.

* **Cross-Platform edition:** Define the key using the [cdata.encryption.key](./arc-properties-configuration#cdata-encryption-key) property in the [arc.properties](./arc-properties-configuration) configuration file. If you are defining a PFX key and require a password, set it in the [cdata.encryption.key.password](./arc-properties-configuration#cdata-encryption-key-password) property. Alternatively, if you are using an AES key, you can use the `APP_KEY` environment variable to supply the file path to the key file.

* **.NET edition:** If you do not find an `AppKey` setting inside your `appSettings` element in the Web.Config file, master key encryption is disabled. To enable it, set a file path in the `AppKey` setting element in the Web.Config file. If you are defining a PFX key and require a password, set it in the `AppKeyPassword` setting. Here is the XML snippet in Web.Config that you need to add:

  ```xml theme={null}
  <appSettings>
    <!-- The path to the master key file to use for encryption. To replace an existing master key, do not modify this file. Instead, you must use: CData.exe appChangeMasterKey -NewKey <new-master-key-path>. -->
    <add key="AppKey" value="C:\Keys\mykey.pfx" />
    <add key="AppKeyPassword" value="Password123" />
  </appSettings>
  ```

## Change Master Key

If necessary, you can replace the master key file. {siteNameShort} always uses the key that you have provided for encryption. Key files are securely managed and backed up, and the process is designed to minimize risk and complexity for users. To change the master key, ensure that you have stopped the server, then use one of the following options:

* **Cross-Platform edition:** Administrators can use the `arc.jar -ChangeMasterKey <new-master-key-file-path>` command to rotate the encryption key without disrupting operations. If you are changing the master key to a PFX file, and you require a password, use the `arc.jar -ChangeMasterKey <new-master-key-file-path> <new-master-key-password>` command.
* **.NET edition:** Administrators must use the `CData.exe appChangeMasterKey -NewKey <new-master-key-file-path> -@libdir "www\bin"` command (do not modify the Web.Config file directly). If you are changing the master key to a PFX file, and need a password, use the `CData.exe appChangeMasterKey -NewKey <new-master-key-file-path> -NewKeyPassword <new-PFX-password> -@libdir "www\bin"` command.

<Note>{siteNameShort} only supports the RSA algorithm in PFX certificate files. Other DSA or ECC certificates are rejected.</Note>

## Use Safe Mode

If you lose your custom master key and need to re-save your configuration's sensitive values (from another source of record that you have), you can start {siteNameShort} in safe mode. This disables all backend automation services and enables very limited features so you can try to recover your settings and other tasks. To enable safe mode:

* **Cross-Platform edition:** Run `java -jar arc.jar -safemode`
* **.NET edition:** Add `<add key="SafeMode" value="true" />` to the `appSettings` element of your Web.Config file.