Version 26.1.9515

• Define Custom Master Key
• Change Master Key
• Use Safe Mode

CData Arc uses a master encryption key to secure sensitive data such as passwords, API keys, and connection credentials stored in connector configurations. By default, Arc provides a built-in encryption key, but organizations with strict security requirements can define custom master keys to maintain full control over their encryption infrastructure.

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.

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: 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 modify:

  <appSettings> 
    <!-- The path to the master key file used for encryption. To replace the current master key, 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 can use the CData.exe appChangeMasterKey -NewKey <new-master-key-file-path> -@libdir "www\bin" command. 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.