diff --git a/certificate-authentication.md b/certificate-authentication.md index 8ea99173f8cc4..8051e6865ef60 100644 --- a/certificate-authentication.md +++ b/certificate-authentication.md @@ -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 ``` @@ -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 @@ -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 @@ -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 ``` @@ -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 ``` @@ -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 @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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: @@ -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:** @@ -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 ``` @@ -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'; ``` @@ -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 '' SUBJECT '' SAN '' CIPHER ''; ``` + Configure user certificate when altering a user: - {{< copyable "sql" >}} - ```sql ALTER USER 'u1'@'%' REQUIRE ISSUER '' SUBJECT '' SAN '' CIPHER ''; ``` @@ -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. @@ -401,8 +361,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 @@ -410,28 +368,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 ``` @@ -448,8 +400,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 @@ -457,22 +407,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:** @@ -483,8 +429,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 @@ -492,14 +436,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 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. \ 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.