Version 26.1.9595

• Understanding Data Encryption Keys and Master Keys
• Define Custom Master Key
• Change Master Key
• Use Safe Mode

CData Arc uses a master key to secure sensitive encrypted data such as passwords, API keys, and connection credentials stored in connector configurations. By default, Arc 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 Arc’s encryption practices with their internal security policies, comply with regulatory requirements, and integrate with existing key management systems.

Important: Losing access to a custom master key prevents Arc from decrypting stored credentials and configuration data. You should implement secure key backup and recovery procedures before configuring a custom master key.

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, Arc 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. Arc 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 Arc edition type.

• Cross-Platform edition: Define the key using the cdata.encryption.key property in the arc.properties configuration file. If you are defining a PFX key and require a password, set it in the 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:

  <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. Arc 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: Arc only supports the RSA algorithm in PFX certficate files. Other DSA or ECC certificates are rejected.

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 Arc 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.