From 92cc9cc96f4305538277e6d5660ef18992402114 Mon Sep 17 00:00:00 2001 From: Aolin Date: Thu, 26 Oct 2023 19:24:33 +0800 Subject: [PATCH 1/4] This is an automated cherry-pick of #15192 Signed-off-by: ti-chi-bot --- best-practices/java-app-best-practices.md | 4 +- develop/dev-guide-choose-driver-or-orm.md | 2 +- develop/dev-guide-connect-to-tidb.md | 4 +- develop/dev-guide-connection-parameters.md | 4 +- ...v-guide-third-party-tools-compatibility.md | 2 +- system-variables.md | 2 +- ...cure-connections-to-serverless-clusters.md | 205 ++++++++++++ .../tidb-cloud-tls-connect-to-dedicated.md | 301 ++++++++++++++++++ tispark-overview.md | 2 +- 9 files changed, 516 insertions(+), 10 deletions(-) create mode 100644 tidb-cloud/secure-connections-to-serverless-clusters.md create mode 100644 tidb-cloud/tidb-cloud-tls-connect-to-dedicated.md diff --git a/best-practices/java-app-best-practices.md b/best-practices/java-app-best-practices.md index ec11af45bc497..fcb5498093a49 100644 --- a/best-practices/java-app-best-practices.md +++ b/best-practices/java-app-best-practices.md @@ -63,7 +63,7 @@ In most scenarios, to improve execution efficiency, JDBC obtains query results i Usually, there are two kinds of processing methods in JDBC: -- [Set `FetchSize` to `Integer.MIN_VALUE`](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-implementation-notes.html#ResultSet) to ensure that the client does not cache. The client will read the execution result from the network connection through `StreamingResult`. +- [Set `FetchSize` to `Integer.MIN_VALUE`](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-implementation-notes.html#ResultSet) to ensure that the client does not cache. The client will read the execution result from the network connection through `StreamingResult`. When the client uses the streaming read method, it needs to finish reading or close `resultset` before continuing to use the statement to make a query. Otherwise, the error `No statements may be issued when any streaming result sets are open and in use on a given connection. Ensure that you have called .close() on any active streaming result sets before attempting more queries.` is returned. @@ -75,7 +75,7 @@ TiDB supports both methods, but it is preferred that you use the first method, b ### MySQL JDBC parameters -JDBC usually provides implementation-related configurations in the form of JDBC URL parameters. This section introduces [MySQL Connector/J's parameter configurations](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-configuration-properties.html) (If you use MariaDB, see [MariaDB's parameter configurations](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)). Because this document cannot cover all configuration items, it mainly focuses on several parameters that might affect performance. +JDBC usually provides implementation-related configurations in the form of JDBC URL parameters. This section introduces [MySQL Connector/J's parameter configurations](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html) (If you use MariaDB, see [MariaDB's parameter configurations](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)). Because this document cannot cover all configuration items, it mainly focuses on several parameters that might affect performance. #### Prepare-related parameters diff --git a/develop/dev-guide-choose-driver-or-orm.md b/develop/dev-guide-choose-driver-or-orm.md index be597f4fefd12..b8b4d585a4cea 100644 --- a/develop/dev-guide-choose-driver-or-orm.md +++ b/develop/dev-guide-choose-driver-or-orm.md @@ -27,7 +27,7 @@ This section describes how to use drivers and ORM frameworks in Java. Support level: **Full** -You can follow the [MySQL documentation](https://dev.mysql.com/doc/connector-j/8.0/en/) to download and configure a Java JDBC driver. It is recommended to use MySQL Connector/J 8.0.33 or later with TiDB v6.3.0 and newer. +You can follow the [MySQL documentation](https://dev.mysql.com/doc/connector-j/en/) to download and configure a Java JDBC driver. It is recommended to use MySQL Connector/J 8.0.33 or later with TiDB v6.3.0 and newer. > **Tip:** > diff --git a/develop/dev-guide-connect-to-tidb.md b/develop/dev-guide-connect-to-tidb.md index 9ebe316236bbb..9759542f24d51 100644 --- a/develop/dev-guide-connect-to-tidb.md +++ b/develop/dev-guide-connect-to-tidb.md @@ -45,7 +45,7 @@ mysqlsh --sql mysql://root@:4000 ## JDBC -You can connect to TiDB using the [JDBC](https://dev.mysql.com/doc/connector-j/8.0/en/) driver. To do that, you need to create a `MysqlDataSource` or `MysqlConnectionPoolDataSource` object (both objects support the `DataSource` interface), and then set the connection string using the `setURL` function. +You can connect to TiDB using the [JDBC](https://dev.mysql.com/doc/connector-j/en/) driver. To do that, you need to create a `MysqlDataSource` or `MysqlConnectionPoolDataSource` object (both objects support the `DataSource` interface), and then set the connection string using the `setURL` function. For example: @@ -54,7 +54,7 @@ MysqlDataSource mysqlDataSource = new MysqlDataSource(); mysqlDataSource.setURL("jdbc:mysql://{host}:{port}/{database}?user={username}&password={password}"); ``` -For more information on JDBC connections, see the [JDBC documentation](https://dev.mysql.com/doc/connector-j/8.0/en/) +For more information on JDBC connections, see the [JDBC documentation](https://dev.mysql.com/doc/connector-j/en/) ### Connection parameters diff --git a/develop/dev-guide-connection-parameters.md b/develop/dev-guide-connection-parameters.md index fb2f3d8f514c1..f3c7b8fc41aca 100644 --- a/develop/dev-guide-connection-parameters.md +++ b/develop/dev-guide-connection-parameters.md @@ -139,7 +139,7 @@ In most scenarios, to improve execution efficiency, JDBC obtains query results i Usually, there are two kinds of processing methods in JDBC: -- [Set **FetchSize** to `Integer.MIN_VALUE`](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-implementation-notes.html#ResultSet) to ensure that the client does not cache. The client will read the execution result from the network connection through `StreamingResult`. +- [Set **FetchSize** to `Integer.MIN_VALUE`](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-implementation-notes.html#ResultSet) to ensure that the client does not cache. The client will read the execution result from the network connection through `StreamingResult`. When the client uses the streaming read method, it needs to finish reading or close `resultset` before continuing to use the statement to make a query. Otherwise, the error `No statements may be issued when any streaming result sets are open and in use on a given connection. Ensure that you have called .close() on any active streaming result sets before attempting more queries.` is returned. @@ -151,7 +151,7 @@ TiDB supports both methods, but it is preferred that you use the first method, b ### MySQL JDBC parameters -JDBC usually provides implementation-related configurations in the form of JDBC URL parameters. This section introduces [MySQL Connector/J's parameter configurations](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-configuration-properties.html) (If you use MariaDB, see [MariaDB's parameter configurations](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)). Because this document cannot cover all configuration items, it mainly focuses on several parameters that might affect performance. +JDBC usually provides implementation-related configurations in the form of JDBC URL parameters. This section introduces [MySQL Connector/J's parameter configurations](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html) (If you use MariaDB, see [MariaDB's parameter configurations](https://mariadb.com/kb/en/library/about-mariadb-connector-j/#optional-url-parameters)). Because this document cannot cover all configuration items, it mainly focuses on several parameters that might affect performance. #### Prepare-related parameters diff --git a/develop/dev-guide-third-party-tools-compatibility.md b/develop/dev-guide-third-party-tools-compatibility.md index 8db35487191aa..41f5d1078a5a3 100644 --- a/develop/dev-guide-third-party-tools-compatibility.md +++ b/develop/dev-guide-third-party-tools-compatibility.md @@ -131,7 +131,7 @@ Do not use the `noIndexUsed()` and `noGoodIndexUsed()` functions in TiDB. **Description** -TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-connp-props-debugging-profiling.html) parameter. It is a MySQL Connector/J parameter used for debugging that will keep the buffer of the data packet. This might cause the connection to close unexpectedly. **DO NOT** turn it on. +TiDB does not support the [enablePacketDebug](https://dev.mysql.com/doc/connector-j/en/connector-j-connp-props-debugging-profiling.html) parameter. It is a MySQL Connector/J parameter used for debugging that will keep the buffer of the data packet. This might cause the connection to close unexpectedly. **DO NOT** turn it on. **Way to avoid** diff --git a/system-variables.md b/system-variables.md index 9b86ffbb8c6d3..2cb967f19c50b 100644 --- a/system-variables.md +++ b/system-variables.md @@ -3356,7 +3356,7 @@ As shown in this diagram, when [`tidb_enable_paging`](#tidb_enable_paging-new-in > Only the default value of `OFF` can be considered safe. Setting `tidb_multi_statement_mode=ON` might be required if your application was specifically designed for an earlier version of TiDB. If your application requires multiple statement support, it is recommended to use the setting provided by your client library instead of the `tidb_multi_statement_mode` option. For example: > > * [go-sql-driver](https://github.com/go-sql-driver/mysql#multistatements) (`multiStatements`) -> * [Connector/J](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-configuration-properties.html) (`allowMultiQueries`) +> * [Connector/J](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html) (`allowMultiQueries`) > * PHP [mysqli](https://www.php.net/manual/en/mysqli.quickstart.multiple-statement.php) (`mysqli_multi_query`) ### tidb_nontransactional_ignore_error New in v6.1.0 diff --git a/tidb-cloud/secure-connections-to-serverless-clusters.md b/tidb-cloud/secure-connections-to-serverless-clusters.md new file mode 100644 index 0000000000000..558cbdd052dc3 --- /dev/null +++ b/tidb-cloud/secure-connections-to-serverless-clusters.md @@ -0,0 +1,205 @@ +--- +title: TLS Connections to TiDB Serverless +summary: Introduce TLS connections in TiDB Serverless. +aliases: ['/tidbcloud/secure-connections-to-serverless-tier-clusters'] +--- + +# TLS Connections to TiDB Serverless + +Establishing a secure TLS connection between your client and your TiDB Serverless cluster is one of the basic security practices for connecting to your databases. The server certificate for TiDB Serverless is issued by an independent third-party certificate provider. You can easily connect to your TiDB Serverless cluster without downloading a server-side digital certificate. + +## Prerequisites + +- Log in to TiDB Cloud via [Password Authentication](/tidb-cloud/tidb-cloud-password-authentication.md) or [SSO Authentication](/tidb-cloud/tidb-cloud-sso-authentication.md). +- [Create a TiDB Serverless cluster](/tidb-cloud/tidb-cloud-quickstart.md). + +## TLS connection to a TiDB Serverless cluster + +In the [TiDB Cloud console](https://tidbcloud.com/), you can get examples of different connection methods and connect to your TiDB Serverless cluster as follows: + +1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page of your project, and then click the name of your cluster to go to its overview page. + +2. Click **Connect** in the upper-right corner. A dialog is displayed. + +3. In the dialog, keep the default setting of the endpoint type as `Public`, and select your preferred connection method and operating system. + + - Supported connection methods: MySQL CLI, MyCLI, JDBC, Python, Go, and Node.js. + - Supported operating systems: MacOS, Debian, CentOS/RedHat/Fedora, Alpine, OpenSUSE, and Windows. + +4. If you have not set a password yet, click **Create password** to generate a random password for your TiDB Serverless cluster. The password will be automatically embedded in the sample connection string for connecting to your cluster easily. + + > **Note:** + > + > - The random password consists of 16 characters, including uppercase and lowercase letters, numbers, and special characters. + > - After you close this dialog, the generated password will not show again, so you need to save the password in a secure location. If you forget it, you can click **Reset password** in this dialog to reset it. + > - The TiDB Serverless cluster can be accessed through the internet. If you need to use the password elsewhere, it is recommended that you reset it to ensure database security. + +5. Connect to your cluster with the connection string. + + > **Note:** + > + > When you connect to a TiDB Serverless cluster, you must include the prefix for your cluster in the user name and wrap the name with quotation marks. For more information, see [User name prefix](/tidb-cloud/select-cluster-tier.md#user-name-prefix). + +The following examples show the connection strings in MySQL CLI, MyCLI, JDBC, Python, Go, and Node.js. To learn how to get the `` of your operating system, see [Root certificate management](#root-certificate-management). + + +
+ +MySQL CLI client attempts to establish a TLS connection by default. When you connect to TiDB Serverless clusters, you should set `ssl-mode` and `ssl-ca`. + +```shell +mysql --connect-timeout 15 -u -h -P 4000 --ssl-mode=VERIFY_IDENTITY --ssl-ca= -D test -p +``` + +- With `--ssl-mode=VERIFY_IDENTITY`, MySQL CLI client forces to enable TLS and validate TiDB Serverless clusters. +- Use `--ssl-ca=` to set the CA root path on your system. + +
+ +
+ +[MyCLI](https://www.mycli.net/) automatically enables TLS when using TLS related parameters. When you connect to TiDB Serverless clusters, you need to set `ssl-ca` and `ssl-verify-server-cert`. + +```shell +mycli -u -h -P 4000 -D test --ssl-ca= --ssl-verify-server-cert +``` + +- Use `--ssl-ca=` to set the CA root path on your system. +- With `--ssl-verify-server-cert` to validate TiDB Serverless clusters. + +
+ +
+ +[MySQL Connector/J](https://dev.mysql.com/doc/connector-j/en/)'s TLS connection configurations are used here as an example. + +``` +jdbc:mysql://:4000/test?user=&password=&sslMode=VERIFY_IDENTITY&enabledTLSProtocols=TLSv1.2,TLSv1.3 +``` + +- Set `sslMode=VERIFY_IDENTITY` to enable TLS and validate TiDB Serverless clusters. JDBC trusts system CA root certificates by default, so you do not need to configure certificates. +- Set `enabledTLSProtocols=TLSv1.2,TLSv1.3` to restrict the versions of TLS protocol. + +
+ +
+ +[mysqlclient](https://pypi.org/project/mysqlclient/)'s TLS connection configurations are used here as an example. + +``` +host="", user="", password="", port=4000, database="test", ssl_mode="VERIFY_IDENTITY", ssl={"ca": ""} +``` + +- Set `ssl_mode="VERIFY_IDENTITY"` to enable TLS and validate TiDB Serverless clusters. +- Set `ssl={"ca": ""}` to set the CA root path on your system. + +
+ +
+ +[Go-MySQL-Driver](https://github.com/go-sql-driver/mysql)'s TLS connection configurations are used here as an example. + +``` +mysql.RegisterTLSConfig("tidb", &tls.Config{ + MinVersion: tls.VersionTLS12, + ServerName: "", +}) + +db, err := sql.Open("mysql", ":@tcp(:4000)/test?tls=tidb") +``` + +- Register `tls.Config` in connection to enable TLS and validate TiDB Serverless clusters. Go-MySQL-Driver uses system CA root certificates by default, so you do not need to configure certificates. +- Set `MinVersion: tls.VersionTLS12` to restrict the versions of TLS protocol. +- Set `ServerName: ""` to verify TiDB Serverless's hostname. +- If you do not want to register a new TLS configuration, you can just set `tls=true` in the connection string. + +
+ +
+ +[Mysql2](https://www.npmjs.com/package/mysql2)'s TLS connection configurations are used here as an example. + +``` +host: '', port: 4000,user: '', password: '', database: 'test', ssl: {minVersion: 'TLSv1.2', rejectUnauthorized: true} +``` + +- Set `ssl: {minVersion: 'TLSv1.2'}` to restrict the versions of TLS protocol. +- Set `ssl: {rejectUnauthorized: true}` to validate TiDB Serverless clusters. Mysql2 uses system CA root certificates by default, so you do not need to configure certificates. + +
+ + +## Root certificate management + +### Root certificate issuance and validity + +TiDB Serverless uses certificates from [Let's Encrypt](https://letsencrypt.org/) as a Certificate Authority (CA) for TLS connection between clients and TiDB Serverless clusters. Once the TiDB Serverless certificate expires, it will be automatically rotated without affecting the normal operations of your cluster and the established TLS secure connection. + +> **Note:** +> +> TiDB Serverless does not provide a CA root certificate download, because we don't guarantee that the same CA will be used to issue a certificate in the future, which will cause the CA root certificate to change. + +If the client uses the system's root CA stores by default, such as Java and Go, you can easily connect securely to TiDB Serverless clusters without specifying the path of CA roots. If you still want to get a CA certificate for a TiDB Serverless cluster, you can download and use the [Mozilla CA Certificate bundle](https://curl.se/docs/caextract.html) instead of a single CA certificate. + +However, some drivers and ORMs do not use the system root CA stores. In those cases, you need to configure the CA root path of the drivers or ORMs to your system root CA stores. For example, when you use [mysqlclient](https://github.com/PyMySQL/mysqlclient) to connect a TiDB Serverless cluster in Python on macOS, you need to set `ca: /etc/ssl/cert.pem` in the `ssl` argument. + +If you are using a GUI client, such as DBeaver, which does not accept a certificate file with multiple certificates inside, you must download the [ISRG Root X1](https://letsencrypt.org/certs/isrgrootx1.pem.txt) certificate. + +### Root certificate default path + +In different operating systems, the default storage paths of the root certificate are as follows： + +**MacOS** + +``` +/etc/ssl/cert.pem +``` + +**Debian / Ubuntu / Arch** + +``` +/etc/ssl/certs/ca-certificates.crt +``` + +**RedHat / Fedora / CentOS / Mageia** + +``` +/etc/pki/tls/certs/ca-bundle.crt +``` + +**Alpine** + +``` +/etc/ssl/cert.pem +``` + +**OpenSUSE** + +``` +/etc/ssl/ca-bundle.pem +``` + +**Windows** + +Windows does not offer a specific path to the CA root. Instead, it uses the [registry](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/local-machine-and-current-user-certificate-stores) to store certificates. For this reason, to specify the CA root path on Windows, take the following steps: + +1. Download the [Mozilla CA Certificate bundle](https://curl.se/docs/caextract.html) and save it in a path you prefer, such as ``. +2. Use the path (``) as your CA root path when you connect to a TiDB Serverless cluster. + +## FAQs + +### Which TLS versions are supported to connect to my TiDB Serverless cluster? + +For security reasons, TiDB Serverless only supports TLS 1.2 and TLS 1.3, and does not support TLS 1.0 and TLS 1.1 versions. See IETF [Deprecating TLS 1.0 and TLS 1.1](https://datatracker.ietf.org/doc/rfc8996/) for details. + +### Is two-way TLS authentication between my connection client and TiDB Serverless supported? + +No. + +TiDB Serverless only supports one-way TLS authentication, which means your client uses the public key to verify the signature of your TiDB Cloud cluster certificate's private key while the cluster does not validate the client. + +### Does TiDB Serverless have to configure TLS to establish a secure connection? + +For standard connection, TiDB Serverless only allows TLS connections and prohibits non-SSL/TLS connections. The reason is that SSL/TLS is one of the most basic security measures for you to reduce the risk of data exposure to the internet when you connect to the TiDB Serverless cluster through the internet. + +For private endpoint connection, because it supports highly secure and one-way access to the TiDB Cloud service and does not expose your data to the public internet, configuring TLS is optional. diff --git a/tidb-cloud/tidb-cloud-tls-connect-to-dedicated.md b/tidb-cloud/tidb-cloud-tls-connect-to-dedicated.md new file mode 100644 index 0000000000000..b123452b0c715 --- /dev/null +++ b/tidb-cloud/tidb-cloud-tls-connect-to-dedicated.md @@ -0,0 +1,301 @@ +--- +title: TLS Connections to TiDB Dedicated +summary: Introduce TLS connections in TiDB Dedicated. +aliases: ['/tidbcloud/tidb-cloud-tls-connect-to-dedicated-tier'] +--- + +# TLS Connections to TiDB Dedicated + +On TiDB Cloud, establishing TLS connections is one of the basic security practices for connecting to TiDB Dedicated clusters. You can configure multiple TLS connections from your client, application, and development tools to your TiDB Dedicated cluster to protect data transmission security. For security reasons, TiDB Dedicated only supports TLS 1.2 and TLS 1.3, and does not support TLS 1.0 and TLS 1.1 versions. + +To ensure data security, TiDB cluster CA for your TiDB Dedicated cluster is hosted on [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/), and TiDB cluster private keys are stored in AWS-managed hardware security modules (HSMs) that meet [FIPS 140-2 Level 3](https://csrc.nist.gov/projects/cryptographic-module-validation-program/Certificate/3139) security standards. + +## Prerequisites + +- Log in to TiDB Cloud via [Password Authentication](/tidb-cloud/tidb-cloud-password-authentication.md) or [SSO Authentication](/tidb-cloud/tidb-cloud-sso-authentication.md), and then [Create a TiDB Dedicated cluster](/tidb-cloud/create-tidb-cluster.md). + +- Set a password to access your cluster in secure settings. + + To do so, you can navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page of your project, click **...** in the row of your TiDB Dedicated cluster, and then select **Security Settings**. In security settings, you can click **Generate** to automatically generate a root password with a length of 16 characters, including numbers, uppercase and lowercase characters, and special characters. + +## Secure connection to a TiDB Dedicated cluster + +In the [TiDB Cloud console](https://tidbcloud.com/), you can get examples of different connection methods and connect to your TiDB Dedicated cluster as follows: + +1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page of your project, and then click the name of your TiDB Dedicated cluster to go to its overview page. + +2. Click **Connect** in the upper-right corner. A dialog is displayed. + +3. On the **Standard Connection** tab of this dialog, follow the three steps to set up the TLS connection. + - Step 1：Create traffic filter + - Step 2：Download TiDB cluster CA + - Step 3：Connect with an SQL client + +4. Under **Step 1: Create traffic filter** in the dialog, configure the IP addresses that are allowed to access your cluster. For more information, see [Configure an IP access list in standard connection](/tidb-cloud/configure-ip-access-list.md#configure-an-ip-access-list-in-standard-connection). + +5. Under **Step 2: Download TiDB cluster CA**, click **Download TiDB cluster CA** to download it locally for client TLS configuration. The TiDB cluster CA ensures that the TLS connection is secure and reliable. + + > **Note:** + > + > After downloading your TiDB Dedicated cluster CA, you can store it in the default storage path of your operating system, or specify another storage path. You need to replace the CA path in the code example with your own cluster CA path in the subsequent steps. + +6. Under **Step 3: Connect with an SQL client** in the dialog, click the tab of your preferred connection method, and then refer to the connection string and sample code on the tab to connect to your cluster. + +The following examples show the connection strings in MySQL, MyCLI, JDBC, Python, Go, and Node.js: + + +
+ +MySQL CLI client attempts to establish a TLS connection by default. When you connect to TiDB Dedicated clusters, you need to set `ssl-mode` and `ssl-ca`. + +```shell +mysql --connect-timeout 15 --ssl-mode=VERIFY_IDENTITY --ssl-ca=ca.pem --tls-version="TLSv1.2" -u root -h tidb.eqlfbdgthh8.clusters.staging.tidb-cloud.com -P 4000 -D test -p +``` + +Parameter description： + +- With `--ssl-mode=VERIFY_IDENTITY`, MySQL CLI client forces to enable TLS and validate TiDB Dedicated clusters. +- Use `--ssl-ca=` to specify your local path of the downloaded TiDB cluster `ca.pem`. +- Use `--tls-version=TLSv1.2` to restrict the versions of the TLS protocol. If you want to use TLS 1.3, you can set the version to `TLSv1.3`. + +
+ +
+ +[MyCLI](https://www.mycli.net/) automatically enables TLS when using TLS related parameters. When you connect to TiDB Dedicated clusters, you need to set `ssl-ca` and `ssl-verify-server-cert`. + +```shell +mycli --ssl-ca=ca.pem --ssl-verify-server-cert -u root -h tidb.eqlfbdgthh8.clusters.staging.tidb-cloud.com -P 4000 -D test +``` + +Parameter descriptions： + +- Use `--ssl-ca=` to specify your local path of the downloaded TiDB cluster `ca.pem`. +- With `--ssl-verify-server-cert` to validate TiDB Dedicated clusters. + +
+ +
+ +[MySQL Connector/J](https://dev.mysql.com/doc/connector-j/en/)'s TLS connection configurations are used here as an example. + +After downloading TiDB cluster CA, if you want to import it into your operating system, you can use the `keytool -importcert -alias TiDBCACert -file ca.pem -keystore -storepass ` command. + +```shell +/* Be sure to replace the parameters in the following connection string. */ +/* version >= 8.0.28 */ +jdbc:mysql://tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com:4000/test?user=root&password=&sslMode=VERIFY_IDENTITY&tlsVersions=TLSv1.2&trustCertificateKeyStoreUrl=file:&trustCertificateKeyStorePassword= +``` + +You can click **show example usage** to view detailed code examples. + +``` +import com.mysql.jdbc.Driver; +import java.sql.*; + +class Main { + public static void main(String args[]) throws SQLException, ClassNotFoundException { + Class.forName("com.mysql.cj.jdbc.Driver"); + try { + Connection conn = DriverManager.getConnection("jdbc:mysql://tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com:4000/test?user=root&password=&sslMode=VERIFY_IDENTITY&tlsVersions=TLSv1.2&trustCertificateKeyStoreUrl=file:&trustCertificateKeyStorePassword="); + Statement stmt = conn.createStatement(); + try { + ResultSet rs = stmt.executeQuery("SELECT DATABASE();"); + if (rs.next()) { + System.out.println("using db:" + rs.getString(1)); + } + } catch (Exception e) { + System.out.println("exec error:" + e); + } + } catch (Exception e) { + System.out.println("connect error:" + e); + } + } +} +``` + +Parameter description： + +- Set `sslMode=VERIFY_IDENTITY` to enable TLS and validate TiDB Dedicated clusters. +- Set `enabledTLSProtocols=TLSv1.2` to restrict the versions of the TLS protocol. If you want to use TLS 1.3, you can set the version to `TLSv1.3`. +- Set `trustCertificateKeyStoreUrl` to your custom truststore path. +- Set `trustCertificateKeyStorePassword` to your truststore password. + +
+ +
+ +[mysqlclient](https://pypi.org/project/mysqlclient/)'s TLS connection configurations are used here as an example. + +``` +host="tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com", user="root", password="", port=4000, database="test", ssl_mode="VERIFY_IDENTITY", ssl={"ca": "ca.pem"} +``` + +You can click **show example usage** to view detailed code examples. + +``` +import MySQLdb + +connection = MySQLdb.connect(host="tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com", port=4000, user="root", password="", database="test", ssl_mode="VERIFY_IDENTITY", ssl={"ca": "ca.pem"}) + +with connection: + with connection.cursor() as cursor: + cursor.execute("SELECT DATABASE();") + m = cursor.fetchone() + print(m[0]) +``` + +Parameter descriptions： + +- Set `ssl_mode="VERIFY_IDENTITY"` to enable TLS and validate TiDB Dedicated clusters. +- Use `ssl={"ca": ""}` to specify your local path of the downloaded TiDB cluster `ca.pem`. + +
+ +
+ +[Go-MySQL-Driver](https://github.com/go-sql-driver/mysql)'s TLS connection configurations are used here as an example. + +``` +rootCertPool := x509.NewCertPool() +pem, err := ioutil.ReadFile("ca.pem") +if err != nil { + log.Fatal(err) +} +if ok := rootCertPool.AppendCertsFromPEM(pem); !ok { + log.Fatal("Failed to append PEM.") +} +mysql.RegisterTLSConfig("tidb", &tls.Config{ + RootCAs: rootCertPool, + MinVersion: tls.VersionTLS12, + ServerName: "tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com", +}) + +db, err := sql.Open("mysql", "root:@tcp(tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com:4000)/test?tls=tidb") +``` + +You can click **show example usage** to view detailed code examples. + +``` +package main +import ( + "crypto/tls" + "crypto/x509" + "database/sql" + "fmt" + "io/ioutil" + "log" + + "github.com/go-sql-driver/mysql" +) +func main() { + rootCertPool := x509.NewCertPool() + pem, err := ioutil.ReadFile("ca.pem") + if err != nil { + log.Fatal(err) + } + if ok := rootCertPool.AppendCertsFromPEM(pem); !ok { + log.Fatal("Failed to append PEM.") + } + mysql.RegisterTLSConfig("tidb", &tls.Config{ + RootCAs: rootCertPool, + MinVersion: tls.VersionTLS12, + ServerName: "tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com", + }) + db, err := sql.Open("mysql", "root:@tcp(tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com:4000)/test?tls=tidb") + if err != nil { + log.Fatal("failed to connect database", err) + } + defer db.Close() + + var dbName string + err = db.QueryRow("SELECT DATABASE();").Scan(&dbName) + if err != nil { + log.Fatal("failed to execute query", err) + } + fmt.Println(dbName) +} +``` + +Parameter descriptions： + +- Register `tls.Config` in the TLS connection configuration to enable TLS and validate TiDB Dedicated clusters. +- Set `MinVersion: tls.VersionTLS12` to restrict the versions of TLS protocol. +- Set `ServerName: ""` to verify TiDB Dedicated's hostname. +- If you do not want to register a new TLS configuration, you can just set `tls=true` in the connection string. + +
+ +
+ +[Mysql2](https://www.npmjs.com/package/mysql2)'s TLS connection configurations are used here as an example. + +``` +var connection = mysql.createConnection({ + host: 'tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com', + port: 4000, + user: 'root', + password: '', + database: 'test', + ssl: { + ca: fs.readFileSync('ca.pem'), + minVersion: 'TLSv1.2', + rejectUnauthorized: true + } +}); +``` + +You can click **show example usage** to view detailed code examples. + +``` +var mysql = require('mysql2'); +var fs = require('fs'); +var connection = mysql.createConnection({ + host: 'tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com', + port: 4000, + user: 'root', + password: '', + database: 'test', + ssl: { + ca: fs.readFileSync('ca.pem'), + minVersion: 'TLSv1.2', + rejectUnauthorized: true + } +}); +connection.connect(function(err) { + if (err) { + throw err + } + connection.query('SELECT DATABASE();', function(err, rows) { + if (err) { + throw err + } + console.log(rows[0]['DATABASE()']); + connection.end() + }); +}); +``` + +Parameter descriptions： + +- Set `ssl: {minVersion: 'TLSv1.2'}` to restrict the versions of the TLS protocol. If you want to use TLS 1.3, you can set the version to `TLSv1.3`. +- Set `ssl: {ca: fs.readFileSync('')}` to read your local CA path of the downloaded TiDB cluster `ca.pem`. + +
+ + +## Manage root certificates for TiDB Dedicated + +TiDB Dedicated uses certificates from [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) as a Certificate Authority (CA) for TLS connections between clients and TiDB Dedicated clusters. Usually, the root certificates of ACM are stored securely in AWS-managed hardware security modules (HSMs) that meet [FIPS 140-2 Level 3](https://csrc.nist.gov/projects/cryptographic-module-validation-program/Certificate/3139) security standards. + +## FAQs + +### Which TLS versions are supported to connect to my TiDB Dedicated cluster? + +For security reasons, TiDB Dedicated only supports TLS 1.2 and TLS 1.3, and does not support TLS 1.0 and TLS 1.1 versions. See IETF [Deprecating TLS 1.0 and TLS 1.1](https://datatracker.ietf.org/doc/rfc8996/) for details. + +### Is two-way TLS authentication between my client and TiDB Dedicated supported? + +No. + +TiDB Dedicated only supports one-way TLS authentication, and does not support two-way TLS authentication currently. If you need two-way TLS authentication, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). diff --git a/tispark-overview.md b/tispark-overview.md index af197b82d418c..f03a04812eff6 100644 --- a/tispark-overview.md +++ b/tispark-overview.md @@ -342,7 +342,7 @@ spark.tispark.jdbc.client_cert_password jdbc_clientstore_ ``` - For details about how to open TiDB TLS, see [Enable TLS between TiDB Clients and Servers](/enable-tls-between-clients-and-servers.md). -- For details about how to generate a JAVA key store, see [Connecting Securely Using SSL](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-using-ssl.html). +- For details about how to generate a JAVA key store, see [Connecting Securely Using SSL](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-using-ssl.html). ### Log4j configuration From 81a32fb88424d024747364b3a73feeafa698be6f Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 29 Nov 2023 12:24:43 +0800 Subject: [PATCH 2/4] Discard changes to tidb-cloud/secure-connections-to-serverless-clusters.md --- ...cure-connections-to-serverless-clusters.md | 205 ------------------ 1 file changed, 205 deletions(-) delete mode 100644 tidb-cloud/secure-connections-to-serverless-clusters.md diff --git a/tidb-cloud/secure-connections-to-serverless-clusters.md b/tidb-cloud/secure-connections-to-serverless-clusters.md deleted file mode 100644 index 558cbdd052dc3..0000000000000 --- a/tidb-cloud/secure-connections-to-serverless-clusters.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: TLS Connections to TiDB Serverless -summary: Introduce TLS connections in TiDB Serverless. -aliases: ['/tidbcloud/secure-connections-to-serverless-tier-clusters'] ---- - -# TLS Connections to TiDB Serverless - -Establishing a secure TLS connection between your client and your TiDB Serverless cluster is one of the basic security practices for connecting to your databases. The server certificate for TiDB Serverless is issued by an independent third-party certificate provider. You can easily connect to your TiDB Serverless cluster without downloading a server-side digital certificate. - -## Prerequisites - -- Log in to TiDB Cloud via [Password Authentication](/tidb-cloud/tidb-cloud-password-authentication.md) or [SSO Authentication](/tidb-cloud/tidb-cloud-sso-authentication.md). -- [Create a TiDB Serverless cluster](/tidb-cloud/tidb-cloud-quickstart.md). - -## TLS connection to a TiDB Serverless cluster - -In the [TiDB Cloud console](https://tidbcloud.com/), you can get examples of different connection methods and connect to your TiDB Serverless cluster as follows: - -1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page of your project, and then click the name of your cluster to go to its overview page. - -2. Click **Connect** in the upper-right corner. A dialog is displayed. - -3. In the dialog, keep the default setting of the endpoint type as `Public`, and select your preferred connection method and operating system. - - - Supported connection methods: MySQL CLI, MyCLI, JDBC, Python, Go, and Node.js. - - Supported operating systems: MacOS, Debian, CentOS/RedHat/Fedora, Alpine, OpenSUSE, and Windows. - -4. If you have not set a password yet, click **Create password** to generate a random password for your TiDB Serverless cluster. The password will be automatically embedded in the sample connection string for connecting to your cluster easily. - - > **Note:** - > - > - The random password consists of 16 characters, including uppercase and lowercase letters, numbers, and special characters. - > - After you close this dialog, the generated password will not show again, so you need to save the password in a secure location. If you forget it, you can click **Reset password** in this dialog to reset it. - > - The TiDB Serverless cluster can be accessed through the internet. If you need to use the password elsewhere, it is recommended that you reset it to ensure database security. - -5. Connect to your cluster with the connection string. - - > **Note:** - > - > When you connect to a TiDB Serverless cluster, you must include the prefix for your cluster in the user name and wrap the name with quotation marks. For more information, see [User name prefix](/tidb-cloud/select-cluster-tier.md#user-name-prefix). - -The following examples show the connection strings in MySQL CLI, MyCLI, JDBC, Python, Go, and Node.js. To learn how to get the `` of your operating system, see [Root certificate management](#root-certificate-management). - - -
- -MySQL CLI client attempts to establish a TLS connection by default. When you connect to TiDB Serverless clusters, you should set `ssl-mode` and `ssl-ca`. - -```shell -mysql --connect-timeout 15 -u -h -P 4000 --ssl-mode=VERIFY_IDENTITY --ssl-ca= -D test -p -``` - -- With `--ssl-mode=VERIFY_IDENTITY`, MySQL CLI client forces to enable TLS and validate TiDB Serverless clusters. -- Use `--ssl-ca=` to set the CA root path on your system. - -
- -
- -[MyCLI](https://www.mycli.net/) automatically enables TLS when using TLS related parameters. When you connect to TiDB Serverless clusters, you need to set `ssl-ca` and `ssl-verify-server-cert`. - -```shell -mycli -u -h -P 4000 -D test --ssl-ca= --ssl-verify-server-cert -``` - -- Use `--ssl-ca=` to set the CA root path on your system. -- With `--ssl-verify-server-cert` to validate TiDB Serverless clusters. - -
- -
- -[MySQL Connector/J](https://dev.mysql.com/doc/connector-j/en/)'s TLS connection configurations are used here as an example. - -``` -jdbc:mysql://:4000/test?user=&password=&sslMode=VERIFY_IDENTITY&enabledTLSProtocols=TLSv1.2,TLSv1.3 -``` - -- Set `sslMode=VERIFY_IDENTITY` to enable TLS and validate TiDB Serverless clusters. JDBC trusts system CA root certificates by default, so you do not need to configure certificates. -- Set `enabledTLSProtocols=TLSv1.2,TLSv1.3` to restrict the versions of TLS protocol. - -
- -
- -[mysqlclient](https://pypi.org/project/mysqlclient/)'s TLS connection configurations are used here as an example. - -``` -host="", user="", password="", port=4000, database="test", ssl_mode="VERIFY_IDENTITY", ssl={"ca": ""} -``` - -- Set `ssl_mode="VERIFY_IDENTITY"` to enable TLS and validate TiDB Serverless clusters. -- Set `ssl={"ca": ""}` to set the CA root path on your system. - -
- -
- -[Go-MySQL-Driver](https://github.com/go-sql-driver/mysql)'s TLS connection configurations are used here as an example. - -``` -mysql.RegisterTLSConfig("tidb", &tls.Config{ - MinVersion: tls.VersionTLS12, - ServerName: "", -}) - -db, err := sql.Open("mysql", ":@tcp(:4000)/test?tls=tidb") -``` - -- Register `tls.Config` in connection to enable TLS and validate TiDB Serverless clusters. Go-MySQL-Driver uses system CA root certificates by default, so you do not need to configure certificates. -- Set `MinVersion: tls.VersionTLS12` to restrict the versions of TLS protocol. -- Set `ServerName: ""` to verify TiDB Serverless's hostname. -- If you do not want to register a new TLS configuration, you can just set `tls=true` in the connection string. - -
- -
- -[Mysql2](https://www.npmjs.com/package/mysql2)'s TLS connection configurations are used here as an example. - -``` -host: '', port: 4000,user: '', password: '', database: 'test', ssl: {minVersion: 'TLSv1.2', rejectUnauthorized: true} -``` - -- Set `ssl: {minVersion: 'TLSv1.2'}` to restrict the versions of TLS protocol. -- Set `ssl: {rejectUnauthorized: true}` to validate TiDB Serverless clusters. Mysql2 uses system CA root certificates by default, so you do not need to configure certificates. - -
- - -## Root certificate management - -### Root certificate issuance and validity - -TiDB Serverless uses certificates from [Let's Encrypt](https://letsencrypt.org/) as a Certificate Authority (CA) for TLS connection between clients and TiDB Serverless clusters. Once the TiDB Serverless certificate expires, it will be automatically rotated without affecting the normal operations of your cluster and the established TLS secure connection. - -> **Note:** -> -> TiDB Serverless does not provide a CA root certificate download, because we don't guarantee that the same CA will be used to issue a certificate in the future, which will cause the CA root certificate to change. - -If the client uses the system's root CA stores by default, such as Java and Go, you can easily connect securely to TiDB Serverless clusters without specifying the path of CA roots. If you still want to get a CA certificate for a TiDB Serverless cluster, you can download and use the [Mozilla CA Certificate bundle](https://curl.se/docs/caextract.html) instead of a single CA certificate. - -However, some drivers and ORMs do not use the system root CA stores. In those cases, you need to configure the CA root path of the drivers or ORMs to your system root CA stores. For example, when you use [mysqlclient](https://github.com/PyMySQL/mysqlclient) to connect a TiDB Serverless cluster in Python on macOS, you need to set `ca: /etc/ssl/cert.pem` in the `ssl` argument. - -If you are using a GUI client, such as DBeaver, which does not accept a certificate file with multiple certificates inside, you must download the [ISRG Root X1](https://letsencrypt.org/certs/isrgrootx1.pem.txt) certificate. - -### Root certificate default path - -In different operating systems, the default storage paths of the root certificate are as follows： - -**MacOS** - -``` -/etc/ssl/cert.pem -``` - -**Debian / Ubuntu / Arch** - -``` -/etc/ssl/certs/ca-certificates.crt -``` - -**RedHat / Fedora / CentOS / Mageia** - -``` -/etc/pki/tls/certs/ca-bundle.crt -``` - -**Alpine** - -``` -/etc/ssl/cert.pem -``` - -**OpenSUSE** - -``` -/etc/ssl/ca-bundle.pem -``` - -**Windows** - -Windows does not offer a specific path to the CA root. Instead, it uses the [registry](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/local-machine-and-current-user-certificate-stores) to store certificates. For this reason, to specify the CA root path on Windows, take the following steps: - -1. Download the [Mozilla CA Certificate bundle](https://curl.se/docs/caextract.html) and save it in a path you prefer, such as ``. -2. Use the path (``) as your CA root path when you connect to a TiDB Serverless cluster. - -## FAQs - -### Which TLS versions are supported to connect to my TiDB Serverless cluster? - -For security reasons, TiDB Serverless only supports TLS 1.2 and TLS 1.3, and does not support TLS 1.0 and TLS 1.1 versions. See IETF [Deprecating TLS 1.0 and TLS 1.1](https://datatracker.ietf.org/doc/rfc8996/) for details. - -### Is two-way TLS authentication between my connection client and TiDB Serverless supported? - -No. - -TiDB Serverless only supports one-way TLS authentication, which means your client uses the public key to verify the signature of your TiDB Cloud cluster certificate's private key while the cluster does not validate the client. - -### Does TiDB Serverless have to configure TLS to establish a secure connection? - -For standard connection, TiDB Serverless only allows TLS connections and prohibits non-SSL/TLS connections. The reason is that SSL/TLS is one of the most basic security measures for you to reduce the risk of data exposure to the internet when you connect to the TiDB Serverless cluster through the internet. - -For private endpoint connection, because it supports highly secure and one-way access to the TiDB Cloud service and does not expose your data to the public internet, configuring TLS is optional. From eafd5ebb80250ff7349f0ca7ba1a6197ec841c2a Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 29 Nov 2023 12:24:55 +0800 Subject: [PATCH 3/4] Discard changes to tidb-cloud/tidb-cloud-tls-connect-to-dedicated.md --- .../tidb-cloud-tls-connect-to-dedicated.md | 301 ------------------ 1 file changed, 301 deletions(-) delete mode 100644 tidb-cloud/tidb-cloud-tls-connect-to-dedicated.md diff --git a/tidb-cloud/tidb-cloud-tls-connect-to-dedicated.md b/tidb-cloud/tidb-cloud-tls-connect-to-dedicated.md deleted file mode 100644 index b123452b0c715..0000000000000 --- a/tidb-cloud/tidb-cloud-tls-connect-to-dedicated.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: TLS Connections to TiDB Dedicated -summary: Introduce TLS connections in TiDB Dedicated. -aliases: ['/tidbcloud/tidb-cloud-tls-connect-to-dedicated-tier'] ---- - -# TLS Connections to TiDB Dedicated - -On TiDB Cloud, establishing TLS connections is one of the basic security practices for connecting to TiDB Dedicated clusters. You can configure multiple TLS connections from your client, application, and development tools to your TiDB Dedicated cluster to protect data transmission security. For security reasons, TiDB Dedicated only supports TLS 1.2 and TLS 1.3, and does not support TLS 1.0 and TLS 1.1 versions. - -To ensure data security, TiDB cluster CA for your TiDB Dedicated cluster is hosted on [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/), and TiDB cluster private keys are stored in AWS-managed hardware security modules (HSMs) that meet [FIPS 140-2 Level 3](https://csrc.nist.gov/projects/cryptographic-module-validation-program/Certificate/3139) security standards. - -## Prerequisites - -- Log in to TiDB Cloud via [Password Authentication](/tidb-cloud/tidb-cloud-password-authentication.md) or [SSO Authentication](/tidb-cloud/tidb-cloud-sso-authentication.md), and then [Create a TiDB Dedicated cluster](/tidb-cloud/create-tidb-cluster.md). - -- Set a password to access your cluster in secure settings. - - To do so, you can navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page of your project, click **...** in the row of your TiDB Dedicated cluster, and then select **Security Settings**. In security settings, you can click **Generate** to automatically generate a root password with a length of 16 characters, including numbers, uppercase and lowercase characters, and special characters. - -## Secure connection to a TiDB Dedicated cluster - -In the [TiDB Cloud console](https://tidbcloud.com/), you can get examples of different connection methods and connect to your TiDB Dedicated cluster as follows: - -1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page of your project, and then click the name of your TiDB Dedicated cluster to go to its overview page. - -2. Click **Connect** in the upper-right corner. A dialog is displayed. - -3. On the **Standard Connection** tab of this dialog, follow the three steps to set up the TLS connection. - - Step 1：Create traffic filter - - Step 2：Download TiDB cluster CA - - Step 3：Connect with an SQL client - -4. Under **Step 1: Create traffic filter** in the dialog, configure the IP addresses that are allowed to access your cluster. For more information, see [Configure an IP access list in standard connection](/tidb-cloud/configure-ip-access-list.md#configure-an-ip-access-list-in-standard-connection). - -5. Under **Step 2: Download TiDB cluster CA**, click **Download TiDB cluster CA** to download it locally for client TLS configuration. The TiDB cluster CA ensures that the TLS connection is secure and reliable. - - > **Note:** - > - > After downloading your TiDB Dedicated cluster CA, you can store it in the default storage path of your operating system, or specify another storage path. You need to replace the CA path in the code example with your own cluster CA path in the subsequent steps. - -6. Under **Step 3: Connect with an SQL client** in the dialog, click the tab of your preferred connection method, and then refer to the connection string and sample code on the tab to connect to your cluster. - -The following examples show the connection strings in MySQL, MyCLI, JDBC, Python, Go, and Node.js: - - -
- -MySQL CLI client attempts to establish a TLS connection by default. When you connect to TiDB Dedicated clusters, you need to set `ssl-mode` and `ssl-ca`. - -```shell -mysql --connect-timeout 15 --ssl-mode=VERIFY_IDENTITY --ssl-ca=ca.pem --tls-version="TLSv1.2" -u root -h tidb.eqlfbdgthh8.clusters.staging.tidb-cloud.com -P 4000 -D test -p -``` - -Parameter description： - -- With `--ssl-mode=VERIFY_IDENTITY`, MySQL CLI client forces to enable TLS and validate TiDB Dedicated clusters. -- Use `--ssl-ca=` to specify your local path of the downloaded TiDB cluster `ca.pem`. -- Use `--tls-version=TLSv1.2` to restrict the versions of the TLS protocol. If you want to use TLS 1.3, you can set the version to `TLSv1.3`. - -
- -
- -[MyCLI](https://www.mycli.net/) automatically enables TLS when using TLS related parameters. When you connect to TiDB Dedicated clusters, you need to set `ssl-ca` and `ssl-verify-server-cert`. - -```shell -mycli --ssl-ca=ca.pem --ssl-verify-server-cert -u root -h tidb.eqlfbdgthh8.clusters.staging.tidb-cloud.com -P 4000 -D test -``` - -Parameter descriptions： - -- Use `--ssl-ca=` to specify your local path of the downloaded TiDB cluster `ca.pem`. -- With `--ssl-verify-server-cert` to validate TiDB Dedicated clusters. - -
- -
- -[MySQL Connector/J](https://dev.mysql.com/doc/connector-j/en/)'s TLS connection configurations are used here as an example. - -After downloading TiDB cluster CA, if you want to import it into your operating system, you can use the `keytool -importcert -alias TiDBCACert -file ca.pem -keystore -storepass ` command. - -```shell -/* Be sure to replace the parameters in the following connection string. */ -/* version >= 8.0.28 */ -jdbc:mysql://tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com:4000/test?user=root&password=&sslMode=VERIFY_IDENTITY&tlsVersions=TLSv1.2&trustCertificateKeyStoreUrl=file:&trustCertificateKeyStorePassword= -``` - -You can click **show example usage** to view detailed code examples. - -``` -import com.mysql.jdbc.Driver; -import java.sql.*; - -class Main { - public static void main(String args[]) throws SQLException, ClassNotFoundException { - Class.forName("com.mysql.cj.jdbc.Driver"); - try { - Connection conn = DriverManager.getConnection("jdbc:mysql://tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com:4000/test?user=root&password=&sslMode=VERIFY_IDENTITY&tlsVersions=TLSv1.2&trustCertificateKeyStoreUrl=file:&trustCertificateKeyStorePassword="); - Statement stmt = conn.createStatement(); - try { - ResultSet rs = stmt.executeQuery("SELECT DATABASE();"); - if (rs.next()) { - System.out.println("using db:" + rs.getString(1)); - } - } catch (Exception e) { - System.out.println("exec error:" + e); - } - } catch (Exception e) { - System.out.println("connect error:" + e); - } - } -} -``` - -Parameter description： - -- Set `sslMode=VERIFY_IDENTITY` to enable TLS and validate TiDB Dedicated clusters. -- Set `enabledTLSProtocols=TLSv1.2` to restrict the versions of the TLS protocol. If you want to use TLS 1.3, you can set the version to `TLSv1.3`. -- Set `trustCertificateKeyStoreUrl` to your custom truststore path. -- Set `trustCertificateKeyStorePassword` to your truststore password. - -
- -
- -[mysqlclient](https://pypi.org/project/mysqlclient/)'s TLS connection configurations are used here as an example. - -``` -host="tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com", user="root", password="", port=4000, database="test", ssl_mode="VERIFY_IDENTITY", ssl={"ca": "ca.pem"} -``` - -You can click **show example usage** to view detailed code examples. - -``` -import MySQLdb - -connection = MySQLdb.connect(host="tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com", port=4000, user="root", password="", database="test", ssl_mode="VERIFY_IDENTITY", ssl={"ca": "ca.pem"}) - -with connection: - with connection.cursor() as cursor: - cursor.execute("SELECT DATABASE();") - m = cursor.fetchone() - print(m[0]) -``` - -Parameter descriptions： - -- Set `ssl_mode="VERIFY_IDENTITY"` to enable TLS and validate TiDB Dedicated clusters. -- Use `ssl={"ca": ""}` to specify your local path of the downloaded TiDB cluster `ca.pem`. - -
- -
- -[Go-MySQL-Driver](https://github.com/go-sql-driver/mysql)'s TLS connection configurations are used here as an example. - -``` -rootCertPool := x509.NewCertPool() -pem, err := ioutil.ReadFile("ca.pem") -if err != nil { - log.Fatal(err) -} -if ok := rootCertPool.AppendCertsFromPEM(pem); !ok { - log.Fatal("Failed to append PEM.") -} -mysql.RegisterTLSConfig("tidb", &tls.Config{ - RootCAs: rootCertPool, - MinVersion: tls.VersionTLS12, - ServerName: "tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com", -}) - -db, err := sql.Open("mysql", "root:@tcp(tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com:4000)/test?tls=tidb") -``` - -You can click **show example usage** to view detailed code examples. - -``` -package main -import ( - "crypto/tls" - "crypto/x509" - "database/sql" - "fmt" - "io/ioutil" - "log" - - "github.com/go-sql-driver/mysql" -) -func main() { - rootCertPool := x509.NewCertPool() - pem, err := ioutil.ReadFile("ca.pem") - if err != nil { - log.Fatal(err) - } - if ok := rootCertPool.AppendCertsFromPEM(pem); !ok { - log.Fatal("Failed to append PEM.") - } - mysql.RegisterTLSConfig("tidb", &tls.Config{ - RootCAs: rootCertPool, - MinVersion: tls.VersionTLS12, - ServerName: "tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com", - }) - db, err := sql.Open("mysql", "root:@tcp(tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com:4000)/test?tls=tidb") - if err != nil { - log.Fatal("failed to connect database", err) - } - defer db.Close() - - var dbName string - err = db.QueryRow("SELECT DATABASE();").Scan(&dbName) - if err != nil { - log.Fatal("failed to execute query", err) - } - fmt.Println(dbName) -} -``` - -Parameter descriptions： - -- Register `tls.Config` in the TLS connection configuration to enable TLS and validate TiDB Dedicated clusters. -- Set `MinVersion: tls.VersionTLS12` to restrict the versions of TLS protocol. -- Set `ServerName: ""` to verify TiDB Dedicated's hostname. -- If you do not want to register a new TLS configuration, you can just set `tls=true` in the connection string. - -
- -
- -[Mysql2](https://www.npmjs.com/package/mysql2)'s TLS connection configurations are used here as an example. - -``` -var connection = mysql.createConnection({ - host: 'tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com', - port: 4000, - user: 'root', - password: '', - database: 'test', - ssl: { - ca: fs.readFileSync('ca.pem'), - minVersion: 'TLSv1.2', - rejectUnauthorized: true - } -}); -``` - -You can click **show example usage** to view detailed code examples. - -``` -var mysql = require('mysql2'); -var fs = require('fs'); -var connection = mysql.createConnection({ - host: 'tidb.srgnqxji5bc.clusters.staging.tidb-cloud.com', - port: 4000, - user: 'root', - password: '', - database: 'test', - ssl: { - ca: fs.readFileSync('ca.pem'), - minVersion: 'TLSv1.2', - rejectUnauthorized: true - } -}); -connection.connect(function(err) { - if (err) { - throw err - } - connection.query('SELECT DATABASE();', function(err, rows) { - if (err) { - throw err - } - console.log(rows[0]['DATABASE()']); - connection.end() - }); -}); -``` - -Parameter descriptions： - -- Set `ssl: {minVersion: 'TLSv1.2'}` to restrict the versions of the TLS protocol. If you want to use TLS 1.3, you can set the version to `TLSv1.3`. -- Set `ssl: {ca: fs.readFileSync('')}` to read your local CA path of the downloaded TiDB cluster `ca.pem`. - -
- - -## Manage root certificates for TiDB Dedicated - -TiDB Dedicated uses certificates from [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) as a Certificate Authority (CA) for TLS connections between clients and TiDB Dedicated clusters. Usually, the root certificates of ACM are stored securely in AWS-managed hardware security modules (HSMs) that meet [FIPS 140-2 Level 3](https://csrc.nist.gov/projects/cryptographic-module-validation-program/Certificate/3139) security standards. - -## FAQs - -### Which TLS versions are supported to connect to my TiDB Dedicated cluster? - -For security reasons, TiDB Dedicated only supports TLS 1.2 and TLS 1.3, and does not support TLS 1.0 and TLS 1.1 versions. See IETF [Deprecating TLS 1.0 and TLS 1.1](https://datatracker.ietf.org/doc/rfc8996/) for details. - -### Is two-way TLS authentication between my client and TiDB Dedicated supported? - -No. - -TiDB Dedicated only supports one-way TLS authentication, and does not support two-way TLS authentication currently. If you need two-way TLS authentication, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). From a24f0074bdd2a847d950c3fece87f513afe41ed6 Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 29 Nov 2023 12:25:53 +0800 Subject: [PATCH 4/4] fix broken link Signed-off-by: Aolin --- tidb-cloud/secure-connections-to-serverless-tier-clusters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/secure-connections-to-serverless-tier-clusters.md b/tidb-cloud/secure-connections-to-serverless-tier-clusters.md index c59b6d29c8e84..94ee70b595a4a 100644 --- a/tidb-cloud/secure-connections-to-serverless-tier-clusters.md +++ b/tidb-cloud/secure-connections-to-serverless-tier-clusters.md @@ -72,7 +72,7 @@ mycli -u -h -P 4000 -D test --ssl-ca= --ssl-veri
-[MySQL Connector/J](https://dev.mysql.com/doc/connector-j/8.0/en/)'s TLS connection configurations are used here as an example. +[MySQL Connector/J](https://dev.mysql.com/doc/connector-j/en/)'s TLS connection configurations are used here as an example. ``` jdbc:mysql://:4000/test?user=&password=&sslMode=VERIFY_IDENTITY&enabledTLSProtocols=TLSv1.2,TLSv1.3