User Guide Getting Started Help Center Documentation Community Training
Looker
  
English
Français
Deutsch
日本語
Migrating to AES-256 GCM Encryption

Looker can use 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.

For Looker-hosted instances, the CMK is generated using the Amazon Web Service (AWS) Key Management System (KMS). All existing Looker-hosted instances are migrated to GCM encryption by Looker and all encryption keys are managed by Looker.

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 API.

If you are not using AWS KMS:

Generate a file containing a base64, 32-byte long CMK. If you are not using a KMS and don’t already have a CMK file, you can use the following command to create a new CMK file:

openssl rand -base64 32 > path_to_key_file

After you’ve created 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 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": [
                "kms:Decrypt",
                "kms:Encrypt",
                "kms:Generate*",
            ],
            "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, set the LKR_MASTER_KEY_FILE environment variable to the path of the CMK file:

export LKR_MASTER_KEY_FILE=path_to_key_file

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

Troubleshooting

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

Top