Looker uses AES-256 Galois/Counter Mode (GCM) encryption to encrypt data internally. Every item of data is encrypted using a unique data key and contains a signed and versioned encryption envelope to guarantee verification. This mode requires the use of an external Customer Master Key (CMK). The CMK is used to derive, encrypt, and decrypt the Key Encryption Key (KEK), which in turn is used to derive, encrypt, and decrypt data keys.
Customer-hosted installations that are using legacy encryption must migrate their internal databases to AES-256 GCM encryption. New customer-hosted installations need to configure their installations for AES-256 GCM encryption. See the Using AES-256 GCM encryption documentation page for instructions on migrating or configuring your customer-hosted installation for AES-256 GCM encryption.
This page includes instructions for rekeying AES-256 GCM encryption if you’re using the new GCM encryption or changing legacy encryption keys if you’re using the legacy 128-bit encryption.
Rekeying AES-256 GCM encryption
If you want to change your CMK, or if you want to move from a local key-based configuration to an AWS KMS configuration (or the reverse), you can do so by creating a new CMK and rekeying your AES-256 GCM encryption.
Rekeying is done offline, meaning that the Looker instance must be shut down. For clustered Looker instances, all nodes of the cluster must be shut down.
Rekeying invalidates the entire Looker on-disk cache, including the query result cache. As a result, after you complete a rekey and start up the instance, the client databases may experience higher than usual load.
To rekey AES-256 GCM encryption, perform the following procedures:
- Stop Looker and create a full backup
- Set
_SOURCE
and_DESTINATION
environment variables - Run the
rekey
command - Set new environment variables
- Start Looker
Stop Looker and create a full backup
Issue the following commands:
cd looker
./looker stop
tar -zcvf /tmp/looker-pre-encrypt.tar.gz /home/lookerops/looker --exclude=.cache --exclude=log --exclude=.tmp --exclude=.snapshots --exclude=looker.jar --exclude=authorized_keys --exclude=dr-log --exclude=core
If you are running an external MySQL database to store Looker application data, back up the database separately. If the database is a MySQL instance, take a snapshot. The database is relatively small, so it should only take a few minutes.
If Looker is clustered, make sure to stop every node before proceeding:
cd looker
./looker stop
If any nodes are still running when you later issue the rekey
command, the command will fail with the message, “There are other live nodes connected to this backend Looker database. If Looker was shutdown within the last minute, try again shortly, otherwise verify all nodes in the cluster are shut down.”
Set _SOURCE
and _DESTINATION
environment variables
When your Looker instance was initially migrated to or configured for AES-256 GCM encryption, one or more environment variables were created that indicate where Looker can find your CMK. These variables differ depending on whether you are using AWS KMS.
The rekey operation uses additional environment variables, based on whether you are currently using AWS KMS, and whether you will use AWS KMS after the rekey operation. Environment variables with the suffix _SOURCE
indicate where Looker can currently find your CMK, and environment variables with the suffix _DESTINATION
indicate where Looker can find your CMK after the rekey operation.
Setting _SOURCE
variables
Perform one of the following procedures, depending on whether your current configuration uses AWS KMS.
If you are currently using AWS KMS
If you initially configured your encryption using AWS KMS, you created one or both of the following environment variables:
LKR_AWS_CMK
: Stores the AWSCMK_alias
.LKR_AWS_CMK_EC
: An optional variable that defines the encryption context used with AWS KMS keystores.
Recreate the environment variables above:
export LKR_AWS_CMK=alias/<CMK_alias>
export LKR_AWS_CMK_EC=<encryption_context>
Then create the _SOURCE
variables. Set the following new variables with the _SOURCE
suffix:
export LKR_AWS_CMK_SOURCE=alias/<CMK_alias>
export LKR_AWS_CMK_EC_SOURCE=<encryption_context>
If you are not currently using AWS KMS
If you initially configured your encryption using a KMS other than AWS, you created one of the following environment variables, depending on whether you store your CMK in an environment variable or in a file on your instance:
LKR_MASTER_KEY_ENV
: If you store your CMK in an environment variable, this stores your CMK.LKR_MASTER_KEY_FILE
: If you store your CMK in a file, this stores the path and filename of the file containing your CMK.
Recreate the environment variable used for your configuration:
export LKR_MASTER_KEY_FILE=<path_to_key_file>
Or:
export LKR_MASTER_KEY_ENV=<CMK_value>
Then create the _SOURCE
variable.
If you store your CMK in a file, create the following variable:
export LKR_MASTER_KEY_FILE_SOURCE=<path_to_key_file>
If you store your CMK in an environment variable, create the following variable:
export LKR_MASTER_KEY_ENV_SOURCE=<CMK_value>
Setting _DESTINATION
variables
Perform one of the following procedures, depending on whether you will use AWS KMS after the rekey operation.
Your new configuration will use AWS KMS
If your new configuration will use AWS KMS, create the following environment variables to indicate the new CMK location:
export LKR_AWS_CMK_DESTINATION=alias/<new_CMK_alias>
export LKR_AWS_CMK_EC_DESTINATION=<new_encryption_context>
Your new configuration will not use AWS KMS
If your new configuration will not use AWS KMS, you have the option of using the LKR_MASTER_KEY_FILE_DESTINATION
or LKR_MASTER_KEY_ENV_DESTINATION
variables to specify the CMK destination.
If you want to store your CMK in a file, issue the following command:
export LKR_MASTER_KEY_FILE_DESTINATION=<path_to_new_key_file>
Or, if you want to store your CMK using an environment variable, issue the following command:
export LKR_MASTER_KEY_ENV_DESTINATION=<CMK_value>
Run the rekey
command
Issue the following command:
./looker rekey
Set new environment variables
Set one or more of the following environment variables as appropriate for your new configuration.
If your new configuration uses AWS KMS:
export LKR_AWS_CMK=alias/<new_CMK_alias>
export LKR_AWS_CMK_EC=<new_encryption_context>
If your new configuration does not use AWS KMS and you store your CMK in an environment variable:
export LKR_MASTER_KEY_ENV=<CMK_value>
If your new configuration does not use AWS KMS and you store your CMK in a file:
export LKR_MASTER_KEY_FILE=<path_to_CMK_file>
If you moved from a locally stored key to AWS KMS or from AWS KMS to a locally stored key, you will have environment variables from your previous configuration that are unnecessary. Delete the old environment variables.
If you moved from a locally stored key to AWS KMS:
unset LKR_MASTER_KEY_FILE
If you moved from AWS KMS to a locally stored key:
unset LKR_AWS_CMK
unset LKR_AWS_CMK_EC
Start Looker
Issue the following command:
./looker start
Changing legacy encryption keys
There is a known vulnerability in the legacy 128-bit encryption: Google strongly recommends that all customer-hosted instances migrate to AES-256 GCM encryption.
This section contains instructions for changing encryption keys for customer-hosted installations using the legacy 128-bit encryption.
Be sure to follow all the following steps. This process can permanently destroy data if completed improperly.
Depending on whether you’ve previously changed your encryption key, see one of the following procedures:
Changing the encryption key the first time
Stop Looker and create a full backup:
cd looker ./looker stop tar -zcvf /tmp/looker-pre-encrypt.tar.gz /home/lookerops/looker --exclude=.cache --exclude=log --exclude=.tmp --exclude=.snapshots --exclude=looker.jar --exclude=authorized_keys --exclude=dr-log --exclude=coreIf you are running an external MySQL database to store Looker application data, back up the database separately. If the database is a MySQL instance, take a snapshot. The database is relatively small, so it should only take a few minutes.
If Looker is clustered, make sure to stop every node before proceeding!
cd looker ./looker stopIf you’re using an older version of the
looker
startup script, you may need to update it. You can download the latest version of thelooker
startup script on this Looker Github page.If you’ve customized your copy of the script and don’t want to use the latest official version, look for the following line toward the bottom of the file:
java -jar looker.jar $1Then change the line to the following:
java -jar looker.jar $*Generate a new key:
./looker generate_key --new-cipher-key-file key1You can also generate your own key file. In that case, the file should contain a 128-bit, randomly chosen number formatted as a 32-character hex string. If you use your own key file, issue the following command to make your key file read-only:
chmod 0600 my_key_fileTell Looker to re-encrypt its data with the new key.
If you’re using Looker’s default application data store, HyperSQL:
./looker change_key --new-cipher-key-file key1If you’re using an external database for Looker application data with connection details stored in a file named
looker-db
:./looker change_key --new-cipher-key-file key1 -d looker-dbConfigure Looker to use the new key file on startup. Edit or create a file named
lookerstart.cfg
with the following contents:LOOKERARGS="--cipher-key-file key1"There may be other options already present inside the quotes. Add
--cipher-key-file
and the filename.Start Looker:
./looker start
Changing the encryption key a subsequent time
Stop Looker and create a full backup:
cd looker ./looker stop tar -zcvf /tmp/looker-pre-encrypt.tar.gz /home/lookerops/looker --exclude=.cache --exclude=log --exclude=.tmp --exclude=.snapshots --exclude=looker.jar --exclude=authorized_keys --exclude=dr-log --exclude=coreIf you are running an external MySQL database to store Looker application data, back up the database separately. If the database is a MySQL instance, take a snapshot. The database is relatively small, so it should only take a few minutes.
If Looker is clustered, make sure to stop every node before proceeding!
cd looker ./looker stopGenerate a new key:
./looker generate_key --new-cipher-key-file key2You can also generate your own key file. In that case, the file should contain a 128-bit, randomly chosen number formatted as a 32-character hex string. If you use your own key file, issue the following command to make your key file read-only:
chmod 0600Tell Looker to re-encrypt its data with the new key.
If you’re using Looker’s default application data store, HyperSQL:
./looker change_key --new-cipher-key-file key2 --cipher-key-file key1If you’re using an external database for Looker application data with connection details stored in a file named
looker-db
:./looker change_key --new-cipher-key-file key2 --cipher-key-file key1 -d looker-dbUpdate the key filename in
lookerstart.cfg
. There may be other options inside the quotes. Change the value for--cipher-key-file
:LOOKERARGS="--cipher-key-file key2"Start Looker:
./looker start
Important notes
- Keep a copy of all keys in a safe, secure place. The retention policy on these key files should match the retention period of your database because one is useless without the other. IF YOU LOSE THE ENCRYPTION KEY, YOUR ENCRYPTED DATA WILL BE LOST.
- The re-encryption step currently takes less than a minute.
- If you create the key file manually, you must issue
chmod 0600 KEYFILE
to set permissions correctly, replacingKEYFILE
with the actual filename. - You can see command line options for managing Looker and its keys by issuing
looker help
andlooker --help
. - You can see additional information for key management commands by issuing the command with
help
before it. For example:looker help generate_key
.