how to use tls message encryption-Scalable Open Financial Architecture(SOFAStack)-阿里云帮助中心

To ensure secure communication, message production and consumption must support Transport Layer Security (TLS) encryption. TLS is a widely recognized method for securing communications, which is critical for financial systems. SOFAMQ provides easy-to-use TLS encryption capabilities. This topic describes how to use TLS to encrypt messages.

Important

The certificate authority (CA) for the NameServer, broker, and client certificates must be the same.

Configure the NameServer

Prepare the environment.
Confirm that OpenSSL is installed on the NameServer. If it is not installed, you must install it. You can run the openssl version command to check the installation.
Generate certificates.
The following steps describe how to generate certificates using OpenSSL:
Note
Enter a password when prompted by the following commands. This example uses 123456 for all passwords.
1. This topic describes two methods for installing a CA certificate:
  - Request a certificate from a dedicated CA. This is the recommended method.
  - Generate a self-signed root certificate.
    You can name the file ca.crt. The steps are as follows:
    1. Generate a CA key.
```
openssl genrsa -des3 -out ca.key 2048
```
    2. Generate a certificate signing request (CSR).
```
openssl req -new -out ca.csr -key ca.key -keyform PEM -subj "/C=CN/ST=Province/L=City/O=Organization/OU=Department/CN=domain_name_or_ip"
```
    3. Generate the self-signed root certificate.
```
openssl x509 -req -days 365 -in ca.csr -signkey ca.key -out ca.crt -CAcreateserial
```
2. Generate a public-private key pair for the application. The following example shows the command.
```
openssl genrsa -des3 -out server.pem 2048 
```
  You can name the file server.pem.
3. Generate a CSR. The following example shows the command.
```
openssl req -new -key server.pem -out server.csr -subj "/C=CN/ST=Province/L=City/O=Organization/OU=Department/CN=domain_name_or_ip"
```
  You can name the file server.csr.
4. Use the CA to sign and generate the application certificate. The following example shows the command.
```
openssl x509 -req -in server.csr -out server.crt -signkey server.pem -CA ca.crt -CAkey ca.key -days 365 -CAcreateserial
```
  You can name the file server.crt.

Configure the tls.properties configuration file. The parameters are described as follows:

Configuration item	Description	Example value	Recommended value
`tls.test.mode.enable`	Specifies whether to use test mode.	false	false
`tls.server.need.client.auth`	Specifies whether the server-side requests a client certificate.	optional	optional
`tls.server.keyPath`	The path of the server-side private key file.	`/home/admin/store/ca/server.pem`	-
`tls.server.keyPassword`	The access password for the server-side private key file.	123456	-
`tls.server.certPath`	The path of the server-side application certificate.	`/home/admin/store/ca/server.crt`	-
`tls.server.authClient`	Specifies whether the server-side authenticates the client.	true	true
`tls.server.trustCertPath`	The path of the server-side authentication certificate.	`/home/admin/store/ca/ca.crt`	-

Important

Place the certificates in the /home/admin/store folder. This folder is not typically cleared.

Set environment variables. The parameters are described as follows:

Configuration item

Description

Default value

tls.server.mode

The enumeration values are as follows:

Disable: Encryption is not supported.
Permissive: Compatible mode.
Enforcing: Forced encryption.

Permissive

tls.config.file

The path of the tls.properties file.

/etc/rocketmq/tls.properties

Note

If you use Yunyou for deployment, the path for the tls.properties file is fixed to /home/admin/store/ca/tls.properties.

Restart the NameServer.

Configure the broker

Prepare the environment.
Confirm that OpenSSL is installed on the broker. If it is not installed, you must install it. You can run the openssl version command to check the installation.
Generate certificates.
The following steps describe how to generate certificates using OpenSSL:
Note
Enter a password when prompted by the following commands. This example uses 123456 for all passwords.
1. You can install the CA certificate using one of the following two methods:
  - Request a certificate from a dedicated CA. This is the recommended method.
  - Generate a self-signed root certificate.
    You can name the file ca.crt. For information about the command to generate a root certificate, see NameServer self-signed root certificate.
2. Generate a server-side application public-private key pair. The following example shows the command.
```
openssl genrsa -des3 -out server.pem 2048 
```
  You can name the file server.pem.
3. Generate a server-side CSR. The following example shows the command.
```
openssl req -new -key server.pem -out server.csr -subj "/C=CN/ST=Province/L=City/O=Organization/OU=Department/CN=domain_name_or_ip"
```
  You can name the file server.csr.
4. Use the CA to sign and generate the server-side application certificate. The following example shows the command.
```
openssl x509 -req -in server.csr -out server.crt -signkey server.pem -CA ca.crt -CAkey ca.key -days 365 -CAcreateserial
```
  You can name the file server.crt.
5. Generate a client application public-private key pair. The following example shows the command.
```
openssl genrsa -des3 -out client.pem 2048    
```
  You can name the file client.pem.
6. Generate a client CSR. The following example shows the command.
```
openssl req -new -key client.pem -out client.csr -subj "/C=CN/ST=Province/L=City/O=Organization/OU=Department/CN=domain_name_or_ip"
```
  You can name the file client.csr.
7. Use the CA to sign and generate the client application certificate. The following example shows the command.
```
openssl x509 -req -in client.csr -out client.crt -signkey client.pem -CA ca.crt -CAkey ca.key -days 365 -CAcreateserial
```
  You can name the file client.crt.

Configure the tls.properties configuration file. The parameters are described as follows:

Configuration item	Description	Example value	Recommended value
`tls.test.mode.enable`	Specifies whether to use test mode.	false	false
`tls.server.need.client.auth`	Specifies whether the server-side requests a client certificate.	optional	optional
`tls.server.keyPath`	The path of the server-side private key file.	`/home/admin/store/ca/server.pem`	-
`tls.server.keyPassword`	The access password for the server-side private key file.	123456	-
`tls.server.certPath`	The path of the server-side application certificate.	`/home/admin/store/ca/server.crt`	-
`tls.server.authClient`	Specifies whether the server-side authenticates the client.	true	true
`tls.server.trustCertPath`	The path of the server-side authentication certificate.	`/home/admin/store/ca/ca.crt`	-
`tls.client.keyPath`	The path of the client private key file.	`/home/admin/store/ca/client.pem`	-
`tls.client.keyPassword`	The access password for the client private key file.	Abc123456	-
`tls.client.certPath`	The path of the client application certificate.	`/home/admin/store/ca/client.crt`	-
`tls.client.authServer`	Specifies whether the client authenticates the server-side.	true	true
`tls.client.trustCertPath`	The path of the client authentication certificate.	`/home/admin/store/ca/ca.crt`	-

Important

Place the certificates in the /home/admin/store folder. This folder is not typically cleared.

Set environment variables. The parameters are described as follows:

Configuration item

Description

Default value

tls.server.mode

The enumeration values are as follows:

Disable: Encryption is not supported.
Permissive: Compatible mode.
Enforcing: Forced encryption.

Permissive

tls.config.file

The path of the tls.properties file.

/etc/rocketmq/tls.properties

Note

If you use Yunyou for deployment, the path for the tls.properties file is fixed to /home/admin/store/ca/tls.properties.

Restart the broker.

Configure the client

Prepare the environment.
On the client, check the version of the sofamq-client JAR package to confirm that it is 3.1.6.1 or later.
Generate certificates.
The following steps describe how to generate certificates using OpenSSL:
Note
Enter a password when prompted by the following commands. This example uses 123456 for all passwords.
1. This topic describes two methods for installing the CA certificate:
  - Request a certificate from a dedicated CA. This is the recommended method.
  - Generate a self-signed root certificate.
    You can name the file ca.crt. For information about the command to generate a root certificate, see NameServer self-signed root certificate.
2. Generate an application public-private key pair. The following example shows the command.
```
openssl genrsa -des3 -out client.pem 2048    
```
  You can name the file client.pem.
3. Generate a CSR. The following example shows the command.
```
openssl req -new -key client.pem -out client.csr -subj "/C=CN/ST=Province/L=City/O=Organization/OU=Department/CN=domain_name_or_ip"
```
  You can name the file client.csr.
4. Use the CA to sign and generate the application certificate. The following example shows the command.
```
openssl x509 -req -in client.csr -out client.crt -signkey client.pem -CA ca.crt -CAkey ca.key -days 365 -CAcreateserial
```
  You can name the file client.crt.

Configure the tls.properties configuration file. The parameters are described as follows:

Configuration item	Description	Example value	Recommended value
`tls.test.mode.enable`	Specifies whether to use test mode.	false	false
`tls.client.keyPath`	The path of the client private key file.	`/home/admin/store/ca/client.pem`	-
`tls.client.keyPassword`	The access password for the client private key file.	123456	-
`tls.client.certPath`	The path of the client application certificate.	`/home/admin/store/ca/client.crt`	-
`tls.client.authServer`	Specifies whether the client authenticates the server-side.	true	true
`tls.client.trustCertPath`	The path of the client authentication certificate.	`/home/admin/store/ca/ca.crt`	-

Set environment variables. The parameters are described as follows:
Configuration item
Description
Default value
tls.config.file
The path of the tls.properties file.
/etc/rocketmq/tls.properties
tls.enable
Specifies whether to enable encryption on the client.
false
Restart the client.
Before you enable TLS on the client, confirm that TLS is enabled on the broker and NameServer.

Specify whether to use encryption when you create a producer or consumer instance. This step is optional.

The tls.enable environment variable specifies the default encryption setting. However, the API setting has a higher priority.

The following code provides an API example:

Properties properties = new Properties();
        
properties.setProperty(PropertyKeyConst.GROUP_ID, "GID_LFQ");
        
properties.setProperty(PropertyKeyConst.USE_TLS, "true"); // Enable encryption
        
Producer producer = AccessPoint.getAccessPoint().createProducer(properties);
        
producer.start();