From ed7f6b75835d8f0c89483f47c39ebbcacb165040 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Tue, 21 Oct 2025 08:50:03 +0200 Subject: [PATCH 1/7] certificate-authentication: small updates --- certificate-authentication.md | 94 ++++++++--------------------------- 1 file changed, 21 insertions(+), 73 deletions(-) diff --git a/certificate-authentication.md b/certificate-authentication.md index 635012727d5f6..b3890d25d843b 100644 --- a/certificate-authentication.md +++ b/certificate-authentication.md @@ -34,8 +34,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 ``` @@ -51,16 +49,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 @@ -79,16 +73,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 @@ -106,8 +96,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 ``` @@ -120,8 +108,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 ``` @@ -144,16 +130,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 @@ -171,8 +153,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 ``` @@ -185,8 +165,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 ``` @@ -201,14 +179,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 ``` @@ -228,13 +204,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: @@ -249,10 +223,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:** @@ -267,32 +239,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 ``` @@ -305,8 +271,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'; ``` @@ -327,16 +291,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 '' SUBJECT '' SAN '' CIPHER ''; ``` + Configure user certificate when altering a user: - {{< copyable "sql" >}} - ```sql ALTER USER 'u1'@'%' REQUIRE ISSUER '' SUBJECT '' SAN '' CIPHER ''; ``` @@ -345,7 +305,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 of the connection matches the information 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. @@ -400,8 +360,6 @@ 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 @@ -409,28 +367,22 @@ The CA certificate is the basis for mutual verification between the client and s 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 ``` @@ -447,8 +399,6 @@ 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 @@ -456,22 +406,18 @@ Also replace the old CA certificate with the combined certificate so that the cl > **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:** @@ -482,8 +428,6 @@ 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 @@ -491,14 +435,18 @@ Also replace the old CA certificate with the combined certificate so that the cl 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 [server configuration](#configure-tidb-to-use-server-certificate). + + ```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. \ No newline at end of file +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. From 31bb3680c3cf3c8eacebeeaa0c17aa4c5421cb64 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Tue, 21 Oct 2025 09:57:39 +0200 Subject: [PATCH 2/7] Apply suggestion from @gemini-code-assist[bot] Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- certificate-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/certificate-authentication.md b/certificate-authentication.md index b3890d25d843b..0288e6740b9cd 100644 --- a/certificate-authentication.md +++ b/certificate-authentication.md @@ -239,7 +239,7 @@ 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 `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). ++ `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: From c1318b21ef95fdac0d7196ee095519bb0467bfb5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Tue, 21 Oct 2025 09:58:16 +0200 Subject: [PATCH 3/7] Apply suggestion from @gemini-code-assist[bot] Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- certificate-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/certificate-authentication.md b/certificate-authentication.md index 0288e6740b9cd..367c8f7f71ac1 100644 --- a/certificate-authentication.md +++ b/certificate-authentication.md @@ -305,7 +305,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 cipher of the connection 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. From cbcf98395127d60eda075514538f2f27a716f1f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Tue, 21 Oct 2025 09:58:41 +0200 Subject: [PATCH 4/7] Apply suggestion from @gemini-code-assist[bot] Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- certificate-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/certificate-authentication.md b/certificate-authentication.md index 367c8f7f71ac1..ac2a004a31e89 100644 --- a/certificate-authentication.md +++ b/certificate-authentication.md @@ -441,7 +441,7 @@ Also replace the old CA certificate with the combined certificate so that the cl 3. Configure the TiDB server to use the new server key and certificate. - Place the files in the location that was specified before in [server configuration](#configure-tidb-to-use-server-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; From ef2a7dffb1b7dbe6df5ab2cd5819eab2c5019846 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 13 Nov 2025 10:24:55 +0800 Subject: [PATCH 5/7] Update certificate-authentication.md --- certificate-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/certificate-authentication.md b/certificate-authentication.md index ac2a004a31e89..6b348bd3b1ec1 100644 --- a/certificate-authentication.md +++ b/certificate-authentication.md @@ -441,7 +441,7 @@ Also replace the old CA certificate with the combined certificate so that the cl 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. + Place the files in the location that is specified before in the [Configure TiDB to use server certificate](#configure-tidb-to-use-server-certificate) section. ```sql ALTER INSTANCE RELOAD TLS; From e7fe2686c7b86ef39445a9650171b01e6a6e5888 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 13 Nov 2025 10:40:06 +0800 Subject: [PATCH 6/7] Update certificate-authentication.md --- certificate-authentication.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/certificate-authentication.md b/certificate-authentication.md index 6b348bd3b1ec1..338842f173461 100644 --- a/certificate-authentication.md +++ b/certificate-authentication.md @@ -439,9 +439,7 @@ Also replace the old CA certificate with the combined certificate so that the cl 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. - - Place the files in the location that is specified before in the [Configure TiDB to use server certificate](#configure-tidb-to-use-server-certificate) section. +3. Configure the TiDB server to use the new server key and certificate. Place the files in the location that is specified before in the [Configure TiDB to use server certificate](#configure-tidb-to-use-server-certificate) section. ```sql ALTER INSTANCE RELOAD TLS; From 65b9064027f6f64605553f2c7ebc8767e2855065 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 13 Nov 2025 10:56:25 +0800 Subject: [PATCH 7/7] Update certificate-authentication.md Co-authored-by: Grace Cai --- certificate-authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/certificate-authentication.md b/certificate-authentication.md index 338842f173461..a1fe29bdb0c4d 100644 --- a/certificate-authentication.md +++ b/certificate-authentication.md @@ -439,7 +439,7 @@ Also replace the old CA certificate with the combined certificate so that the cl 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. Place the files in the location that is specified before in the [Configure TiDB to use server certificate](#configure-tidb-to-use-server-certificate) section. +3. Configure the TiDB server to use the new server key and certificate. Place the files in the same directory specified in the [Configure TiDB to use server certificate](#configure-tidb-to-use-server-certificate) section. ```sql ALTER INSTANCE RELOAD TLS;