版本：4.x

透明数据加密（TDE）

本文档介绍透明数据加密（Transparent Data Encryption，TDE）的配置方法与使用限制。

能力概览

TDE 用于保护 Doris 持久化数据的静态存储安全。TDE 由以下几层密钥协作完成：

Root Key：由 KMS 管理，或以 local root key 文件形式保存在 FE 本地，用于保护 Doris 内部主密钥。
Master Key：由 Doris 生成并保存在元数据中，用 Root Key 加密。
Data Key：用于具体数据加密，由主密钥派生或保护。

当前实现支持 aws_kms、aliyun_kms 和 local 作为根密钥提供方。本文的 KMS 示例使用 aws_kms。

使用边界

使用 TDE 时，请注意以下限制：

FE 级参数 doris_tde_algorithm 决定新建内部表默认采用的加密算法。
修改 doris_tde_algorithm 不会自动改写已有表的存量数据。
使用 KMS 作为根密钥提供方时，需要完整配置 KMS Key ID、Endpoint、Region 和 Provider。
使用 local 作为根密钥提供方时，必须通过 doris_tde_root_key_file 指定 FE 本地可读取的 root key 文件。
local root key 文件路径必须是绝对路径，路径中不能包含 ..，文件必须存在且可读。
local root key 文件内容必须是 Base64 编码；Base64 解码后的原始 key 长度必须为 16 字节或 32 字节。

前置条件

1. 准备 KMS Key

如果使用 AWS KMS，需要准备一个可用的 AWS KMS Key，并获取以下信息：

doris_tde_key_id
doris_tde_key_endpoint
doris_tde_key_region
doris_tde_key_provider=aws_kms

首次启用时，上述四项必须完整配置。只配置其中一部分会导致 FE 初始化根密钥失败。

2. 准备 AWS 访问凭证

使用 AWS KMS 时支持两种凭证来源：

通过环境变量 DORIS_TDE_AK / DORIS_TDE_SK 注入 Access Key 和 Secret Key。
通过 AWS Instance Profile 获取凭证。

相关凭证至少应具备以下 KMS 权限：

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

3. 准备 local root key 文件

如果使用 local root key，需要准备一个 Base64 编码的 key 文件。建议在安全环境中生成 32 字节原始 key，例如：

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

当前实现也接受 Base64 解码后长度为 16 字节的 key：

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

local root key 文件属于高敏感密钥材料，应通过操作系统文件权限进行访问控制。建议由运行 FE 进程的专用用户持有，并按最小权限原则设置权限，例如 600 或 400，确保除 FE 进程及授权运维人员外，其他用户不能读取或修改该文件。不要将该文件放在共享目录、提交到版本库或写入日志。

在多 FE 部署中，需要将相同内容的 key 文件放到每个 FE 都能读取的相同绝对路径。SQL 中传入的 local key 文件路径是 FE 侧路径，不是客户端机器上的路径。

FE 配置

使用 KMS

编辑 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

然后为 FE 进程注入 AWS 凭证，例如：

export DORIS_TDE_AK=your_access_key
export DORIS_TDE_SK=your_secret_key

使用 local root key

编辑 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

完成配置后重启 FE。

信息

doris_tde_algorithm 的默认值为 PLAINTEXT。如果希望新建表启用数据加密，需要显式设置为 AES256 或 SM4。

首次初始化成功后，Root Key 信息会写入 Doris 元数据。local 模式会持久化 root key 文件路径和 root key 的 SHA-256 校验值，校验值以 Base64 编码保存；不会持久化 root key 明文或 Base64 文本。后续 FE 重启时，local provider 会优先读取元数据中持久化的 root key 文件路径。如果只是修改 fe.conf 中的 doris_tde_root_key_file，不会自动把已有系统切换到新的 local root key 或新的文件路径。

参数说明

FE 参数

参数	默认值	说明
`doris_tde_key_provider`	空	根密钥提供方，支持 `aws_kms`、`aliyun_kms` 和 `local`。
`doris_tde_key_id`	空	KMS Key ID。local 模式不需要配置。
`doris_tde_key_endpoint`	空	KMS Endpoint。local 模式不需要配置。
`doris_tde_key_region`	空	KMS 所在区域。local 模式不需要配置。
`doris_tde_root_key_file`	空	local 模式下 root key 文件路径。路径必须为 FE 可读取的绝对路径，文件内容为 Base64 编码的 key。
`doris_tde_algorithm`	`PLAINTEXT`	新建内部表默认使用的 TDE 算法，可选 `AES256`、`SM4`、`PLAINTEXT`。
`doris_tde_rotate_master_key_interval_ms`	`2592000000`	自动轮转主密钥的时间间隔，默认 30 天。
`doris_tde_check_rotate_master_key_interval_ms`	`300000`	检查是否需要轮转主密钥的周期，默认 5 分钟。

生效方式

数据文件加密

doris_tde_algorithm 是 FE 级默认值。建表时会读取该值，并将对应算法写入表的加密元数据。

可选算法为：

AES256
SM4
PLAINTEXT

如果 FE 使用 PLAINTEXT，则新建表不会启用数据加密。

使用方式

通过 FE 配置项 doris_tde_algorithm 为新建内部表设置默认加密算法。

如果希望业务数据落盘即加密，应在建表前完成 FE TDE 参数配置。

查看密钥元数据

可以通过 information_schema.encryption_keys 查看 Doris 当前管理的主密钥元数据：

SELECT * FROM information_schema.encryption_keys;

该表包含主密钥的 ID、版本、父密钥信息、算法、密文、IV、校验值以及创建和修改时间，适合用于检查主密钥是否已初始化与轮转。

如果该查询没有返回预期结果，优先检查：

KMS 模式下，doris_tde_key_provider、doris_tde_key_id、doris_tde_key_endpoint、doris_tde_key_region 是否完整配置。
KMS 模式下，FE 进程是否已正确注入 DORIS_TDE_AK / DORIS_TDE_SK，或是否能从 Instance Profile 取到凭证。
local 模式下，doris_tde_root_key_file 是否为绝对路径，文件是否存在且 FE 进程可读。
local 模式下，key 文件内容是否为合法 Base64，解码后长度是否为 16 字节或 32 字节。
FE 启动日志中是否出现 KMS 初始化、local root key 读取或 root key 校验相关报错。

轮转机制

自动轮转主密钥

FE 会按照 doris_tde_check_rotate_master_key_interval_ms 周期检查是否达到轮转阈值；如果达到 doris_tde_rotate_master_key_interval_ms，则自动生成新的主密钥版本，并同时维护 AES256 和 SM4 两类主密钥版本。

手动轮转根密钥

管理员可以执行 ADMIN ROTATE TDE ROOT KEY 轮转 Root Key。该命令要求当前用户具备全局 ADMIN 权限。执行后，Doris 会使用新的 Root Key 重新保护已有主密钥。

常用属性如下：

属性	说明
`doris_tde_key_provider`	新 Root Key 的 provider。
`doris_tde_key_id`	新 KMS Key ID。新 provider 为 KMS 时使用。
`doris_tde_key_endpoint`	新 KMS Endpoint。新 provider 为 KMS 时使用。
`doris_tde_key_region`	新 KMS Region。新 provider 为 KMS 时使用。
`doris_tde_key_new_key_file`	新 local root key 文件路径。新 provider 为 `local` 时必填。
`doris_tde_key_original_key_file`	当前 local root key 文件路径。当前 provider 为 `local` 时必填，用于校验当前 local root key。

KMS 轮转到 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"
);

KMS 轮转到 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"
);

local 轮转到 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"
);

local 轮转到 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"
);

当轮转涉及 local root key 时，需要注意：

SQL 中的 key 文件路径是 FE 侧路径，必须是绝对路径，不能包含 ..，文件必须存在且可读。
当前 provider 为 local 时，必须提供 doris_tde_key_original_key_file。FE 会读取该文件，并使用已持久化的 root key hash 校验它是否为当前正在使用的 local root key。
新 provider 为 local 时，必须提供 doris_tde_key_new_key_file。FE 会读取该文件，将新 root key 的文件路径和 hash 写入元数据，并用新 root key 重新保护已有主密钥。
在多 FE 部署中，轮转前应将涉及的 local key 文件放到每个 FE 都能读取的相同绝对路径。否则 follower 回放 edit log 或后续 FE 重启时可能无法初始化 local root key provider。
不要直接覆盖当前正在使用的 local root key 文件来完成轮转。需要保留旧 key 文件，并通过 ADMIN ROTATE TDE ROOT KEY 同时提供旧 key 文件和新 key 文件。

运维建议

在生产环境中显式配置 doris_tde_algorithm，不要依赖默认值。
在启用 KMS 模式前先完成 KMS 权限校验与凭证注入。
在启用 local 模式前先确认所有 FE 上的 key 文件路径、内容、属主和权限一致，并符合最小权限原则。
妥善备份 local root key 文件。该文件丢失或内容被替换后，FE 可能无法通过 root key hash 校验或无法解密已有主密钥。
更换 local root key 或 local root key 文件路径时，使用 ADMIN ROTATE TDE ROOT KEY，不要只修改 fe.conf。

透明数据加密（TDE）

能力概览

使用边界

前置条件

1. 准备 KMS Key

2. 准备 AWS 访问凭证

3. 准备 local root key 文件

FE 配置

使用 KMS

使用 local root key

推荐使用流程

使用 KMS 启用 TDE

使用 local root key 启用 TDE

参数说明

FE 参数

生效方式

数据文件加密

使用方式

查看密钥元数据

轮转机制

自动轮转主密钥

手动轮转根密钥

运维建议

能力概览​

使用边界​

前置条件​

1. 准备 KMS Key​

2. 准备 AWS 访问凭证​

3. 准备 local root key 文件​

FE 配置​

使用 KMS​

使用 local root key​

推荐使用流程​

使用 KMS 启用 TDE​

使用 local root key 启用 TDE​

参数说明​

FE 参数​

生效方式​

数据文件加密​

使用方式​

查看密钥元数据​

轮转机制​

自动轮转主密钥​

手动轮转根密钥​

运维建议​

能力概览

使用边界

前置条件

1. 准备 KMS Key

2. 准备 AWS 访问凭证

3. 准备 local root key 文件

FE 配置

使用 KMS

使用 local root key

推荐使用流程

使用 KMS 启用 TDE

使用 local root key 启用 TDE

参数说明

FE 参数

生效方式

数据文件加密

使用方式

查看密钥元数据

轮转机制

自动轮转主密钥

手动轮转根密钥

运维建议