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:

1. Stop Looker and create a full backup
2. Set _SOURCE and _DESTINATION environment variables
3. Run the rekey command
4. Set new environment variables
5. 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 AWS CMK_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

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
• Changing the encryption key a subsequent time

Changing the encryption key the first time

1. 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=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

2. If you’re using an older version of the looker startup script, you may need to update it. You can download the latest version of the looker 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 $1

   Then change the line to the following:

   java -jar looker.jar $*

3. Generate a new key:

   ./looker generate_key --new-cipher-key-file key1

   You 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_file

4. Tell 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 key1

   If 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-db

5. Configure 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.

6. Start Looker:

   ./looker start

Changing the encryption key a subsequent time

1. 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=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

2. Generate a new key:

   ./looker generate_key --new-cipher-key-file key2

   You 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

3. Tell 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 key1

   If 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-db

4. Update 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"

5. 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, replacing KEYFILE with the actual filename.
• You can see command line options for managing Looker and its keys by issuing looker help and looker --help.
• You can see additional information for key management commands by issuing the command with help before it. For example: looker help generate_key.