> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Data encryption

> Learn more about data encryption in ClickHouse Cloud

export const EnterprisePlanFeatureBadge = ({feature = 'This feature', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Enterprise plan feature
            </div>
            <div>
                <p>{feature} {linking_verb_are ? 'are' : 'is'} available in the Enterprise plan. {support ? `Contact support to enable this feature.` : 'To upgrade, visit the plans page in the cloud console.'}</p>
            </div>
        </div>;
};

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

<h2 id="storage-encryption">
  Storage level encryption
</h2>

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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html)
* [GCP default encryption at rest](https://cloud.google.com/docs/security/encryption/default-encryption)
* [Azure storage encryption for data at rest](https://learn.microsoft.com/en-us/azure/storage/common/storage-service-encryption)

<h2 id="database-encryption">
  Database level encryption
</h2>

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.

<h3 id="transparent-data-encryption-tde">
  Transparent Data Encryption (TDE)
</h3>

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

<h3 id="customer-managed-encryption-keys-cmek">
  Customer Managed Encryption Keys (CMEK)
</h3>

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

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.

<Accordion title="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](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)

  6. Click the key

  7. Update the AWS key policy as follows:

     ```json theme={null}
     {
         "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
</Accordion>

<Accordion title="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](https://cloud.google.com/kms/docs/create-key)
  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
</Accordion>

<Accordion title="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](https://learn.microsoft.com/en-us/azure/key-vault/general/quick-create-portal)
  8. [Create a Key Vault key in Azure](https://learn.microsoft.com/en-us/azure/key-vault/keys/quick-create-portal)
  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
</Accordion>

<h4 id="key-rotation">
  Key rotation
</h4>

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.

<h4 id="kms-key-poller">
  KMS key poller
</h4>

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.

<h3 id="backup-and-restore">
  Backup and restore
</h3>

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](#key-rotation) for more details.

<h2 id="performance">
  Performance
</h2>

Database encryption leverages ClickHouse's built-in [Virtual File System for Data Encryption feature](/concepts/features/configuration/server-config/storing-data#encrypted-virtual-file-system) 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:

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/Qke-GQkmVyWEhvPu/images/_snippets/cmek-performance.png?fit=max&auto=format&n=Qke-GQkmVyWEhvPu&q=85&s=9cc895525a034c65985f737efbc23c43" size="lg" alt="CMEK Performance Penalty" width="2048" height="684" data-path="images/_snippets/cmek-performance.png" />