home User Guide Getting Started Help Center Documentation Community Training Certification
Looker keyboard_arrow_down
language keyboard_arrow_down
Migrating to AES-256 GCM encryption

Looker uses AES-256 Galois/Counter Mode (GCM) encryption to encrypt sensitive data that is stored internally, including:

For a detailed list of the data that Looker encrypts, contact your Account Manager or open a support request in Looker’s Help Center by clicking Contact Us.

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.

Encryption is used only for Looker’s internal database and cache. Customer databases are not affected by Looker’s encryption in any way. In addition, only static data (data stored on disk) is encrypted in this manner.

Customer-hosted installations can use their own AWS KMS accounts or their own custom key management systems. All data keys and the KEK are encrypted and used internally on the customer-hosted Looker installation. If not using AWS KMS, the external CMK should be kept securely.

Existing customer-hosted installations that want to use GCM encryption need to migrate from the legacy encryption to the new GCM encryption. New customer-hosted installations require additional configuration for GCM encryption.

Follow the procedures in the following sections in order.

Stopping Looker and creating a full backup

If you are migrating to GCM encryption from an existing Looker instance, be sure to create a full backup in case there is a problem with the encryption migration. If you are installing a new Looker instance, skip this section.

If you are using Looker’s internal database:

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. Then stop Looker.

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 migration 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.”

Generating a CMK

If you are using AWS KMS, create a CMK using either the AWS Management Console or the API.

If you are not using AWS KMS, generate a Base64, 32-byte CMK. You can store the CMK either in an environment variable or in a file.

After generating the CMK file, set the key file permissions to current user read-only:

chmod 0400 <path_to_key_file>

Creating an AWS IAM role

If you are not using AWS KMS, skip this section.

If you are using AWS KMS, Looker recommends that you create a new IAM role that is unique for your CMK and attach it with your Looker instance.

Below is an example IAM role that contains the minimum permissions required for your CMK:

    "Version": "2012-10-17",
    "Statement": [
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "kms:GenerateRandom",
            "Resource": "*"
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
            "Resource": "arn:aws:kms:*:*:key/*"

Setting environment variables

If you are using AWS KMS, set the AWS_REGION environment variable to your AWS region, and the LKR_AWS_CMK environment variable to the alias of your CMK:

export AWS_REGION=<AWS_region>
export LKR_AWS_CMK=alias/<CMK_alias>

Optionally, you can also set the LKR_AWS_CMK_EC environment variable to set a custom AWS encryption context. If you do not set this environment variable, Looker will use the default encryption context, the string Looker_Encryption_Context.

export LKR_AWS_CMK_EC=<My_Encryption_Context>

If you are not using AWS KMS, and you are storing your CMK in a file, set the LKR_MASTER_KEY_FILE environment variable to the path of the CMK file:

export LKR_MASTER_KEY_FILE=<path_to_key_file>

If you are not using AWS KMS, and you are storing your CMK in an environment variable, set the LKR_MASTER_KEY_ENV environment variable to the value of the CMK:

export LKR_MASTER_KEY_ENV=<CMK_value>

Encrypting the internal database

If you are migrating an existing Looker instance to GCM encryption, migrate Looker’s internal database and start Looker:

java -jar looker.jar migrate_encryption
./looker  start

If you are installing a new Looker instance, the first time you start Looker use the --force-gcm-encryption flag:

./looker start --force-gcm-encryption

The encryption process usually takes less than a minute. Once Looker has started, you can verify the new encryption by searching for GCM in the Looker log:

grep GCM log/looker.log

2018-10-29 22:42:20.279 +0000 [INFO|007d0|crypt] :: Starting migration from AES-128-CBC Legacy to AES-GCM-256
2018-10-29 22:42:20.468 +0000 [INFO|007d0|db:looker] :: (0.000152s) INSERT INTO "SETTING" ("KEY", "VALUE") VALUES


This section lists some common errors and resolutions to those errors: