*: update the recent improvements about tls/security

TOC.md

@@ -171,6 +171,7 @@
       - [`ADD INDEX`](/reference/sql/statements/add-index.md)
       - [`ADMIN`](/reference/sql/statements/admin.md)
       - [`ALTER DATABASE`](/reference/sql/statements/alter-database.md)
+      - [`ALTER INSTANCE`](/reference/sql/statements/alter-instance.md)
       - [`ALTER TABLE`](/reference/sql/statements/alter-table.md)
       - [`ALTER USER`](/reference/sql/statements/alter-user.md)
       - [`ANALYZE TABLE`](/reference/sql/statements/analyze-table.md)

how-to/secure/enable-tls-between-components.md

@@ -1,86 +1,180 @@
 ---
-title: Enable TLS Authentication
-summary: Learn how to enable TLS authentication in a TiDB cluster.
+title: Enable TLS Authentication and Encrypt the Stored Data
+summary: Learn how to enable TLS authentication and encrypt the stored data in a TiDB cluster.
 category: how-to
 ---
 
-# Enable TLS Authentication
+# Enable TLS Authentication and Encrypt the Stored Data
 
-## Overview
+This document introduces how to enable TLS authentication and encrypt the stored data in a TiDB cluster.
 
-This document describes how to enable TLS authentication in the TiDB cluster. The TLS authentication includes the following two conditions:
+## Enable TLS Authentication
 
-- The mutual authentication between TiDB components, including the authentication among TiDB, TiKV and PD, between TiKV Control and TiKV, between PD Control and PD, between TiKV peers, and between PD peers. Once enabled, the mutual authentication applies to all components, and it does not support applying to only part of the components.
-- The one-way and mutual authentication between the TiDB server and the MySQL Client.
+This section describes how to enable TLS authentication in a TiDB cluster. TLS authentication can be applied to the following scenarios:
+
+- The **mutual authentication** between TiDB components, including the authentication among TiDB, TiKV, and PD; the authentication between TiDB Control and TiDB, between TiKV Control and TiKV, between PD Control and PD; the authentication between TiKV peers, and between PD peers. Once enabled, the mutual authentication applies to all components, rather than to part of the components.
+- The **one-way** and **mutual authentication** between the TiDB server and the MySQL Client.
 
 > **Note:**
 >
 > The authentication between the MySQL Client and the TiDB server uses one set of certificates, while the authentication among TiDB components uses another set of certificates.
 
 ## Enable mutual TLS authentication among TiDB components
 
-### Prepare certificates
+1. Prepare certificates.
+
+    It is recommended to prepare a server certificate for TiDB, TiKV, and PD separately. Make sure that these components can authenticate each other. The clients of TiDB, TiKV, and PD share one client certificate.
+
+    You can use tools like `openssl`, `easy-rsa` and `cfssl` to generate self-signed certificates.
+
+    If you choose `cfssl`, you can refer to [generating self-signed certificates](/how-to/secure/generate-self-signed-certificates.md).
+
+2. Configure certificates.
+
+   To enable mutual authentication among TiDB components, configure the certificates of TiDB, TiKV, and PD as follows.
+
+   - TiDB
+
+        Configure in the configuration file or command line arguments:
+
+        ```toml
+        [security]
+        # Path of file that contains list of trusted SSL CAs for connection with cluster components.
+        cluster-ssl-ca = "/path/to/ca.pem"
+        # Path of file that contains X509 certificate in PEM format for connection with cluster components.
+        cluster-ssl-cert = "/path/to/tidb-server.pem"
+        # Path of file that contains X509 key in PEM format for connection with cluster components.
+        cluster-ssl-key = "/path/to/tidb-server-key.pem"
+        ```
+
+   - TiKV
+
+        Configure in the configuration file or command line arguments, and set the corresponding URL to https:
+
+        ```toml
+        [security]
+        # set the path for certificates. Empty string means disabling secure connections.
+        ca-path = "/path/to/ca.pem"
+        cert-path = "/path/to/tikv-server.pem"
+        key-path = "/path/to/tikv-server-key.pem"
+        ```
+
+   - PD
+
+        Configure in the configuration file or command line arguments, and set the corresponding URL to https:
+
+        ```toml
+        [security]
+        # Path of file that contains list of trusted SSL CAs. If set, following four settings shouldn't be empty
+        cacert-path = "/path/to/ca.pem"
+        # Path of file that contains X509 certificate in PEM format.
+        cert-path = "/path/to/pd-server.pem"
+        # Path of file that contains X509 key in PEM format.
+        key-path = "/path/to/pd-server-key.pem"
+        ```
+
+    After certificates are configured as above, mutual authentication among TiDB components is enabled.
+
+    > **Note:**
+    >
+    > If you have enabled TLS in a TiDB cluster when you connect to the cluster using tidb-ctl, tikv-ctl, or pd-ctl, you need to specify the client certificate. For example:
 
-It is recommended to prepare a separate server certificate for TiDB, TiKV and PD, and make sure that they can authenticate each other. The clients of TiDB, TiKV and PD share one client certificate.
+    {{< copyable "shell-regular" >}}
 
-You can use multiple tools to generate self-signed certificates, such as `openssl`, `easy-rsa` and `cfssl`.
+    ```bash
+    ./tidb-ctl -u https://127.0.0.1:10080 --ca /path/to/ca.pem --ssl-cert /path/to/client.pem --ssl-key /path/to/client-key.pem
+    ```
 
-See an example of [generating self-signed certificates](/how-to/secure/generate-self-signed-certificates.md) using `cfssl`.
+    {{< copyable "shell-regular" >}}
 
-### Configure certificates
+    ```bash
+    ./pd-ctl -u https://127.0.0.1:2379 --cacert /path/to/ca.pem --cert /path/to/client.pem --key /path/to/client-key.pem
+    ```
 
-To enable mutual authentication among TiDB components, configure the certificates of TiDB, TiKV and PD as follows.
+    {{< copyable "shell-regular" >}}
 
-#### TiDB
+    ```bash
+    ./tikv-ctl --host="127.0.0.1:20160" --ca-path="/path/to/ca.pem" --cert-path="/path/to/client.pem" --key-path="/path/to/clinet-key.pem"
+    ```
 
-Configure in the configuration file or command line arguments:
+3. Configure Common Name.
 
-```toml
-[security]
-# Path of file that contains list of trusted SSL CAs for connection with cluster components.
-cluster-ssl-ca = "/path/to/ca.pem"
-# Path of file that contains X509 certificate in PEM format for connection with cluster components.
-cluster-ssl-cert = "/path/to/tidb-server.pem"
-# Path of file that contains X509 key in PEM format for connection with cluster components.
-cluster-ssl-key = "/path/to/tidb-server-key.pem"
-```
+    The Common Name is used for caller verification. In general, the callee needs to verify the caller's identity, in addition to verifying the key, the certificates, and the CA provided by the caller. For example, TiKV can only be accessed by TiDB, and other visitors are blocked even though they have legitimate certificates. It is recommended to mark the certificate user identity using `Common Name` when generating the certificate, and to check the caller's identity by configuring the `Common Name` list for the callee.
 
-#### TiKV
+    - TiDB
 
-Configure in the configuration file or command line arguments, and set the corresponding URL to https:
+        Configure in the configuration file or command line arguments:
 
-```toml
-[security]
-# set the path for certificates. Empty string means disabling secure connections.
-ca-path = "/path/to/ca.pem"
-cert-path = "/path/to/tikv-server.pem"
-key-path = "/path/to/tikv-server-key.pem"
-```
+        ```toml
+        [security]
+        cluster-verify-cn = [
+            "TiDB-Server",
+            "TiKV-Control",
+        ]
+        ```
 
-#### PD
+    - TiKV
 
-Configure in the configuration file or command line arguments, and set the corresponding URL to https:
+        Configure in the configuration file or command line arguments:
 
-```toml
-[security]
-# Path of file that contains list of trusted SSL CAs. If set, following four settings shouldn't be empty
-cacert-path = "/path/to/ca.pem"
-# Path of file that contains X509 certificate in PEM format.
-cert-path = "/path/to/pd-server.pem"
-# Path of file that contains X509 key in PEM format.
-key-path = "/path/to/pd-server-key.pem"
-```
+        ```toml
+        [security]
+        cert-allowed-cn = [
+            "TiDB-Server", "PD-Server", "TiKV-Control", "RawKvClient1",
+        ]
+        ```
 
-Now mutual authentication among TiDB components is enabled.
+    - PD
 
-When you connect the server using the client, it is required to specify the client certificate. For example:
+        Configure in the configuration file or command line arguments:
 
-```bash
-./pd-ctl -u https://127.0.0.1:2379 --cacert /path/to/ca.pem --cert /path/to/client.pem --key /path/to/client-key.pem
+        ```toml
+        [security]
+        cert-allowed-cn = ["TiKV-Server", "TiDB-Server", "PD-Control"]
+        ```
 
-./tikv-ctl --host="127.0.0.1:20160" --ca-path="/path/to/ca.pem" --cert-path="/path/to/client.pem" --key-path="/path/to/clinet-key.pem"
-```
+4. Reload certificates.
+
+    To reload the certificates and the keys, TiDB, PD, and TiKV reread the current certificates and the key files each time a new connection is created. Currently, you cannot reload the CA certificate. 
 
 ## Enable TLS authentication between the MySQL client and TiDB server
 
-See [Use Encrypted Connections](/how-to/secure/enable-tls-clients.md).
+Refer to [Use Encrypted Connections](/how-to/secure/enable-tls-clients.md).
+
+## Encrypt stored data
+
+In a TiDB cluster, user data is stored in TiKV. Once you configure the encrypted storage feature in TiKV, the TiDB cluster encrypts this data. This section introduces how to configure the data encryption feature in TiKV.
+
+1. Generate the token file.
+
+    The token file stores the keys used to encrypt the user data and to decrypt the encrypted data.
+
+    {{< copyable "shell-regular" >}}
+
+    ```bash
+    ./tikv-ctl random-hex --len 256 > cipher-file-256
+    ```
+
+    > **Note:**
+    >
+    > You can only use the hex-formatted token file. The file length must be 2 to the power of N, and is less than or equal to 1024.
+
+2. Configure TiKV as follows.
+
+    ```toml
+    [security]
+    # Storage path of the Cipher file.
+    cipher-file = "/path/to/cipher-file-256"
+    ```
+
+> **Note:**
+>
+> When you import data into a cluster using [TiDB Lightning](/reference/tools/tidb-lightning/overview.md), if the storage encryption feature is enabled in the target cluster, the SST files generated by TiDB Lightning must be encrypted.
+
+### Limitations
+
+The limitations of the storage encryption feature are as follows:
+
+- If the feature has not been enabled in the cluster before, you cannot enable this feature.
+- If the feature is enabled in the cluster, you cannot disable this feature.
+- You cannot enable the feature for some TiKV instances while disabling it for other instances in one cluster. You can only enable or disable this feature for all TiKV instances. This is because if you enable the encrypted storage feature, data are encrypted during data migration.

how-to/secure/enable-tls-clients.md

@@ -6,22 +6,35 @@ category: how-to
 
 # Enable TLS for MySQL Clients
 
-It is recommended to use the encrypted connection to ensure data security because non-encrypted connection might lead to information leak.
+It is recommended to use the encrypted connection to ensure data security because non-encrypted connection might lead to an information leak.
 
-The TiDB server supports the encrypted connection based on the TLS (Transport Layer Security). The protocol is consistent with MySQL encrypted connections and is directly supported by existing MySQL clients such as MySQL operation tools and MySQL drivers. TLS is sometimes referred to as SSL (Secure Sockets Layer). Because the SSL protocol has [known security vulnerabilities](https://en.wikipedia.org/wiki/Transport_Layer_Security), TiDB does not support it. TiDB supports the following versions: TLS 1.0, TLS 1.1, and TLS 1.2.
+The TiDB server supports the encrypted connection based on the TLS (Transport Layer Security). The protocol is consistent with MySQL encrypted connections and is directly supported by existing MySQL clients such as MySQL operation tools and MySQL drivers. TLS is sometimes referred to as SSL (Secure Sockets Layer). Because the SSL protocol has [known security vulnerabilities](https://en.wikipedia.org/wiki/Transport_Layer_Security), TiDB does not support it. TiDB supports the following versions: TLS 1.0, TLS 1.1, and TLS 1.2, TLS 1.3.
 
 After using an encrypted connection, the connection has the following security properties:
 
 - Confidentiality: the traffic plaintext cannot be eavesdropped
 - Integrity: the traffic plaintext cannot be tampered
 - Authentication: (optional) the client and the server can verify the identity of both parties to avoid man-in-the-middle attacks
 
-The encrypted connections in TiDB are disabled by default. To use encrypted connections in the client, you must first configure the TiDB server and enable encrypted connections. In addition, similar to MySQL, the encrypted connections in TiDB consist of single optional connection. For a TiDB server with encrypted connections enabled, you can choose to securely connect to the TiDB server through an encrypted connection, or to use a generally unencrypted connection. Most MySQL clients do not use encrypted connections by default, so generally the client is explicitly required to use an encrypted connection.
+The encrypted connections in TiDB are disabled by default. To use encrypted connections in the client, you must first configure the TiDB server and enable encrypted connections. In short, to use encrypted connections, both of the following conditions must be met:
 
-In short, to use encrypted connections, both of the following conditions must be met:
++ Enable encrypted connections in the TiDB server.
++ The client specifies to use an encrypted connection.
 
-1. Enable encrypted connections in the TiDB server.
-2. The client specifies to use an encrypted connection.
+Similar to MySQL, the encrypted connections in TiDB consist of single connections. The encrypted connection is optional by default. For a TiDB server with encrypted connections enabled, you can choose to securely connect to the TiDB server through an encrypted connection, or to use a generally unencrypted connection. If the encrypted connections are enforced as required, both of the following two ways are available:
+
++ Configure the launch parameter `--require-secure-transport` to enable encrypted connections to the TiDB server for all users.
++ Specify `require ssl` when you create a user (`create user`), grant permissions (`grant`) or modify an existing user (`alter user`), which is to specify that specified users must use the encrypted connection to access TiDB. The following is an example of creating a user:
+
+    {{< copyable "sql" >}}
+
+    ```sql
+    create user 'u1'@'%'  require ssl;
+    ```
+
+> **Note:**
+>
+> If the login user has configured using the [TiDB Certificate-Based Authentication for Login] (/reference/security/cert-based-authentication.md#configure-the-user-certificate-information-for-login-verification), the user is implicitly required to enable the encrypted connection to TiDB.
 
 ## Configure TiDB to use encrypted connections
 
@@ -63,7 +76,13 @@ ssl-cert = "certs/server-cert.pem"
 ssl-key = "certs/server-key.pem"
 ```
 
-If the certificate parameters are correct, TiDB outputs `secure connection is enabled` when started, otherwise it outputs `secure connection is NOT ENABLED`.
+If the certificate parameters are correct, TiDB outputs `secure connection is enabled` when started; otherwise, it outputs `secure connection is NOT ENABLED`.
+
+## Reload certificate, key, and CA
+
+To replace the certificate, the key or CA, first replace the corresponding files, then execute the [`ALTER INSTANCE RELOAD TLS`](/reference/sql/statements/alter-instance.md) statement on the running TiDB instance to reload the certificate ([`ssl-cert`](/reference/configuration/tidb-server/configuration-file.md#ssl-cert)), the key ([`ssl-key`](/reference/configuration/tidb-server/configuration-file.md#ssl-key)), and the CA ([`ssl-ca`](/reference/configuration/tidb-server/configuration-file.md#ssl-ca)) from the original configuration path. In this way, you do not need to restart the TiDB instance.
+
+The newly loaded certificate, key, and CA take effect on the connection that is established after the statement is successfully executed. The connection established before the statement execution is not affected.
 
 ## Configure the MySQL client to use encrypted connections
 
@@ -85,7 +104,7 @@ If the `ssl-ca` parameter is not specified in the TiDB server or MySQL client, t
   1. Specify the `ssl-cert` and `ssl-key` parameters in the TiDB server.
   2. Specify the `--ssl-ca` parameter in the MySQL client.
   3. Specify the `--ssl-mode` to `VERIFY_CA` at least in the MySQL client.
-  4. Make sure that the certificate (`ssl-cert`) configured by the TiDB server is signed by the CA specified by the client `--ssl-ca` parameter, otherwise the authentication fails.
+  4. Make sure that the certificate (`ssl-cert`) configured in the TiDB server is signed by the CA specified by the client `--ssl-ca` parameter; otherwise, the authentication fails.
 
 + To authenticate the MySQL client from the TiDB server:
   1. Specify the `ssl-cert`, `ssl-key`, and `ssl-ca` parameters in the TiDB server.
@@ -94,9 +113,17 @@ If the `ssl-ca` parameter is not specified in the TiDB server or MySQL client, t
 
 - To perform mutual authentication, meet both of the above requirements.
 
+By default, the server-to-client authentication is optional. Even if the client does not present its certificate of identification during the TLS handshake, the TLS connection can be still established. You can also require the client to be authenticated by specifying `require 509` when creating a user (`create user`), granting permissions (`grant`), or modifying an existing user (`alter user`). The following is an example of creating a user:
+
+{{< copyable "sql" >}}
+
+```sql
+create user 'u1'@'%'  require x509;
+```
+
 > **Note:**
 >
-> Currently, it is optional that TiDB server authenticates the client. If the client does not present its identity certificate in the TLS handshake, the TLS connection can also be successfully established.
+> If the login user has configured using the [TiDB Certificate-Based Authentication for Login] (/reference/security/cert-based-authentication.md#configure-the-user-certificate-information-for-login-verification), the user is implicitly required to enable the encrypted connection to TiDB.
 
 ## Check whether the current connection uses encryption
 
@@ -131,21 +158,17 @@ The TLS versions, key exchange protocols and encryption algorithms supported by
 - TLS 1.0
 - TLS 1.1
 - TLS 1.2
+- TLS 1.3
 
 ### Supported key exchange protocols and encryption algorithms
 
-- TLS\_RSA\_WITH\_RC4\_128\_SHA
-- TLS\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA
 - TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA
 - TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA
 - TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256
 - TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256
 - TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384
-- TLS\_ECDHE\_ECDSA\_WITH\_RC4\_128\_SHA
 - TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA
 - TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA
-- TLS\_ECDHE\_RSA\_WITH\_RC4\_128\_SHA
-- TLS\_ECDHE\_RSA\_WITH\_3DES\_EDE\_CBC\_SHA
 - TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA
 - TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA
 - TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA256
@@ -154,5 +177,6 @@ The TLS versions, key exchange protocols and encryption algorithms supported by
 - TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256
 - TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384
 - TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384
-- TLS\_ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305
-- TLS\_ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305
+- TLS\_AES\_128\_GCM\_SHA256
+- TLS\_AES\_256\_GCM\_SHA384
+- TLS\_CHACHA20\_POLY1305\_SHA256