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:
In the command line, browse to your
<Portal for ArcGIS install directory>/tools/recoverinvariantsfolder.In the command line, browse to your
<Portal for ArcGIS install directory>\tools\recoverinvariantsfolder.Run the following command:
recover-invariants -r <recovery codes file>recover-invariants.bat -r <recovery codes file>For assistance, run the command with
-hor--help.
To regenerate the primary encryption key for a server site, complete the following steps:
In the command line, browse to your
<Server install directory>/tools/recoverinvariantsfolder.In the command line, browse to your
<Server install directory>\tools\recoverinvariantsfolder.Run the following command:
recover-invariants.sh -r <recovery codes file>recover-invariants.bat -r <recovery codes file>For assistance, run the command with
-hor--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.