Transparent Data Encryption (TDE)

This topic describes how to configure Transparent Data Encryption (TDE), including supported root key providers, configuration requirements, and operational limits.

Overview

TDE protects data at rest in Doris. It is structured around three layers of keys:

• Root Key: managed by KMS, or stored as a local root key file on FE, and used to protect Doris master keys
• Master Key: generated and stored by Doris, encrypted by the Root Key
• Data Key: used to protect actual data

The current implementation supports aws_kms, aliyun_kms, and local as root key providers. The KMS examples in this topic use aws_kms.

Operational boundaries

Use the following rules when operating TDE:

• use FE parameter doris_tde_algorithm to define the default algorithm for newly created internal tables;
• do not expect existing tables to be re-encrypted automatically after changing doris_tde_algorithm;
• when using a KMS root key provider, configure the KMS key ID, endpoint, region, and provider together;
• when using local as the root key provider, configure doris_tde_root_key_file with a root key file that FE can read locally;
• the local root key file path must be absolute, must not contain .., and must point to an existing readable file;
• the local root key file content must be Base64 encoded, and the decoded raw key must be either 16 bytes or 32 bytes.

Prerequisites

Prepare a KMS key

If you use AWS KMS, prepare an accessible AWS KMS key and the following values:

• doris_tde_key_id
• doris_tde_key_endpoint
• doris_tde_key_region
• doris_tde_key_provider=aws_kms

For first-time initialization, all four values must be configured together. A partial configuration is rejected by the FE initialization path.

Prepare AWS credentials

When AWS KMS is used, the current implementation supports two credential sources:

• environment variables DORIS_TDE_AK and DORIS_TDE_SK
• AWS Instance Profile credentials

The credentials should allow at least the following KMS operations:

• kms:Encrypt
• kms:Decrypt
• kms:GenerateDataKey
• kms:DescribeKey

Prepare a local root key file

If you use a local root key, prepare a Base64-encoded key file. A 32-byte raw key is recommended, for example:

openssl rand -base64 32 > /opt/apache-doris/fe/conf/doris_tde_root_key
chmod 600 /opt/apache-doris/fe/conf/doris_tde_root_key

The current implementation also accepts a key whose decoded length is 16 bytes:

openssl rand -base64 16 > /opt/apache-doris/fe/conf/doris_tde_root_key
chmod 600 /opt/apache-doris/fe/conf/doris_tde_root_key

The local root key file is highly sensitive key material and should be protected with operating-system-level access controls. It is recommended that the file be owned by the dedicated user running the FE process and restricted by the principle of least privilege, for example with permission 600 or 400, so that only FE and authorized operators can read or modify it. Do not place the file in shared directories, commit it to source control, or write it to logs.

In a multi-FE deployment, place the same key file content at the same absolute path on every FE. Local key file paths passed in SQL are FE-side paths, not paths on the SQL client host.

FE configuration

Use KMS

Edit conf/fe.conf:

doris_tde_key_provider = aws_kms
doris_tde_key_id = <your-kms-key-id>
doris_tde_key_endpoint = https://kms.us-east-1.amazonaws.com
doris_tde_key_region = us-east-1

doris_tde_algorithm = AES256
doris_tde_rotate_master_key_interval_ms = 2592000000
doris_tde_check_rotate_master_key_interval_ms = 300000

Then provide AWS credentials to the FE process, for example:

export DORIS_TDE_AK=your_access_key
export DORIS_TDE_SK=your_secret_key

Use a local root key

Edit conf/fe.conf:

doris_tde_key_provider = local
doris_tde_root_key_file = /opt/apache-doris/fe/conf/doris_tde_root_key

doris_tde_algorithm = AES256
doris_tde_rotate_master_key_interval_ms = 2592000000
doris_tde_check_rotate_master_key_interval_ms = 300000

Restart FE after the configuration is updated.

info

The default value of doris_tde_algorithm is PLAINTEXT. If you want new tables to be encrypted, set it explicitly to AES256 or SM4.

After the first successful initialization, the Root Key metadata is stored by Doris. In local mode, Doris persists the root key file path and a SHA-256 hash of the root key encoded with Base64. It does not persist the root key plaintext or the Base64 key text. On later FE restarts, the local provider first reads the persisted root key file path from metadata. Changing doris_tde_root_key_file in fe.conf alone does not switch an existing deployment to a different local root key or path.

Recommended rollout

Enable TDE with KMS

Use this order to enable TDE reliably:

1. prepare an AWS KMS key and verify that FE has working credentials for it;
2. inject DORIS_TDE_AK and DORIS_TDE_SK, or make a valid Instance Profile available to FE;
3. configure doris_tde_key_provider, doris_tde_key_id, doris_tde_key_endpoint, doris_tde_key_region, and doris_tde_algorithm in fe.conf;
4. restart FE;
5. run SELECT * FROM information_schema.encryption_keys; to confirm that master keys were initialized;
6. create the tables that should use encrypted storage only after the previous steps are complete.

Enable TDE with a local root key

Use this order to enable TDE reliably:

1. generate a Base64-encoded local root key file, and place the same file content at the same absolute path on every FE;
2. configure doris_tde_key_provider=local, doris_tde_root_key_file, and doris_tde_algorithm in fe.conf;
3. restart FE;
4. run SELECT * FROM information_schema.encryption_keys; to confirm that master keys were initialized;
5. back up the local root key file and protect the backup at the same level as the online file;
6. create the tables that should use encrypted storage only after the previous steps are complete.

Parameters

FE parameters

Parameter	Default	Description
doris_tde_key_provider	empty	Root key provider. Valid values are aws_kms, aliyun_kms, and local.
doris_tde_key_id	empty	KMS key ID. Not required in local mode.
doris_tde_key_endpoint	empty	KMS endpoint. Not required in local mode.
doris_tde_key_region	empty	KMS region. Not required in local mode.
doris_tde_root_key_file	empty	Root key file path for local mode. The path must be an absolute path readable by FE, and the file content must be a Base64-encoded key.
doris_tde_algorithm	PLAINTEXT	Default TDE algorithm for newly created internal tables. Valid values are AES256, SM4, and PLAINTEXT.
doris_tde_rotate_master_key_interval_ms	2592000000	Automatic master key rotation interval, 30 days by default.
doris_tde_check_rotate_master_key_interval_ms	300000	Interval for checking whether a rotation is needed, 5 minutes by default.

How encryption takes effect

Data files

doris_tde_algorithm is an FE-level default. Doris reads this value during table creation and writes the selected algorithm into the table encryption metadata.

Valid algorithms are:

• AES256
• SM4
• PLAINTEXT

If FE uses PLAINTEXT, newly created tables are not encrypted.

Usage model

Use the FE configuration parameter doris_tde_algorithm to define the default encryption algorithm for newly created internal tables.

If data must be encrypted at rest from the beginning, configure FE TDE before creating those tables.

Inspect key metadata

Use information_schema.encryption_keys to inspect the master key metadata managed by Doris:

SELECT * FROM information_schema.encryption_keys;

This schema table includes the key ID, version, parent key metadata, algorithm, ciphertext, IV, checksum, and creation or modification time.

If this query does not show the expected keys, check these items first:

• in KMS mode, doris_tde_key_provider, doris_tde_key_id, doris_tde_key_endpoint, and doris_tde_key_region are all configured together;
• in KMS mode, the FE process can read DORIS_TDE_AK and DORIS_TDE_SK, or can obtain credentials from the Instance Profile;
• in local mode, doris_tde_root_key_file is an absolute path, and the file exists and is readable by the FE process;
• in local mode, the key file content is valid Base64, and the decoded length is either 16 bytes or 32 bytes;
• the FE startup logs do not contain KMS initialization, local root key loading, or root key verification errors.

Rotation

Automatic master key rotation

FE checks every doris_tde_check_rotate_master_key_interval_ms whether the latest master key has reached the threshold defined by doris_tde_rotate_master_key_interval_ms. When it does, Doris generates a new master key version. The current implementation maintains both AES256 and SM4 master key versions.

Manual root key rotation

An administrator can rotate the Root Key with ADMIN ROTATE TDE ROOT KEY. This command requires global ADMIN privilege. Doris re-protects the existing master keys with the new Root Key information.

Common properties:

Property	Description
doris_tde_key_provider	Provider for the new Root Key.
doris_tde_key_id	New KMS key ID. Used when the new provider is KMS.
doris_tde_key_endpoint	New KMS endpoint. Used when the new provider is KMS.
doris_tde_key_region	New KMS region. Used when the new provider is KMS.
doris_tde_key_new_key_file	Path to the new local root key file. Required when the new provider is local.
doris_tde_key_original_key_file	Path to the current local root key file. Required when the current provider is local, and used to verify the current local root key.

Rotate from KMS to KMS:

ADMIN ROTATE TDE ROOT KEY PROPERTIES (
  "doris_tde_key_provider" = "aws_kms",
  "doris_tde_key_id" = "<new-kms-key-id>",
  "doris_tde_key_endpoint" = "https://kms.us-east-1.amazonaws.com",
  "doris_tde_key_region" = "us-east-1"
);

Rotate from KMS to local:

ADMIN ROTATE TDE ROOT KEY PROPERTIES (
  "doris_tde_key_provider" = "local",
  "doris_tde_key_new_key_file" = "/opt/apache-doris/fe/conf/new_local_root_key"
);

Rotate from local to local:

ADMIN ROTATE TDE ROOT KEY PROPERTIES (
  "doris_tde_key_provider" = "local",
  "doris_tde_key_original_key_file" = "/opt/apache-doris/fe/conf/current_local_root_key",
  "doris_tde_key_new_key_file" = "/opt/apache-doris/fe/conf/new_local_root_key"
);

Rotate from local to KMS:

ADMIN ROTATE TDE ROOT KEY PROPERTIES (
  "doris_tde_key_provider" = "aws_kms",
  "doris_tde_key_id" = "<new-kms-key-id>",
  "doris_tde_key_endpoint" = "https://kms.us-east-1.amazonaws.com",
  "doris_tde_key_region" = "us-east-1",
  "doris_tde_key_original_key_file" = "/opt/apache-doris/fe/conf/current_local_root_key"
);

When a rotation involves a local root key:

• key file paths in SQL are FE-side paths; each path must be absolute, must not contain .., and must point to an existing readable file;
• when the current provider is local, doris_tde_key_original_key_file is required. FE reads the file and verifies it against the persisted root key hash;
• when the new provider is local, doris_tde_key_new_key_file is required. FE reads the file, persists the new root key file path and hash, and re-protects existing master keys with the new root key;
• in a multi-FE deployment, put every involved local key file at the same absolute path on every FE before rotation. Otherwise, follower edit-log replay or a later FE restart may fail to initialize the local root key provider;
• do not rotate by overwriting the local root key file currently in use. Keep the old key file and pass both the old and new key files to ADMIN ROTATE TDE ROOT KEY.

Recommendations

• set doris_tde_algorithm explicitly in production instead of relying on the default;
• validate KMS access and credential injection before enabling KMS mode;
• before enabling local mode, verify that the key file path, content, owner, and permissions are consistent on all FEs and follow the principle of least privilege;
• back up the local root key file carefully. If this file is lost or replaced, FE may fail root key hash verification or fail to decrypt existing master keys;
• use ADMIN ROTATE TDE ROOT KEY to change a local root key or local root key file path. Do not only change fe.conf.