pingcap · sre-bot · Jun 9, 2020 · Jun 5, 2020 · Jun 5, 2020 · Jun 5, 2020
diff --git a/TOC.md b/TOC.md
@@ -74,8 +74,9 @@
     - [Placement Rules](/configure-placement-rules.md)
   + Secure
     + Transport Layer Security (TLS)
-      - [Enable TLS For MySQL Clients](/encrypted-connections-with-tls-protocols.md)
+      - [Enable TLS for MySQL Clients and Servers](/enable-tls-between-clients-and-servers.md)
       - [Enable TLS Between TiDB Components](/enable-tls-between-components.md)
+    - [Encrypt Stored Data](/enable-encrypt-stored-data.md)
     - [Generate Self-signed Certificates](/generate-self-signed-certificates.md)
     - [Encryption-At-Rest](/encryption-at-rest.md)
   + Monitor

diff --git a/enable-encrypt-stored-data.md b/enable-encrypt-stored-data.md
@@ -0,0 +1,45 @@
+---
+title: Enable Stored Data Encryption
+summary: Introduce how to enable encryption for stored data.
+category: how-to
+---
+
+# Enable Stored Data Encryption
+
+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.
+
+## Operation procedures
+
+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](/tidb-lightning/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.
diff --git a/encrypted-connections-with-tls-protocols.md → enable-tls-between-clients-and-servers.md b/encrypted-connections-with-tls-protocols.md → enable-tls-between-clients-and-servers.md
@@ -1,13 +1,13 @@
 ---
-title: Enable TLS for MySQL Clients
+title: Enable TLS Between TiDB Clients and Servers
 summary: Use the encrypted connection to ensure data security.
 category: how-to
-aliases: ['/docs/dev/how-to/secure/enable-tls-clients/']
+aliases: ['/docs/dev/how-to/secure/enable-tls-clients/','/docs/dev/encrypted-connections-with-tls-protocols/']
 ---
 
-# Enable TLS for MySQL Clients
+# Enable TLS Between TiDB Clients and Servers
 
-It is recommended to use the encrypted connection to ensure data security because non-encrypted connection might lead to an information leak.
+Non-encrypted connection between TiDB's server and client is used by default, which enables third parties that monitor channel traffic to know the data sent and received between the server and the client, including but not limited to query content, query results, and so on. If a channel is untrustworthy (such as if the client is connected to the TiDB server via a public network), then a non-encrypted connection is prone to information leakage. In this case, for security reasons, it is recommended to use an encrypted connection.
 
 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.
 
@@ -79,12 +79,6 @@ 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`.
 
-## 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`](/sql-statements/sql-statement-alter-instance.md) statement on the running TiDB instance to reload the certificate ([`ssl-cert`](/tidb-configuration-file.md#ssl-cert)), the key ([`ssl-key`](/tidb-configuration-file.md#ssl-key)), and the CA ([`ssl-ca`](/tidb-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
 
 The client of MySQL 5.7 or later versions attempts to establish an encrypted connection by default. If the server does not support encrypted connections, it automatically returns to unencrypted connections. The client of MySQL earlier than version 5.7 uses the unencrypted connection by default.
@@ -181,3 +175,13 @@ The TLS versions, key exchange protocols and encryption algorithms supported by
 - TLS\_AES\_128\_GCM\_SHA256
 - TLS\_AES\_256\_GCM\_SHA384
 - TLS\_CHACHA20\_POLY1305\_SHA256
+
+## 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`](/sql-statements/sql-statement-alter-instance.md) statement on the running TiDB instance to reload the certificate ([`ssl-cert`](/tidb-configuration-file.md#ssl-cert)), the key ([`ssl-key`](/tidb-configuration-file.md#ssl-key)), and the CA ([`ssl-ca`](/tidb-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.
+
+### See also
+
+- [Enable TLS Between TiDB Components](/enable-tls-between-components.md)。
diff --git a/enable-tls-between-components.md b/enable-tls-between-components.md
@@ -1,34 +1,30 @@
 ---
-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.
+title: Enable TLS Between TiDB Components
+summary: Learn how to enable TLS authentication between TiDB components.
 category: how-to
 aliases: ['/docs/dev/how-to/secure/enable-tls-between-components/']
 ---
 
-# Enable TLS Authentication and Encrypt the Stored Data
+# Enable TLS Between TiDB Components
 
-This document introduces how to enable TLS authentication and encrypt the stored data in a TiDB cluster.
+This document describes how to enable encrypted data transmission between components within a TiDB cluster. Once enabled, encrypted transmission is used between the following components:
 
-## Enable TLS Authentication
+- TiDB and TiKV; TiDB and PD
+- TiKV and PD
+- TiDB Control and TiDB; TiKV Control and TiKV; PD Control and PD
+- Internal communication within each TiKV, PD, TiDB cluster
 
-This section describes how to enable TLS authentication in a TiDB cluster. TLS authentication can be applied to the following scenarios:
+Currently, it is not supported to only enable encrypted transmission of some specific components.
 
-- 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
+## Configure and enable encrypted data transmission
 
 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.
+    It is recommended to prepare a server certificate for TiDB, TiKV, and PD separately. Make sure that these components can authenticate each other. The Control tools of TiDB, TiKV, and PD can choose to 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](/generate-self-signed-certificates.md).
+    If you choose `openssl`, you can refer to [generating self-signed certificates](/generate-self-signed-certificates.md).
 
 2. Configure certificates.
 
@@ -74,11 +70,11 @@ This section describes how to enable TLS authentication in a TiDB cluster. TLS a
         key-path = "/path/to/pd-server-key.pem"
         ```
 
-    After certificates are configured as above, mutual authentication among TiDB components is enabled.
+    Now, encrypted transmission 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:
+    > After enabling encrypted transmission in a TiDB cluster, if you need to connect to the cluster using tidb-ctl, tikv-ctl, or pd-ctl, specify the client certificate. For example:
 
     {{< copyable "shell-regular" >}}
 
@@ -98,84 +94,48 @@ This section describes how to enable TLS authentication in a TiDB cluster. TLS a
     ./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"
     ```
 
-3. Configure Common Name.
-
-    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.
-
-    - TiDB
-
-        Configure in the configuration file or command line arguments:
-
-        ```toml
-        [security]
-        cluster-verify-cn = [
-            "TiDB-Server",
-            "TiKV-Control",
-        ]
-        ```
-
-    - TiKV
+### Verify component caller's identity
 
-        Configure in the configuration file or command line arguments:
+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.
 
-        ```toml
-        [security]
-        cert-allowed-cn = [
-            "TiDB-Server", "PD-Server", "TiKV-Control", "RawKvClient1",
-        ]
-        ```
+To verify component caller's identity, you need 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.
 
-    - PD
+- TiDB
 
-        Configure in the configuration file or command line arguments:
+    Configure in the configuration file or command line arguments:
 
-        ```toml
-        [security]
-        cert-allowed-cn = ["TiKV-Server", "TiDB-Server", "PD-Control"]
-        ```
-
-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
-
-Refer to [Use Encrypted Connections](/encrypted-connections-with-tls-protocols.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.
+    ```toml
+    [security]
+    cluster-verify-cn = [
+        "TiDB-Server",
+        "TiKV-Control",
+    ]
+    ```
 
-    The token file stores the keys used to encrypt the user data and to decrypt the encrypted data.
+- TiKV
 
-    {{< copyable "shell-regular" >}}
+    Configure in the configuration file or command line arguments:
 
-    ```bash
-    ./tikv-ctl random-hex --len 256 > cipher-file-256
+    ```toml
+    [security]
+    cert-allowed-cn = [
+        "TiDB-Server", "PD-Server", "TiKV-Control", "RawKvClient1",
+    ]
     ```
 
-    > **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.
+- PD
 
-2. Configure TiKV as follows.
+    Configure in the configuration file or command line arguments:
 
     ```toml
     [security]
-    # Storage path of the Cipher file.
-    cipher-file = "/path/to/cipher-file-256"
+    cert-allowed-cn = ["TiKV-Server", "TiDB-Server", "PD-Control"]
     ```
 
-> **Note:**
->
-> When you import data into a cluster using [TiDB Lightning](/tidb-lightning/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.
+### Reload certificates
 
-### Limitations
+To reload the certificates and the keys, TiDB, PD, TiKV, and all kinds of clients reread the current certificates and the key files each time a new connection is created. Currently, you cannot reload the CA certificate.
 
-The limitations of the storage encryption feature are as follows:
+## See also
 
-- 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.
+- [Enable TLS Between TiDB Clients and Servers](/enable-tls-between-clients-and-servers.md)
diff --git a/sql-statements/sql-statement-alter-instance.md b/sql-statements/sql-statement-alter-instance.md
@@ -35,4 +35,4 @@ The `ALTER INSTANCE RELOAD TLS` statement only supports reloading from the origi
 
 ## See also
 
-[Enable Client TLS](/encrypted-connections-with-tls-protocols.md).
+[Enable TLS Between TiDB Clients and Servers](/enable-tls-between-clients-and-servers.md).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -35,4 +35,4 @@ The `ALTER INSTANCE RELOAD TLS` statement only supports reloading from the origi

		## See also

		[Enable Client TLS](/encrypted-connections-with-tls-protocols.md).
		[Enable TLS Between TiDB Clients and Servers](/enable-tls-between-clients-and-servers.md).