TLS Connections to TiDB Dedicated

MyCLI 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.

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=<CA_path> 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'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 <your_custom_truststore_path> -storepass <your_truststore_password> command.

/* 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=<your_password>&sslMode=VERIFY_IDENTITY&tlsVersions=TLSv1.2&trustCertificateKeyStoreUrl=file:<your_custom_truststore_path>&trustCertificateKeyStorePassword=<your_truststore_password>

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'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": "<CA_path>"} to specify your local path of the downloaded TiDB cluster ca.pem.

Go-MySQL-Driver'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: "<host>" 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'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('<CA_path>')} to read your local CA path of the downloaded TiDB cluster ca.pem.