Configure encryption keysedit

Enterprise Search is designed to keep synchronization information and access tokens secure at all times. To ensure safe storage of credentials and other secrets, encryption keys must be provided when starting and deploying the service.

To configure encryption keys, locate the config/enterprise-search.yml configuration file in the Enterprise Search directory, and set a secret_management.encryption_keys value:

secret_management.encryption_keys: [{encryption_key1}, {encryption_key2}, {...}]

secret_management.encryption_keys requires an array of values with at least one encryption key. We recommend rotating encryption keys over time, and Enterprise Search lets you set multiple encryption keys to enable proper security practices.

Should an encryption key be misplaced or lost, the encrypted access tokens and source synchronization credentials will no longer be accessible, and content synchronization will be halted for all sources until they are re-authenticated.

When a new value is added to the encryption_keys aray, Enterprise Search will attempt to decrypt secrets from the first entry, moving across the array until success. Secrets are re-encrypted with the last key in the array when rewritten.

We strongly recommend using 256-bit encryption key values, and rotating keys on a regular basis.

Generating encryption keysedit

There are several techniques for generating secure random 256-bit encryption keys.

On systems with openssl installed, run:

openssl rand -hex 32

Or on Linux environments without openssl, including empty docker containers for CentOS, Ubuntu, Debian, Alpine and even in a busybox environment, run this command:

od  -vN 32 -An -tx1 /dev/urandom | tr -d " \n" ; echo

If you do not specify a secret_management.encryption_keys value in the config/enterprise-search.yml file and run Enterprise Search, Enterprise Search will fail to start. But before failing, Enterprise Search will generate and display an example encryption key that you can copy and paste into the configuration file.