From bce3532dc0c8f3e951fe1733f5c323fa59c09e2a Mon Sep 17 00:00:00 2001 From: Yukang-Lian Date: Wed, 3 Jun 2026 19:52:55 +0800 Subject: [PATCH] [doc] Add TLS framework configuration reference Add current English and Chinese documentation for the TLS framework configuration contract. Clarify that the open-source build provides fixed configuration names and framework extension points, while complete runtime TLS behavior requires a custom TLS module implementation. Tests: - git diff --cached --check - corepack yarn docs:links:changed - corepack yarn docs:i18n-sync:changed - corepack yarn docs:features:changed - DOCS_VERSIONS=current SKIP_BLOG=true SKIP_COMMUNITY=true SKIP_RELEASES=true corepack yarn build --locale en - DOCS_VERSIONS=current SKIP_BLOG=true SKIP_COMMUNITY=true SKIP_RELEASES=true corepack yarn build --locale zh-CN --- docs/admin-manual/auth/tls-framework.md | 66 +++++++++++++++++++ .../admin-manual/auth/tls-framework.md | 66 +++++++++++++++++++ sidebars.ts | 6 +- 3 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 docs/admin-manual/auth/tls-framework.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/tls-framework.md diff --git a/docs/admin-manual/auth/tls-framework.md b/docs/admin-manual/auth/tls-framework.md new file mode 100644 index 0000000000000..b7791729588c2 --- /dev/null +++ b/docs/admin-manual/auth/tls-framework.md @@ -0,0 +1,66 @@ +--- +{ + "title": "TLS Framework Configuration", + "language": "en", + "description": "Reference for the Apache Doris TLS framework configuration contract, including fixed TLS configuration names, defaults, component scope, and extension guidance.", + "keywords": [ + "Doris TLS framework", + "enable_tls", + "tls_verify_mode", + "mTLS", + "TLS configuration" + ] +} +--- + + + + +This document describes the TLS framework configuration contract in Apache Doris. + +The open-source Doris package contains the framework, configuration items, parser support, and extension points for TLS and certificate-based authentication. It does not include a complete TLS runtime implementation for every protocol. In the stock open-source build, enabling TLS for a protocol that has no TLS module implementation will fail with an error indicating that the TLS module is required. + +The configuration names, default values, and meanings listed below are fixed by the framework. If you provide your own TLS module implementation, use this framework and these configuration items for compatibility. Implementation details such as certificate loading, TLS context creation, handshake behavior, certificate reload, and protocol-specific peer verification can be implemented by the TLS module. + +## Configuration Reference + +| Configuration | Components | Default | Description | Notes | +| --- | --- | --- | --- | --- | +| `enable_tls` | FE, BE, Cloud | `false` | Enables the unified TLS framework for the process. | When this is `true`, protocols not excluded by `tls_excluded_protocols` are expected to use the TLS implementation provided by the module. All related Doris components must use compatible TLS settings. | +| `tls_verify_mode` | FE, BE, Cloud | `verify_peer` | Controls certificate verification behavior. Supported values are `verify_none`, `verify_peer`, and `verify_fail_if_no_peer_cert`. | See [TLS verification modes](#tls-verification-modes). | +| `tls_certificate_path` | FE, BE, Cloud | Empty | Path to the certificate used by the component when acting as a TLS server or client. | The framework contract expects PEM certificates. A TLS module can support a leaf certificate or a full chain PEM file. | +| `tls_private_key_path` | FE, BE, Cloud | Empty | Path to the private key used with `tls_certificate_path`. | The framework contract expects a PEM private key. | +| `tls_private_key_password` | FE, BE, Cloud | Empty | Password for the private key file. | This is the plain password string, not a Base64-encoded value. | +| `tls_ca_certificate_path` | FE, BE, Cloud | Empty | Path to the CA certificate or CA bundle used for peer certificate verification. | The framework contract expects PEM CA certificates. A TLS module can also use system or JDK default trust stores when this value is empty and the scenario allows it. | +| `tls_cert_refresh_interval_seconds` | FE, BE, Cloud | `3600` | Interval, in seconds, for checking whether certificate files need to be reloaded. | The framework exposes the interval. Actual certificate reload behavior is implemented by the TLS module. | +| `tls_excluded_protocols` | FE, BE, Cloud | Empty | Comma-separated list of protocol names that should not use TLS. Matching is case-insensitive. | The applicable protocol names depend on the component and TLS module. The open-source framework reserves selectors such as `thrift`, `mysql`, `http`, `arrowflight`, `brpc`, and `bdbje`; use only selectors supported by your implementation. | +| `tls_peer_cert_required_san_dns` | FE, BE, Cloud | Empty | Peer certificate DNS Subject Alternative Name allowlist for selected private protocols. | Syntax: `=,;...`. The framework reserves this contract for module implementations that need peer certificate admission control. | +| `tls_cert_based_auth_ignore_password` | FE | `false` | Allows password verification to be skipped after certificate-based authentication succeeds. | This only affects FE user authentication flows. Enabling it weakens password-based protection and should be done only by deployments whose TLS module provides the required certificate authentication behavior. | + +## TLS Verification Modes + +| Mode | Client role | Server role | Usage | +| --- | --- | --- | --- | +| `verify_none` | Does not verify the server certificate. | Does not verify the client certificate. | For deployments that need TLS encryption without certificate validation. | +| `verify_peer` | Verifies the server certificate. | Does not require a client certificate. | For one-way TLS verification. This value does not require mTLS. | +| `verify_fail_if_no_peer_cert` | Verifies the server certificate. | Requires and verifies the client certificate. | For mTLS deployments that need mutual certificate verification. | + +## Framework Behavior in the Open-Source Build + +The open-source framework provides configuration definitions and extension points, and the default providers keep the existing plaintext behavior when `enable_tls` is `false`. + +When `enable_tls` is `true`, protocol startup or channel creation is routed through the TLS framework. If the corresponding TLS module is not provided, the open-source default implementation rejects TLS startup for that protocol and reports that the TLS module is required. + +This means the table above is a compatibility contract, not a complete operational guide for enabling TLS in the stock open-source package. + +## Implementation Guidance + +If you implement a custom TLS module, follow these rules: + +- Use the configuration names and semantics in this document. Do not introduce different configuration names for the same TLS behavior. +- Keep configuration behavior consistent across FE, BE, and Cloud components where the same item exists. +- Respect `tls_excluded_protocols` so users can choose which protocols are handled by the TLS module. +- Implement `tls_verify_mode` consistently for both server and client roles. +- If certificate reload is supported, use `tls_cert_refresh_interval_seconds` as the reload check interval. +- If peer certificate DNS SAN admission control is supported, use the `tls_peer_cert_required_san_dns` syntax described in the table. +- For certificate-based authentication, provide a runtime authentication implementation through the framework extension point. Without a custom implementation, the open-source default service is no-op. diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/tls-framework.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/tls-framework.md new file mode 100644 index 0000000000000..2949a324bb5e1 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/tls-framework.md @@ -0,0 +1,66 @@ +--- +{ + "title": "TLS 框架配置", + "language": "zh-CN", + "description": "Apache Doris TLS 框架配置契约说明，包括固定配置项、默认值、组件范围以及扩展实现要求。", + "keywords": [ + "Doris TLS 框架", + "enable_tls", + "tls_verify_mode", + "mTLS", + "TLS 配置" + ] +} +--- + + + + +本文档说明 Apache Doris TLS 框架的配置契约。 + +开源 Doris 包含 TLS 和证书鉴权相关的框架、配置项、解析支持和扩展点，但不包含覆盖所有协议的完整 TLS 运行时实现。在开源默认构建中，如果为未提供 TLS 模块实现的协议开启 TLS，启动或连接创建会失败，并提示需要 TLS module。 + +下表中的配置名称、默认值和语义由框架固定。如果你提供自己的 TLS module 实现，需要使用这套框架和这些配置项，以保证配置兼容。证书加载、TLS context 创建、握手行为、证书重载、协议级对端校验等细节可以由 TLS module 自行实现。 + +## 配置项参考 + +| 配置项 | 适用组件 | 默认值 | 说明 | 备注 | +| --- | --- | --- | --- | --- | +| `enable_tls` | FE、BE、Cloud | `false` | 是否为当前进程启用统一 TLS 框架。 | 设置为 `true` 后，未被 `tls_excluded_protocols` 排除的协议预期由 TLS module 提供 TLS 实现。相关 Doris 组件需要使用兼容的 TLS 配置。 | +| `tls_verify_mode` | FE、BE、Cloud | `verify_peer` | 控制证书校验行为。可选值为 `verify_none`、`verify_peer`、`verify_fail_if_no_peer_cert`。 | 参见 [TLS 校验模式](#tls-校验模式)。 | +| `tls_certificate_path` | FE、BE、Cloud | 空 | 当前组件作为 TLS 服务端或客户端时使用的证书路径。 | 框架契约预期使用 PEM 证书。TLS module 可以支持单张 leaf 证书或 full chain PEM 文件。 | +| `tls_private_key_path` | FE、BE、Cloud | 空 | 与 `tls_certificate_path` 配套使用的私钥路径。 | 框架契约预期使用 PEM 私钥。 | +| `tls_private_key_password` | FE、BE、Cloud | 空 | 私钥文件密码。 | 使用明文密码字符串，不是 Base64 编码值。 | +| `tls_ca_certificate_path` | FE、BE、Cloud | 空 | 用于校验对端证书的 CA 证书或 CA bundle 路径。 | 框架契约预期使用 PEM CA 证书。在该值为空且场景允许时，TLS module 也可以使用系统或 JDK 默认 trust store。 | +| `tls_cert_refresh_interval_seconds` | FE、BE、Cloud | `3600` | 检查证书文件是否需要重载的周期，单位为秒。 | 框架暴露该周期，具体证书重载行为由 TLS module 实现。 | +| `tls_excluded_protocols` | FE、BE、Cloud | 空 | 指定不使用 TLS 的协议列表，用英文逗号分隔，大小写不敏感。 | 可用协议名取决于组件和 TLS module。开源框架预留了 `thrift`、`mysql`、`http`、`arrowflight`、`brpc`、`bdbje` 等 selector；只应使用你的实现支持的 selector。 | +| `tls_peer_cert_required_san_dns` | FE、BE、Cloud | 空 | 为部分私有协议配置对端证书 DNS Subject Alternative Name 准入 allowlist。 | 语法为 `=,;...`。该配置是为需要对端证书准入控制的 TLS module 预留的框架契约。 | +| `tls_cert_based_auth_ignore_password` | FE | `false` | 证书鉴权成功后是否允许跳过密码校验。 | 该配置只影响 FE 用户认证流程。开启后会削弱密码保护，只应在 TLS module 已提供所需证书鉴权行为的部署中使用。 | + +## TLS 校验模式 + +| 模式 | 客户端角色 | 服务端角色 | 使用场景 | +| --- | --- | --- | --- | +| `verify_none` | 不校验服务端证书。 | 不校验客户端证书。 | 需要 TLS 加密但不做证书校验的部署。 | +| `verify_peer` | 校验服务端证书。 | 不要求客户端证书。 | 单向 TLS 校验。该值不表示要求 mTLS。 | +| `verify_fail_if_no_peer_cert` | 校验服务端证书。 | 要求并校验客户端证书。 | 需要双向证书校验的 mTLS 部署。 | + +## 开源默认构建中的框架行为 + +开源框架提供配置定义和扩展点。当 `enable_tls` 为 `false` 时，默认 provider 保持已有明文行为。 + +当 `enable_tls` 为 `true` 时，协议启动或 channel 创建会进入 TLS 框架。如果没有提供对应 TLS module，开源默认实现会拒绝该协议的 TLS 启动，并提示需要 TLS module。 + +因此，上面的配置表是兼容性契约，不是开源默认包中直接启用 TLS 的完整操作手册。 + +## 实现建议 + +如果你实现自定义 TLS module，请遵循以下规则： + +- 使用本文档中的配置名称和语义，不要为相同 TLS 行为引入不同配置名。 +- 对 FE、BE、Cloud 中共有的配置项保持一致语义。 +- 遵循 `tls_excluded_protocols`，让用户能够选择哪些协议交给 TLS module 处理。 +- 对服务端和客户端角色一致实现 `tls_verify_mode`。 +- 如果支持证书重载，使用 `tls_cert_refresh_interval_seconds` 作为检查周期。 +- 如果支持对端证书 DNS SAN 准入控制，使用表格中描述的 `tls_peer_cert_required_san_dns` 语法。 +- 如果支持证书鉴权，需要通过框架扩展点提供运行时鉴权实现。没有自定义实现时，开源默认服务是 no-op。 diff --git a/sidebars.ts b/sidebars.ts index 8edfc219570bc..b34716e25ef22 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -841,7 +841,11 @@ const sidebars: SidebarsConfig = { { type: 'category', label: 'Encryption in Transit', - items: ['admin-manual/auth/certificate', 'admin-manual/auth/fe-certificate'], + items: [ + 'admin-manual/auth/certificate', + 'admin-manual/auth/fe-certificate', + 'admin-manual/auth/tls-framework', + ], }, 'admin-manual/auth/encryption-function', ],