Help Center/ Distributed Message Service for Kafka/ User Guide/ Connecting to an Instance/ Configuring Kafka Access Control/ Generating and Replacing an SSL Kafka Certificate in JKS Format
Updated on 2025-08-21 GMT+08:00
View PDF
Share

Generating and Replacing an SSL Kafka Certificate in JKS Format

The SSL certificate secures data transmission through encryption between a client and an instance.

When connecting a Kafka client to a Kafka instance that has ciphertext access enabled and SASL_SSL as the security protocol, use either the certificate provided by DMS for Kafka or your own certificate. This section describes how to generate your own certificate and use it to replace the one provided by DMS for Kafka.

To generate and replace certificates, contact background support personnel to enable the function for you. This function is available on a whitelist basis in all regions.

Step 1: Generating a Certificate to Step 4: Verifying the Certificate describe how to make an SSL certificate applicable to the scenario where certificate domain name verification is not enabled, and how to replace with the certificate. To make an SSL certificate applicable to the scenario where certificate domain name verification is enabled, see (Optional) Making and Replacing an SSL Certificate with Domain Name Verification Enabled.

Notes and Constraints

Replacing the certificate will restart the instance. Exercise caution.

Prerequisites

  • A Linux server is available. The server must install Java Development Kit 1.8.111 or later and JAVA_HOME and PATH environment variables are configured.
  • Kafka SASL_SSL has been enabled for the instance.
  • (Optional) To generate an SSL certificate with domain name verification enabled, obtain the connection address from the Connection area on the Kafka instance details page.

Step 1: Generating a Certificate

  1. Log in to the Linux server and run the following command to generate the server.keystore.jks certificate: 

    keytool -genkey -keystore server.keystore.jks -alias localhost -validity 3650 -keyalg RSA

    Enter the keystore password as prompted and record the password for later use.

    The password must meet the following requirements:

    • Contains 8 to 32 characters.
    • Contains at least three of the following character types: letters, digits, spaces, and special characters `-!@#$ %^&*()-_=+\|[{}]:'",<.>/? and does not start with a hyphen (-).
    • Cannot be a weak password. To check whether a password is weak, enter it in 5.

    Enter the information about the certificate owner as prompted, such as the name, company, organization, city, and country or region.

    [root@ecs-kafka ~]# keytool -genkey -keystore server.keystore.jks -alias localhost -validity 3650 -keyalg RSA
Enter keystore password:  
Re-enter new password: 
What is your first and last name?
  [Unknown]:  Tom
What is the name of your organizational unit?
  [Unknown]:  test
What is the name of your organization?
  [Unknown]:  test01
What is the name of your City or Locality?
  [Unknown]:  nj
What is the name of your State or Province?
  [Unknown]:  js
What is the two-letter country code for this unit?
  [Unknown]:  xx
Is CN=Tom, OU=test, O=test01, L=nj, ST=js, C=xx correct?
  [no]:  y

  2. Run the following command to generate a CA: 

    openssl req -new -x509 -keyout ca-key -out ca-cert -days 3650

    Enter the PEM password as prompted and record the password for later use.

    The password must meet the following requirements: 4 to 1024 characters.

    Enter the information about the certificate owner as prompted, such as the country or region, city, organization, company, name, and email.

    [root@ecs-kafka ~]# openssl req -new -x509 -keyout ca-key -out ca-cert -days 3650
Generating an RSA private key
............................................................................................................................................+++++
..........+++++
writing new private key to 'ca-key'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:xx
State or Province Name (full name) []:js
Locality Name (eg, city) [Default City]:nj
Organization Name (eg, company) [Default Company Ltd]:test01
Organizational Unit Name (eg, section) []:test
Common Name (eg, your name or your server's hostname) []:Tom 
Email Address []:xx
[root@ecs-kafka ~]#

  3. The certificate validity can be checked only after a truststore certificate is created. Run the following command to create a server truststore certificate with the generated CA: 

    keytool -keystore server.truststore.jks -alias CARoot -import -file ca-cert

    Enter the truststore password of the server certificate as prompted and record the password for later use.

    The password must meet the following requirements:

    • Contains 8 to 32 characters.
    • Contains at least three of the following character types: letters, digits, spaces, and special characters `-!@#$ %^&*()-_=+\|[{}]:'",<.>/? and does not start with a hyphen (-).
    • Cannot be a weak password. To check whether a password is weak, enter it in 5.
    Enter y when the following information is displayed: 
    Trust this certificate?

  4. Run the following command to create a client truststore certificate with the CA: 

    keytool -keystore client.truststore.jks -alias CARoot -import -file ca-cert

    Enter the client truststore password as prompted and record the password. This password is the value of ssl.truststore.password in the configuration file used by the client to connect to the Kafka instance.

    The password must meet the following requirements:

    • Contains 8 to 32 characters.
    • Contains at least three of the following character types: letters, digits, spaces, and special characters `-!@#$ %^&*()-_=+\|[{}]:'",<.>/? and does not start with a hyphen (-).
    • Cannot be a weak password. To check whether a password is weak, enter it in 5.
    Enter y when the following information is displayed: 
    Trust this certificate?

  5. Sign the server certificate.

    1. Export the server certificate server.cert-file. 
      keytool -keystore server.keystore.jks -alias localhost -certreq -file server.cert-file

      Enter the keystore password set in 1 as prompted.

    2. Sign the server certificate with the CA. 
      openssl x509 -req -CA ca-cert -CAkey ca-key -in server.cert-file -out server.cert-signed -days 3650 -CAcreateserial

      Enter the PEM password set in 2 as prompted.

    3. Import the CA certificate to the server keystore. 
      keytool -keystore server.keystore.jks -alias CARoot -import -file ca-cert

      Enter the keystore password set in 1 as prompted.

      Enter y when the following information is displayed: 
      Trust this certificate?
    4. Import the signed server certificate to the server keystore. 
      keytool -keystore server.keystore.jks -alias localhost -import -file server.cert-signed

      Enter the keystore password set in 1 as prompted.

  6. Export the server.keystore.jks, server.truststore.jks, and client.truststore.jks certificates to the local PC.

    The server.keystore.jks and server.truststore.jks files are used to replace the keystore and truststore files in subsequent step Replacing a Certificate. Store client.truststore.jks in a specific location on the client. Record the storage path and it is the value of ssl.truststore.location in the configuration file used by the client to connect to the Kafka instance.
    Figure 1 Certificate directory

Step 2: Replacing a Certificate

  1. Log in to the Kafka console.
  2. Click in the upper left corner to select the region where your instance is located.
  3. Click the desired instance to view its details.
  4. In the Connection area, click Re-upload next to SSL Certificate.

    Figure 2 Connection information

  5. Set the parameters for replacing the SSL certificate by referring to Table 1.

    Figure 3 Replacing the SSL certificate
    Table 1 Parameters for replacing the SSL certificate

    Parameter

    Description

    Key Password

    Enter the keystore password set in 1.

    Keystore Password

    Enter the keystore password set in 1.

    Keystore File

    Import the server.keystore.jks certificate.

    Truststore Password

    Enter the server truststore password set in 3.

    Truststore File

    Import the server.truststore.jks certificate.

  6. Click OK.
  7. Click OK.

    On the Instance > Background Tasks page, if the certificate replacement task is Successful, the certificate is successfully replaced.

    After the original certificate is successfully replaced, you will download the certificate provided by DMS for Kafka rather than your own certificate by clicking Download on the Basic Information tab page.

Step 3: Modifying Client Configuration Files

After a certificate is replaced, modify the ssl.truststore.location and ssl.truststore.password parameters in the consumer.properties and producer.properties files on the client, respectively.

security.protocol=SASL_SSL
ssl.truststore.location=/opt/kafka_2.12-2.7.2/config/client.truststore.jks
ssl.truststore.password=axxxb
ssl.endpoint.identification.algorithm=
Table 2 Configuration file parameters

Parameter

Description

ssl.truststore.location

Path for storing the client.truststore.jks certificate

ssl.truststore.password

truststore password of the client certificate

ssl.endpoint.identification.algorithm

Whether to verify the certificate domain name This parameter must be left blank, which indicates disabling domain name verification.

Step 4: Verifying the Certificate

Produce and consume messages by referring to Connecting to Kafka Using the Client (Ciphertext Access). The new certificate takes effect if the operation is successful.

(Optional) Making and Replacing an SSL Certificate with Domain Name Verification Enabled

When certificate domain name verification is enabled, changing the instance address may cause a client to fail to connect to the instance. The changing operations include changing the private network address to a public network address; changing the public network address to a private network address; and increasing the number of brokers.

  1. Log in to the Linux server and run the following command to generate the server.keystore.jks certificate: 

    keytool -genkey -keystore server.keystore.jks -alias localhost -validity 3650 -keyalg RSA -ext SAN=IP:xxx.xxx.xx.xx,IP:xxx.xxx.xx.xx,IP:xxx.xxx.xx.xx

    The IP address is the IP address in the Kafka instance connection address, which is obtained from Prerequisites. Note: The connection address of the Kafka instance contains IP address: Port, for example, 192.168.10.10:9093,192.168.10.11:9093,192.168.10.12:9093. The preceding command should be modified as follows:

    keytool -genkey -keystore server.keystore.jks -alias localhost -validity 3650 -keyalg RSA -ext SAN=IP:192.168.10.10,IP:192.168.10.11,IP:192.168.10.12
    1. Enter the keystore password as prompted and record the password for later use.

      The password must meet the following requirements:

      • Contains 8 to 32 characters.
      • Contains at least three of the following character types: letters, digits, spaces, and special characters `-!@#$ %^&*()-_=+\|[{}]:'",<.>/? and does not start with a hyphen (-).
      • Cannot be a weak password. To check whether a password is weak, enter it in 5.
    2. Enter the information about the certificate owner as prompted, such as the name, company, organization, city, and country or region. 
      [root@ecs-kafka ~]# keytool -genkey -keystore server.keystore.jks -alias localhost -validity 3650 -keyalg RSA -ext SAN=IP:192.168.10.10,IP:192.168.10.11,IP:192.168.10.12
Enter keystore password:  
Re-enter new password: 
What is your first and last name?
  [Unknown]:  Tom
What is the name of your organizational unit?
  [Unknown]:  test
What is the name of your organization?
  [Unknown]:  test01
What is the name of your City or Locality?
  [Unknown]:  nj
What is the name of your State or Province?
  [Unknown]:  js
What is the two-letter country code for this unit?
  [Unknown]:  xx
Is CN=Tom, OU=test, O=test01, L=nj, ST=js, C=xx correct?
  [no]:  y
    3. Press Enter as prompted to set the key password to the same as the keystore password. 
      Enter key password for <localhost>
        (RETURN if same as keystore password):

  2. Run the following command to generate a CA private key: 

    openssl genrsa -out ca.key 2048

  3. Run the following command to generate a CA certificate: 

    openssl req -new -x509 -key ca.key -out ca.crt -days 3650 -subj "/CN=KafkaTestCA"

  4. Run the following command to generate a server certificate: 

    keytool -keystore server.keystore.jks -alias localhost -certreq -file server.csr -storepass xxx

    storepass indicates the password of the keystore. Enter the keystore password set in 1.a.

  5. Use the CA to sign the server certificate.

    1. Run the following command to create a sans.ext file: 
      touch sans.ext
    2. Run the following command to edit the sans.ext file and add the following content: 
      vim sans.ext

      Add the following content:

      subjectAltName=IP:xxx.xxx.xx.xx,IP:xxx.xxx.xx.xx,IP:xxx.xxx.xx.xx

      The IP address is the IP address in the Kafka instance connection address, which is obtained from Prerequisites.

    3. Run the following command to use the CA to sign the server certificate: 
      openssl x509 -req -CA ca.crt -CAkey ca.key -in server.csr -out server.crt -days 3650 -CAcreateserial -extfile sans.ext
      The returned information is as follows: 
      [root@ecs-kafka ~]# openssl x509 -req -CA ca.crt -CAkey ca.key -in server.csr -out server.crt -days 3650 -CAcreateserial -extfile sans.ext
Signature ok
subject=C=xx, ST=js, L=nj, O=test01, OU=test, CN=Tom
Getting CA Private Key

  6. Import the CA certificate to the server keystore. 

    keytool -keystore server.keystore.jks -alias CARoot -import -file ca.crt -storepass xxx -noprompt

    storepass indicates the password of the keystore. Enter the keystore password set in 1.a.

    The returned information is as follows: 
    [root@ecs-kafka ~]# keytool -keystore server.keystore.jks -alias CARoot -import -file ca.crt -storepass xxx -noprompt
Certificate was added to keystore

  7. Import the server certificate to the server keystore. 

    keytool -keystore server.keystore.jks -alias localhost -import -file server.crt -storepass xxx -noprompt

    storepass indicates the password of the keystore. Enter the keystore password set in 1.a.

    The returned information is as follows:

    [root@ecs-kafka ~]# keytool -keystore server.keystore.jks -alias localhost -import -file server.crt -storepass xxx -noprompt
Certificate reply was installed in keystore

  8. Create a server truststore certificate with the CA. 

    keytool -keystore server.truststore.jks -alias CARoot -import -file ca.crt -storepass xxx -noprompt

    storepass is the password of the server truststore certificate. Set the password by complying with the following requirements and record it for later use.

    The password must meet the following requirements:

    • Contains 8 to 32 characters.
    • Contains at least three of the following character types: letters, digits, spaces, and special characters `-!@#$ %^&*()-_=+\|[{}]:'",<.>/? and does not start with a hyphen (-).
    • Cannot be a weak password. To check whether a password is weak, enter it in 5.
    The returned information is as follows: 
    [root@ecs-kafka ~]# keytool -keystore server.truststore.jks -alias CARoot -import -file ca.crt -storepass xxx -noprompt
Certificate was added to keystore

  9. Create a client truststore certificate with the CA. 

    keytool -keystore client.truststore.jks -alias CARoot -import -file ca.crt -storepass xxx -noprompt

    storepass is the password of the client truststore certificate. Set the password by complying with the following requirements and record it for later use.

    The password must meet the following requirements:

    • Contains 8 to 32 characters.
    • Contains at least three of the following character types: letters, digits, spaces, and special characters `-!@#$ %^&*()-_=+\|[{}]:'",<.>/? and does not start with a hyphen (-).
    • Cannot be a weak password. To check whether a password is weak, enter it in 5.
    The returned information is as follows: 
    [root@ecs-kafka ~]# keytool -keystore client.truststore.jks -alias CARoot -import -file ca.crt -storepass xxx -noprompt
Certificate was added to keystore

  10. Export the server.keystore.jks, server.truststore.jks, and client.truststore.jks certificates to the local PC.

    The server.keystore.jks and server.truststore.jks files are used to replace the keystore and truststore files in subsequent step Replacing a Certificate. Store client.truststore.jks in a specific location on the client. Record the storage path and it is the value of ssl.truststore.location in the configuration file used by the client to connect to the Kafka instance.

  11. Replace the SSL certificate on the Kafka console by referring to Step 2: Replacing a Certificate.

    Table 3 Parameters for replacing the SSL certificate

    Parameter

    Description

    Key Password

    Enter the keystore password set in 1.a.

    Keystore Password

    Enter the keystore password set in 1.a.

    Keystore File

    Import the server.keystore.jks certificate.

    Truststore Password

    Enter the server truststore password set in 8.

    Truststore File

    Import the server.truststore.jks certificate.

  12. Modify the client configuration file.

    After a certificate is replaced, modify the ssl.truststore.location and ssl.truststore.password parameters in the consumer.properties and producer.properties files on the client, respectively. 
    security.protocol=SASL_SSL
ssl.truststore.location=/opt/kafka_2.12-2.7.2/config/client.truststore.jks
ssl.truststore.password=axxxb
ssl.endpoint.identification.algorithm=https
    Table 4 Configuration file parameters

    Parameter

    Description

    ssl.truststore.location

    Path for storing the client.truststore.jks certificate

    ssl.truststore.password

    truststore password of the client certificate

    ssl.endpoint.identification.algorithm

    Certificate domain name verification setting. To enable it, set to "https".

  13. Check whether the certificate has taken effect.

    Produce and consume messages by referring to Connecting to Kafka Using the Client (Ciphertext Access). The new certificate takes effect if the operation is successful.

Parent Topic: Configuring Kafka Access Control