Skip to main content

Manage primary encryption keys

Each component of ArcGIS Enterprise encrypts sensitive data. To encrypt that data, an encryption key is necessary. The most fundamental encryption key is called the primary encryption key. The primary encryption key is generated randomly using a cryptographically secure method, is not stored in plaintext, and is unique to your ArcGIS Enterprise components.

When ArcGIS Enterprise first generates the primary encryption key, it creates a recovery codes file that can be used to regenerate the cryptographic invariants needed for the primary encryption key. It is recommended that an administrator obtain the recovery codes file, store it in a secure place, and ensure that other administrators know where it is stored. If the primary encryption key for a component becomes corrupted, that component cannot start and the software does not function until you recover the primary encryption key.

Preserve the recovery codes

By default, Portal for ArcGIS, ArcGIS Data Store, and each server site store the recovery codes file in <installation directory>/framework/etc/recovery_codes.txt for each component. Store this file in a secure location. When you have preserved the recovery codes file, you can delete the file from each machine.

By default, Portal for ArcGIS, ArcGIS Data Store, and each server site store the recovery codes file in <installation directory>\framework\etc\recovery_codes.txt for each component. Store this file in a secure location. When you have preserved the recovery codes file, you can delete the file from each machine.

Specify a recovery codes file

In most cases, it is advisable to let ArcGIS Enterprise randomly generate the primary encryption key. However, there may be situations where you want to use the same primary encryption key across ArcGIS Enterprise components or deployments. To specify a primary encryption key, supply the recovery codes file when using the following command line utilities or REST APIs:

Component Command line utilities REST APIs
Portal for ArcGIS createportal or upgradeportal Create New Site or Upgrade
ArcGIS Data Store configuredatastore None
ArcGIS Server createsite or upgradeserver Create New Site or Upgrade
ArcGIS Data Pipelines Server createsite or upgradesite Create New Site
ArcGIS Mission Server createsite or upgradesite Create Site
ArcGIS Notebook Server createsite or upgradesite Create New Site or Upgrade Site
ArcGIS Velocity Server createsite or upgradesite Create New Site or Upgrade
ArcGIS Video Server createsite or upgradesite None

Because a given recovery codes file always generates the same primary encryption key, using the same recovery codes file for multiple components generates the same encryption key across those components.

Recover the primary encryption key

If the primary encryption key becomes corrupted, you either need to use the recovery codes file if it is available or restore from backup.

Recovery codes file is available

If the recovery codes file is available, you can use a command line utility to regenerate the primary encryption key. If you do not specify a recovery codes file, the utility uses the default recovery codes file location.

To recover the primary encryption key for Portal for ArcGIS, complete the following steps:

  1. In the command line, browse to your <Portal for ArcGIS install directory>/tools/recoverinvariants folder.

  2. In the command line, browse to your <Portal for ArcGIS install directory>\tools\recoverinvariants folder.

  3. Run the following command:

    recover-invariants -r <recovery codes file>

    recover-invariants.bat -r <recovery codes file>

    For assistance, run the command with -h or --help.

To regenerate the primary encryption key for a server site, complete the following steps:

  1. In the command line, browse to your <Server install directory>/tools/recoverinvariants folder.

  2. In the command line, browse to your <Server install directory>\tools\recoverinvariants folder.

  3. Run the following command:

    recover-invariants.sh -r <recovery codes file>

    recover-invariants.bat -r <recovery codes file>

    For assistance, run the command with -h or --help.

To regenerate the primary encryption key for ArcGIS Data Store, run the recoverinvariants utility.

Recovery codes file is unavailable

If you do not have a recovery codes file, you must create a new ArcGIS Enterprise deployment and restore it from backup. See Migrate ArcGIS Enterprise with WebGISDR for more information on how to restore ArcGIS Enterprise to a new environment.