Skip to content

certificate-authentication: small updates #21951

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

certificate-authentication: small updates #21951

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
70f8d66
certificate-authentication: small updates
dveeden Oct 21, 2025
3c48574
Apply suggestion from @gemini-code-assist[bot]
dveeden Oct 21, 2025
9934915
Apply suggestion from @gemini-code-assist[bot]
dveeden Oct 21, 2025
0d5e3a4
Apply suggestion from @gemini-code-assist[bot]
dveeden Oct 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 21 additions & 73 deletions certificate-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,6 @@ It is recommended that you use [OpenSSL](https://www.openssl.org/) to create key

1. Execute the following command to generate the CA key:

{{< copyable "shell-regular" >}}

```bash
sudo openssl genrsa 2048 > ca-key.pem
```
Expand All @@ -52,16 +50,12 @@ It is recommended that you use [OpenSSL](https://www.openssl.org/) to create key

2. Execute the following command to generate the certificate corresponding to the CA key:

{{< copyable "shell-regular" >}}

```bash
sudo openssl req -new -x509 -nodes -days 365000 -key ca-key.pem -out ca-cert.pem
```

3. Enter detailed certificate information. For example:

{{< copyable "shell-regular" >}}

```bash
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Expand All @@ -80,16 +74,12 @@ It is recommended that you use [OpenSSL](https://www.openssl.org/) to create key

1. Execute the following command to generate the server key:

{{< copyable "shell-regular" >}}

```bash
sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout server-key.pem -out server-req.pem
```

2. Enter detailed certificate information. For example:

{{< copyable "shell-regular" >}}

```bash
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Expand All @@ -107,8 +97,6 @@ It is recommended that you use [OpenSSL](https://www.openssl.org/) to create key

3. Execute the following command to generate the RSA key of the server:

{{< copyable "shell-regular" >}}

```bash
sudo openssl rsa -in server-key.pem -out server-key.pem
```
Expand All @@ -121,8 +109,6 @@ It is recommended that you use [OpenSSL](https://www.openssl.org/) to create key

4. Use the CA certificate signature to generate the signed server certificate:

{{< copyable "shell-regular" >}}

```bash
sudo openssl x509 -req -in server-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem
```
Expand All @@ -145,16 +131,12 @@ After generating the server key and certificate, you need to generate the key an

1. Execute the following command to generate the client key:

{{< copyable "shell-regular" >}}

```bash
sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout client-key.pem -out client-req.pem
```

2. Enter detailed certificate information. For example:

{{< copyable "shell-regular" >}}

```bash
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Expand All @@ -172,8 +154,6 @@ After generating the server key and certificate, you need to generate the key an

3. Execute the following command to generate the RSA key of the client:

{{< copyable "shell-regular" >}}

```bash
sudo openssl rsa -in client-key.pem -out client-key.pem
```
Expand All @@ -186,8 +166,6 @@ After generating the server key and certificate, you need to generate the key an

4. Use the CA certificate signature to generate the client certificate:

{{< copyable "shell-regular" >}}

```bash
sudo openssl x509 -req -in client-req.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem
```
Expand All @@ -202,14 +180,12 @@ After generating the server key and certificate, you need to generate the key an

> **Note:**
>
> The information of the `subject` section in the above output is used for [certificate configuration for login verification](#configure-the-user-certificate-information-for-login-verification) in the `require` section.
> The information of the `subject` section in the above output is used for [certificate configuration for login verification](#configure-the-user-certificate-information-for-login-verification) in the `REQUIRE` section.

### Verify certificate

Execute the following command to verify certificate:

{{< copyable "shell-regular" >}}

```bash
openssl verify -CAfile ca-cert.pem server-cert.pem client-cert.pem
```
Expand All @@ -229,13 +205,11 @@ After generating the certificates, you need to configure the TiDB server and the

Modify the `[security]` section in the TiDB configuration file. This step specifies the directory in which the CA certificate, the server key, and the server certificate are stored. You can replace `path/to/server-cert.pem`, `path/to/server-key.pem`, `path/to/ca-cert.pem` with your own directory.

{{< copyable "" >}}

```
```toml
[security]
ssl-cert ="path/to/server-cert.pem"
ssl-key ="path/to/server-key.pem"
ssl-ca="path/to/ca-cert.pem"
ssl-cert = "path/to/server-cert.pem"
ssl-key = "path/to/server-key.pem"
ssl-ca = "path/to/ca-cert.pem"
```

Start TiDB and check logs. If the following information is displayed in the log, the configuration is successful:
Expand All @@ -250,10 +224,8 @@ Configure the client so that the client uses the client key and certificate for

Taking the MySQL client as an example, you can use the newly created client certificate, client key and CA by specifying `ssl-cert`, `ssl-key`, and `ssl-ca`:

{{< copyable "shell-regular" >}}

```bash
mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem
mysql -u test -h 0.0.0.0 -P 4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem
```

> **Note:**
Expand All @@ -268,32 +240,26 @@ First, connect TiDB using the client to configure the login verification. Then,

The user certificate information can be specified by `REQUIRE SUBJECT`, `REQUIRE ISSUER`, `REQUIRE SAN`, and `REQUIRE CIPHER`, which are used to check the X.509 certificate attributes.

+ `REQUIRE SUBJECT`: Specifies the subject information of the client certificate when you log in. With this option specified, you do not need to configure `require ssl` or x509. The information to be specified is consistent with the entered subject information in [Generate client keys and certificates](#generate-client-key-and-certificate).
+ `REQUIRE SUBJECT`: Specifies the subject information of the client certificate when you log in. With this option specified, you do not need to configure `REQUIRE SSL` or `REQUIRE X509`. The information to be specified is consistent with the entered subject information in [Generate client keys and certificates](#generate-client-key-and-certificate).

To get this option, execute the following command:

{{< copyable "shell-regular" >}}

```bash
openssl x509 -noout -subject -in client-cert.pem | sed 's/.\{8\}//' | sed 's/, /\//g' | sed 's/ = /=/g' | sed 's/^/\//'
```

+ `require issuer`: Specifies the `subject` information of the CA certificate that issues the user certificate. The information to be specified is consistent with the entered `subject` information in [Generate CA key and certificate](#generate-ca-key-and-certificate).
+ `REQUIRE ISSUER`: Specifies the `subject` information of the CA certificate that issues the user certificate. The information to be specified is consistent with the entered `subject` information in [Generate CA key and certificate](#generate-ca-key-and-certificate).

To get this option, execute the following command:

{{< copyable "shell-regular" >}}

```bash
openssl x509 -noout -subject -in ca-cert.pem | sed 's/.\{8\}//' | sed 's/, /\//g' | sed 's/ = /=/g' | sed 's/^/\//'
```

+ `require san`: Specifies the `Subject Alternative Name` information of the CA certificate that issues the user certificate. The information to be specified is consistent with the [`alt_names` of the `openssl.cnf` configuration file](https://docs.pingcap.com/tidb/stable/generate-self-signed-certificates) used to generate the client certificate.
+ `REQUIRE SAN`: Specifies the `Subject Alternative Name` information of the CA certificate that issues the user certificate. The information to be specified is consistent with the [`alt_names` of the `openssl.cnf` configuration file](https://docs.pingcap.com/tidb/stable/generate-self-signed-certificates) used to generate the client certificate.

+ Execute the following command to get the information of the `REQUIRE SAN` item in the generated certificate:

{{< copyable "shell-regular" >}}

```shell
openssl x509 -noout -extensions subjectAltName -in client.crt
```
Expand All @@ -306,8 +272,6 @@ The user certificate information can be specified by `REQUIRE SUBJECT`, `REQUIRE

+ Multiple check items can be configured after they are connected by commas. For example, configure `REQUIRE SAN` as follows for the `u1` user:

{{< copyable "sql" >}}

```sql
CREATE USER 'u1'@'%' REQUIRE SAN 'DNS:d1,URI:spiffe://example.org/myservice1,URI:spiffe://example.org/myservice2';
```
Expand All @@ -328,16 +292,12 @@ You can configure one option or multiple options using the space or `and` as the

+ Configure user certificate when creating a user (`CREATE USER`):

{{< copyable "sql" >}}

```sql
CREATE USER 'u1'@'%' REQUIRE ISSUER '<replaceable>' SUBJECT '<replaceable>' SAN '<replaceable>' CIPHER '<replaceable>';
```

+ Configure user certificate when altering a user:

{{< copyable "sql" >}}

```sql
ALTER USER 'u1'@'%' REQUIRE ISSUER '<replaceable>' SUBJECT '<replaceable>' SAN '<replaceable>' CIPHER '<replaceable>';
```
Expand All @@ -346,7 +306,7 @@ After the above configuration, the following items will be verified when you log

+ SSL is used; the CA that issues the client certificate is consistent with the CA configured in the server.
+ The `issuer` information of the client certificate matches the information specified in `REQUIRE ISSUER`.
+ The `subject` information of the client certificate matches the information specified in `REQUIRE CIPHER`.
+ The cipher used for the connection matches the one specified in `REQUIRE CIPHER`.
+ The `Subject Alternative Name` information of the client certificate matches the information specified in `REQUIRE SAN`.

You can log into TiDB only after all the above items are verified. Otherwise, the `ERROR 1045 (28000): Access denied` error is returned. You can use the following command to check the TLS version, the cipher algorithm and whether the current connection uses the certificate for the login.
Expand Down Expand Up @@ -401,37 +361,29 @@ The CA certificate is the basis for mutual verification between the client and s

1. Back up the old CA key and certificate (suppose that `ca-key.pem` is stolen):

{{< copyable "shell-regular" >}}

```bash
mv ca-key.pem ca-key.old.pem && \
mv ca-cert.pem ca-cert.old.pem
```

2. Generate the new CA key:

{{< copyable "shell-regular" >}}

```bash
sudo openssl genrsa 2048 > ca-key.pem
```

3. Generate the new CA certificate using the newly generated CA key:

{{< copyable "shell-regular" >}}

```bash
sudo openssl req -new -x509 -nodes -days 365000 -key ca-key.pem -out ca-cert.new.pem
```

> **Note:**
>
> Generating the new CA certificate is to replace the keys and certificates on the client and server, and to ensure that online users are not affected. Therefore, the appended information in the above command must be consistent with the `require issuer` information.
> Generating the new CA certificate is to replace the keys and certificates on the client and server, and to ensure that online users are not affected. Therefore, the appended information in the above command must be consistent with the `REQUIRE ISSUER` information.

4. Generate the combined CA certificate:

{{< copyable "shell-regular" >}}

```bash
cat ca-cert.new.pem ca-cert.old.pem > ca-cert.pem
```
Expand All @@ -448,31 +400,25 @@ Also replace the old CA certificate with the combined certificate so that the cl

1. Generate the new RSA key of the client:

{{< copyable "shell-regular" >}}

```bash
sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout client-key.new.pem -out client-req.new.pem && \
sudo openssl rsa -in client-key.new.pem -out client-key.new.pem
```

> **Note:**
>
> The above command is to replace the client key and certificate, and to ensure that the online users are not affected. Therefore, the appended information in the above command must be consistent with the `require subject` information.
> The above command is to replace the client key and certificate, and to ensure that the online users are not affected. Therefore, the appended information in the above command must be consistent with the `REQUIRE SUBJECT` information.

2. Use the combined certificate and the new CA key to generate the new client certificate:

{{< copyable "shell-regular" >}}

```bash
sudo openssl x509 -req -in client-req.new.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.new.pem
```

3. Make the client (for example, MySQL) connect TiDB with the new client key and certificate:

{{< copyable "shell-regular" >}}

```bash
mysql -utest -h0.0.0.0 -P4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem
mysql -u test -h 0.0.0.0 -P 4000 --ssl-cert /path/to/client-cert.new.pem --ssl-key /path/to/client-key.new.pem --ssl-ca /path/to/ca-cert.pem
```

> **Note:**
Expand All @@ -483,23 +429,25 @@ Also replace the old CA certificate with the combined certificate so that the cl

1. Generate the new RSA key of the server:

{{< copyable "shell-regular" >}}

```bash
sudo openssl req -newkey rsa:2048 -days 365000 -nodes -keyout server-key.new.pem -out server-req.new.pem && \
sudo openssl rsa -in server-key.new.pem -out server-key.new.pem
```

2. Use the combined CA certificate and the new CA key to generate the new server certificate:

{{< copyable "shell-regular" >}}

```bash
sudo openssl x509 -req -in server-req.new.pem -days 365000 -CA ca-cert.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.new.pem
```

3. Configure the TiDB server to use the new server key and certificate. See [Configure TiDB server](#configure-tidb-and-the-client-to-use-certificates) for details.
3. Configure the TiDB server to use the new server key and certificate.

Place the files in the location that was specified before in the [Configure TiDB to use server certificate](#configure-tidb-to-use-server-certificate) section.

```sql
ALTER INSTANCE RELOAD TLS;
```

## Policy-based access control for certificates

TiDB supports policy-based access control (PBAC) for certificates, leveraging policies defined by the underlying key management server. This enables fine-grained control over access based on various criteria, such as time-based policies (for example, certificates only valid during specific hours), location-based policies (for example, restricting access to certain geographic locations), and other customizable conditions, ensuring enhanced security and flexibility in certificate management.
TiDB supports policy-based access control (PBAC) for certificates, leveraging policies defined by the underlying key management server. This enables fine-grained control over access based on various criteria, such as time-based policies (for example, certificates only valid during specific hours), location-based policies (for example, restricting access to certain geographic locations), and other customizable conditions, ensuring enhanced security and flexibility in certificate management.