Data encryption

Storage level encryption

ClickHouse Cloud is configured with encryption at rest by default utilizing cloud provider-managed AES 256 keys. For more information review:

• AWS server-side encryption for S3
• GCP default encryption at rest
• Azure storage encryption for data at rest

Database level encryption

Enterprise plan feature

Enhanced Encryption is available in the Enterprise plan. To upgrade, visit the plans page in the cloud console.

Data at rest is encrypted by default using cloud provider-managed AES 256 keys. Customers may enable Transparent Data Encryption (TDE) to provide an additional layer of protection for service data or supply their own key to implement Customer Managed Encryption Keys (CMEK) for their service.

Enhanced encryption is currently available in AWS and GCP services. Azure is coming soon.

Transparent Data Encryption (TDE)

TDE must be enabled on service creation. Existing services can't be encrypted after creation. Once TDE is enabled, it can't be disabled. All data in the service will remain encrypted. If you want to disable TDE after it has been enabled, you must create a new service and migrate your data there.

1. Select Create new service
2. Name the service
3. Select AWS or GCP as the cloud provider and the desired region from the drop-down
4. Click the drop-down for Enterprise features and toggle Enable Transparent Data Encryption (TDE)
5. Click Create service

Customer Managed Encryption Keys (CMEK)

Note

Deleting a KMS key used to encrypt a ClickHouse Cloud service will cause your ClickHouse service to be stopped and its data will be unretrievable, along with existing backups. To prevent accidental data loss when rotating keys you may wish to maintain old KMS keys for a period of time prior to deletion.

Once a service is encrypted with TDE, customers may update the key to enable CMEK. The service will automatically restart after updating the TDE setting. During this process, the old KMS key decrypts the data encrypting key (DEK), and the new KMS key re-encrypts the DEK. This ensures that the service on restart will use the new KMS key for encryption operations moving forward. This process may take several minutes.

Enable CMEK with AWS KMS

1. In ClickHouse Cloud, select the encrypted service

2. Click on the Settings on the left

3. At the bottom of the screen, expand the Network security information

4. Copy the Encryption role ID (AWS) or Encryption Service Account (GCP) - you will need this in a future step

5. Create a KMS key for AWS

6. Click the key

7. Update the AWS key policy as follows:

   {
       "Sid": "Allow ClickHouse Access",
       "Effect": "Allow",
       "Principal": {
           "AWS": [ "Encryption role ID " ]
       },
       "Action": [
           "kms:Encrypt",
           "kms:Decrypt",
           "kms:ReEncrypt*",
           "kms:DescribeKey"
       ],
       "Resource": "*"
   }
   

8. Save the Key policy

9. Copy the Key ARN

10. Return to ClickHouse Cloud and paste the Key ARN in the Transparent Data Encryption section of the Service Settings

11. Save the change

Enable CMEK with GCP KMS

1. In ClickHouse Cloud, select the encrypted service
2. Click on the Settings on the left
3. At the bottom of the screen, expand the Network security information
4. Copy the Encryption Service Account (GCP) - you will need this in a future step
5. Create a KMS key for GCP
6. Click the key
7. Grant the following permissions to the GCP Encryption Service Account copied in step 4 above.
   • Cloud KMS CryptoKey Encrypter/Decrypter
   • Cloud KMS Viewer
8. Save the Key permission
9. Copy the Key Resource Path
10. Return to ClickHouse Cloud and paste the Key Resource Path in the Transparent Data Encryption section of the Service Settings
11. Save the change

Enable CMEK with Azure KMS

1. In ClickHouse Cloud, select the encrypted service
2. Click on Settings on the left
3. At the bottom of the screen, expand Network security information
4. Copy the Cross Tenant App Client ID - you will need this in the next step
5. Sign into your Azure subscription and use the following command via the Azure CLI to create a new service principal; replace {azure_cross_tenant_app_client_id} with the value you copied in the previous step
   az ad sp create --id {azure_cross_tenant_app_client_id}
6. Copy the Name of the new service principal created - you will need this in a future step
7. Create an Azure Key Vault
8. Create a Key Vault key in Azure
9. From the Key Vault key, select Access control (IAM) on the left
10. Select Role assignments from the top menu
11. Click Add then Add role assignment from the top menu
12. Select the Key Vault Crypto User role, then click Next
13. Leave the default selections on the Add role assignment screen and click +Select members
14. Paste the service principal name you copied in step 6 (it starts with CH-TDE), select the service principal and click Select
15. Click Next then Review + assign
16. Return to your Azure Key Vault and copy the following values:
    • From the Overview page, copy your Vault URI
    • From the Overview page, copy your Directory ID
    • From the Keys page, copy your key Name
17. Return to your service settings in ClickHouse Cloud and paste the values from step 16 in the following fields:
    • Key ID > paste your key Name
    • Key Vault URI > paste your Vault URI
    • Key Tenant ID > paste your Directory ID
18. Click Rotate KMS, wait a few minutes as this will result in a rolling restart and verify your service is running

Key rotation

Once you set up CMEK, rotate the key by following the procedures above for creating a new KMS key and granting permissions. Return to the service settings to paste the new ARN (AWS), Key Resource Path (GCP) or Key Name (Azure) and save the settings. The service will restart to apply the new key.

KMS key poller

When using CMEK, the validity of the provided KMS key is checked every 10 minutes. If access to the KMS key is invalid, the ClickHouse service will stop. To resume service, restore access to the KMS key by following the steps in this guide, and then restart the service.

Backup and restore

Backups are encrypted using the same key as the associated service. When you restore an encrypted backup, it creates an encrypted instance that uses the same KMS key as the original instance. If needed, you can rotate the KMS key after restoration; see Key Rotation for more details.

Performance

Database encryption leverages ClickHouse's built-in Virtual File System for Data Encryption feature to encrypt and protect your data. The algorithm in use for this feature is AES_256_CTR, which is expected to have a performance penalty of 5-15% depending on the workload: