TLS Configuration

This section introduces TLS configuration in RocketMQ.

1 Generate Certificate Files

Users can generate certificate files using OpenSSL. It is suggested to generate files in Linux.

1.1 Generate ca.pem

openssl req -newkey rsa:2048 -keyout ca_rsa_private.pem -x509 -days 365 -out ca.pem

1.2 Generate server.csr

openssl req -newkey rsa:2048 -keyout server_rsa.key  -out server.csr

1.3 Generate server.pem

openssl x509 -req -days 365 -in server.csr -CA ca.pem -CAkey ca_rsa_private.pem -CAcreateserial -out server.pem

1.4 Generate client.csr

openssl req -newkey rsa:2048 -keyout client_rsa.key -out client.csr

1.5 Generate client.pem

openssl x509 -req -days 365 -in client.csr -CA ca.pem -CAkey ca_rsa_private.pem -CAcreateserial -out client.pem

1.6 Generate server.key

openssl pkcs8 -topk8 -v1 PBE-SHA1-RC4-128 -in  server_rsa.key -out server.key

1.7 Generate client.key

openssl pkcs8 -topk8 -v1 PBE-SHA1-RC4-128 -in client_rsa.key -out client.key

2 Create tls.properties

Create tls.properties, correctly configure the path and password of the generated certificates.

# The flag to determine whether use test mode when initialize TLS context. default is true
tls.test.mode.enable=false                     
# Indicates how SSL engine respect to client authentication, default is none
tls.server.need.client.auth=require   
# The store path of server-side private key
tls.server.keyPath=/opt/certFiles/server.key
# The password of the server-side private key
tls.server.keyPassword=123456
# The store path of server-side X.509 certificate chain in PEM format
tls.server.certPath=/opt/certFiles/server.pem
# To determine whether verify the client endpoint's certificate strictly. default is false
tls.server.authClient=false
# The store path of trusted certificates for verifying the client endpoint's certificate
tls.server.trustCertPath=/opt/certFiles/ca.pem

If you need to authenticate the client connection, you also need to add the following content to the file.

# The store path of client-side private key 
tls.client.keyPath=/opt/certFiles/client.key
# The password of the client-side private key
tls.client.keyPassword=123456
# The store path of client-side X.509 certificate chain in PEM format
tls.client.certPath=/opt/certFiles/client.pem
# To determine whether verify the server endpoint's certificate strictly
tls.client.authServer=false                    
# The store path of trusted certificates for verifying the server endpoint's certificate
tls.client.trustCertPath=/opt/certFiles/ca.pem

3 Update Rocketmq JVM parameters

Edit the configuration file under the rocketmq/bin path to make tls.properties configurations take effect.

The value of “tls.config.file” needs to be replaced by the file path created in step 2.

3.1 Edit runserver.sh

Add following content in JAVA_OPT:

JAVA_OPT="${JAVA_OPT} -Dtls.server.mode=enforcing -Dtls.config.file=/opt/rocketmq-4.9.3/conf/tls.properties"

3.2 Edit runbroker.sh

Add following content in JAVA_OPT:

JAVA_OPT="${JAVA_OPT} -Dorg.apache.rocketmq.remoting.ssl.mode=enforcing -Dtls.config.file=/opt/rocketmq-4.9.3/conf/tls.properties  -Dtls.enable=true"

4 Client connection

Create tlsclient.properties using by client. Add following content:

# The store path of client-side private key 
tls.client.keyPath=/opt/certFiles/client.key
# The password of the client-side private key
tls.client.keyPassword=123456
# The store path of client-side X.509 certificate chain in PEM format
tls.client.certPath=/opt/certFiles/client.pem               
# The store path of trusted certificates for verifying the server endpoint's certificate
tls.client.trustCertPath=/opt/certFiles/ca.pem

Add following parameters in JVM. The value of “tls.config.file” needs to be replaced by the file path we created:

-Dtls.client.authServer=true -Dtls.enable=true  -Dtls.test.mode.enable=false  -Dtls.config.file=/opt/certs/tlsclient.properties

Enable TLS for client like the following:

public class ExampleProducer {
    public static void main(String[] args) throws Exception {
        DefaultMQProducer producer = new DefaultMQProducer("please_rename_unique_group_name");
        //setUseTLS should be true
        producer.setUseTLS(true);
        producer.start();

        // Send messages as usual.
        producer.shutdown();
    }
}

5 Proxy TLS Configuration

RocketMQ Proxy uses rmq-proxy.json (not tls.properties) for TLS configuration. The proxy supports TLS for both its gRPC and Remoting protocol endpoints.

5.1 Configure rmq-proxy.json

Add TLS-related fields to distribution/conf/rmq-proxy.json:

{
  "rocketMQClusterName": "DefaultCluster",
  "tlsTestModeEnable": false,
  "tlsKeyPath": "/opt/certFiles/server.key",
  "tlsKeyPassword": "123456",
  "tlsCertPath": "/opt/certFiles/server.pem"
}

Field	Type	Default	Description
`tlsTestModeEnable`	boolean	`true`	Use self-signed certificates for testing. Set to `false` for production.
`tlsKeyPath`	string	`${PROXY_HOME}/conf/tls/rocketmq.key`	Path to the server private key file (PKCS#8 PEM format).
`tlsKeyPassword`	string	`""`	Password for the encrypted private key. Leave empty if the key is not encrypted.
`tlsCertPath`	string	`${PROXY_HOME}/conf/tls/rocketmq.crt`	Path to the server certificate chain file (X.509 PEM format).
`tlsCertWatchIntervalMs`	int	`3600000`	Interval in milliseconds to check for certificate file changes.

5.2 Update Proxy JVM parameters

Edit runproxy.sh (or the script that launches the proxy) to enable TLS enforcing mode:

JAVA_OPT="${JAVA_OPT} -Dtls.server.mode=enforcing"

The three available TLS modes are:

disabled - TLS is not supported; incoming TLS handshakes are rejected.
permissive - TLS is optional; the proxy accepts both TLS and non-TLS connections.
enforcing - TLS is required; non-TLS connections are rejected.