User Guide Getting Started Help Center Documentation Community Training
Looker
  
English
Français
Deutsch
日本語
Changing Looker's Encryption Keys

As of Looker 6.4, Looker can use 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.

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

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 using the new GCM encryption or changing legacy encryption keys if 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 completing a rekey and starting up the instance, the client databases may experience higher than usual load.

To rekey AES-256 GCM encryption:

  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
    

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

  2. Set _SOURCE and _DESTINATION environment variables:

    When your Looker instance was initially migrated to or configured for AES-256 GCM encryption, one or more of the following environment variables was created:

    • LKR_MASTER_KEY_FILE: If you are not using AWS KMS, the path and file name of the file containing your CMK.
    • LKR_AWS_CMK: If you are using AWS KMS, the AWS CMK alias.
    • LKR_AWS_CMK_EC: If you are using AWS KMS, this is an optional variable that defines the encryption context used with AWS KMS keystores.

    The rekey operation uses additional environment variables identical to the ones above, with the suffix _SOURCE to indicate the existing configuration and with the suffix _DESTINATION to indicate the desired configuration after the rekey operation.

    Before rekeying your encryption, create environment variables identical to your existing ones with the _SOURCE suffix.

    If your existing configuration does not use AWS KMS:

    export LKR_MASTER_KEY_FILE_SOURCE=path_to_key_file
    

    If your existing configuration does use AWS KMS:

    export LKR_AWS_CMK_SOURCE=alias/CMK_alias
    export LKR_AWS_CMK_EC_SOURCE=My_Encryption_Context
    

    Then create environment variables with the _DESTINATION suffix that are appropriate for your new configuration.

    If your new configuration will not use AWS KMS:

    export LKR_MASTER_KEY_FILE_DESTINATION=path_to_new_key_file
    

    If your new configuration will use AWS KMS:

    export LKR_AWS_CMK_DESTINATION=alias/new_CMK_alias
    export LKR_AWS_CMK_EC_DESTINATION=My_New_Encryption_Context
    
  3. Run the rekey command:

    ./looker rekey
    
  4. Configure new environment variables:

    Set one or more of the following environment variables as appropriate for your new configuration.

    If your new configuration does not use AWS KMS:

    export LKR_MASTER_KEY_FILE=path_to_new_key_file
    

    If your new configuration does use AWS KMS:

    export LKR_AWS_CMK=alias/new_CMK_alias
    export LKR_AWS_CMK_EC=My_New_Encryption_Context
    

    If you moved from a locally-stored key to AWS or from AWS 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:

    unset LKR_MASTER_KEY_FILE
    

    If you moved from a AWS to a locally-stored key:

    unset LKR_AWS_CMK
    unset LKR_AWS_CMK_EC
    
  5. Start Looker:

    ./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 of 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

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

    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 my_key_file

  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

Top