Configure encryption keys
editConfigure encryption keys
editEnterprise Search is designed to keep content source synchronization credentials, API tokens and other sensitive information secure at all times. Data protection at rest is implemented by using a set of encryption keys shared between all nodes of an Enterprise Search deployment. To ensure safe storage of your sensitive information, encryption keys must be provided when starting and deploying the service.
When running on Elastic Cloud or Elastic Cloud on Kubernetes (ECK), the platform takes care of your encryption secrets and you are not required to set them yourselves.
Encryption keys configuration
editTo 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. Each key value needs to be a unique string and we recommend using a random value that is impossible to guess (256-bits or longer). See the dedicated section below on how you can generate a secure encryption key.
Since encryption keys are used to persist data in an Elasticsearch cluster shared by all nodes of an Enterprise Search deployment, you need to ensure all nodes within an Enterprise search deployment share the same set of encryption keys. Failure to configure the same keys across all nodes will lead to data inconsistencies and potential data loss.
When restoring an Enterprise Search deployment from a backup, you need to make sure your configuration file contains the right set of encryption keys to allow you to gain access to the restored dataset (on Elastic Cloud it happens automatically).
Protecting your encryption keys
editThe keys configured in the configuration file should be treated as sensitive information and protected from unauthorized access by third parties and from data loss. We recommend using permissions that do not allow reads by anybody but the owner (0640 or -rw-r----), storing the configuration file on an encrypted disk volume and encrypting the file during filesystem backups.
In Docker and Kubernetes environments, we recommend using Docker secrets or Kubernetes encrypted secrets to protect your encryption keys and provide them to the deployment via container environment variables.
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.
We recommend you save your keys in a password manager or some other secure storage to ensure you would not lose access to encrypted data in Enterprise Search.
Using multiple keys and key rotation
editFollowing the well-established security practices and various compliance requirements around the world, we recommend periodically rotating your encryption keys.
To support graceful key rotation, Enterprise Search lets you set multiple encryption keys. When a new value is added to the encryption_keys array, 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, which effectively allows you to rotate encryption secrets without downtime.
Generating encryption keys
editThere 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.