Skip to content

Update enable-tls-between-clients-and-servers.md #16100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update enable-tls-between-clients-and-servers.md #16100

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions enable-tls-between-clients-and-servers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,18 @@ TiDB 服务端支持启用基于 TLS（传输层安全）协议的加密连接

要为 TiDB 客户端与服务端间的通信开启 TLS 加密传输，首先需要在 TiDB 服务端通过配置开启 TLS 加密连接的支持，然后通过配置客户端应用程序使用 TLS 加密连接。一般情况下，如果服务端正确配置了 TLS 加密连接支持，客户端库都会自动启用 TLS 加密传输。

TiDB 客户端与服务端间的通信开启 TLS 加密可以分为两种：1、只开启SSL加密通信；2、强制校验客户端证书。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
TiDB 客户端与服务端间的通信开启 TLS 加密可以分为两种：1、只开启SSL加密通信；2、强制校验客户端证书。
TiDB 服务端配置开启与客户端之间通信的 TLS 加密传输，可以分为两种类型：1、只开启 TLS 加密传输；2、服务端强制校验客户端证书。
+ 只开启 TLS 加密传输：可以手动配置参数 `ssl-cert`、`ssl-key`，开启 TLS 加密传输；也可以配置参数 `auto-tls` 自动生成证书以开启 TLS 加密传输。配置参数 `ssl-ca` 可以增加对客户端证书进行校验，但是不是强制的，客户端可以不提供证书，如果提供证书则必须是合法的证书。
+ 服务端强制校验客户端证书：当服务端配置了参数 `ssl-cert`、`ssl-key` 和 `ssl-ca` 的基础上，打开了系统变量`require_secure_transport` 后，服务端将强制要求客户端提供证书并校验证书合法性。


另外，与 MySQL 相同，TiDB 也支持在同一 TCP 端口上开启 TLS 连接或非 TLS 连接。对于开启了 TLS 连接支持的 TiDB 服务端，客户端既可以选择通过加密连接安全地连接到该 TiDB 服务端，也可以选择使用普通的非加密连接。如需使用加密连接，你可以通过以下方式进行配置：

+ 通过配置系统变量 `require_secure_transport` 要求所有用户必须使用加密连接来连接到 TiDB。
+ 通过配置系统变量 `require_secure_transport` 要求所有用户必须使用加密连接来连接到 TiDB。开启后会校验客户端证书。此为上文说的强制校验客户端证书。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
+ 通过配置系统变量 `require_secure_transport` 要求所有用户必须使用加密连接来连接到 TiDB。开启后会校验客户端证书。此为上文说的强制校验客户端证书。
+ 通过配置系统变量 [`require_secure_transport`] (/system-variables.md#require_secure_transport-new-in-v610)要求所有用户必须基于某种形式的安全传输机制连接到 TiDB，此时服务端仅允许使用 TLS 的 TCP/IP 连接，或者使用 Unix 套接字的连接。

+ 开启方式，修改tidb.toml
```[security]
require-secure-transport = true
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

security.require-secure-transport已经失效了，取而代之的是系统变量require_secure_transport，此系统变量的开启需要用户基于安全连接到数据库后，使用SET命令进行开启。
另外：当前章节是概述部分，要补充配置示例，请在 <##配置 TiDB 服务端启用安全连接> 章节进行。

ssl-ca = "/path/root.crt"
ssl-cert = "/path/tidb.crt"
ssl-key = "/path/tidb.key"
```
+ 通过在创建用户 (`create user`)，或修改已有用户 (`alter user`) 时指定 `REQUIRE SSL` 要求指定用户必须使用加密连接来连接 TiDB。以创建用户为例：

```sql
Expand All @@ -40,7 +49,12 @@ TiDB 服务端支持启用基于 TLS（传输层安全）协议的加密连接
- [`ssl-ca`](/tidb-configuration-file.md#ssl-ca)：可选，指定受信任的 CA 证书文件路径
- [`tls-version`](/tidb-configuration-file.md#tls-version)：可选，指定最低 TLS 版本，例如 `TLSv1.2`

`auto-tls` 支持安全连接，但不提供客户端证书验证。有关证书验证和控制证书生成方式的说明，请参考下面配置 `ssl-cert`，`ssl-key` 和 `ssl-ca` 变量的建议：
`auto-tls` 支持安全连接，但不提供客户端证书验证。此为上文说的只开启SSL加密通信。
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`auto-tls` 支持安全连接，但不提供客户端证书验证。此为上文说的只开启SSL加密通信。
`auto-tls` 表示在服务端没有配置参数 `ssl-cert` 和 `ssl-key` 时，服务端会自动签发这两个证书，以支持TiDB的安全连接，但不提供 CA 证书进行客户端证书验证。有关证书验证和控制证书生成方式的说明，请参考下面配置 `ssl-cert`、`ssl-key` 和 `ssl-ca` 变量，以及系统变量 `require_secure_transport` 的建议：

+ 开启方式，修改tidb.toml
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

配置示例，请在本章节的最后添加。对比仅开启加密传输和强制要求校验客户端证书两种方式。添加的示例例如：

  • 只开启 TLS 加密传输，在 config 文件或命令行参数中设置： 
    ssl-ca = "/path/root.crt"
ssl-cert = "/path/tidb.crt"
ssl-key = "/path/tidb.key"
  • 服务端强制校验客户端证书，在配置了参数 ssl-cert，ssl-key 和 ssl-ca 的基础上，修改系统变量 require_secure_transport：
SET GLOBAL require_secure_transport = ON;

```[security]
auto-tls = true
```
有关证书验证和控制证书生成方式的说明，请参考下面配置 `ssl-cert`，`ssl-key` 和 `ssl-ca` 变量的建议：

- 在启动 TiDB 时，至少需要在配置文件中同时指定 `ssl-cert` 和 `ssl-key` 参数，才能在 TiDB 服务端开启安全连接。还可以指定 `ssl-ca` 参数进行客户端身份验证（请参见[配置启用身份验证](#配置启用身份验证)章节）。
- 参数指定的文件都为 PEM 格式。另外目前 TiDB 尚不支持加载有密码保护的私钥，因此必须提供一个没有密码的私钥文件。若提供的证书或私钥无效，则 TiDB 服务端将照常启动，但并不支持客户端加密连接到 TiDB 服务端。
Expand Down