# Securing RabbitMQ with TLS/SSL

This document describes the steps to enable TLS/SSL security on the RabbitMQ server running on Windows based on the installation performed with the Powershell script provided by Matrix42 on the Marketplace. An adaption to other installations and configuration is possible but not part of this document. Please see the official RabbitMQ documentation for individual configurations.

## Introduction

RabbitMQ is a central 3rd party component in the Matrix42 SUEM product which allows a fast and reliable communication of the core products and the Digital Workspace Platform (DWP). The standard installation uses an unencrypted transfer of the messages and authentication to the broker. In order to use encrypted communication the server needs to be configured and all participants (DWP, Empirum, Silverback, EgoSecure Data Protection and eventually others) need to be adjusted to use the secured messaging protocol ampqs instead of ampq. Also the access to the RabbitMQ Management Console is restricted to use https with TLS enabled.

## Prerequisites

This guide assumes the following prerequisites are available:

## Step by step configuration

### Prepare the certificate used on the RabbitMQ server

RabbitMQ requires the certificate and the CA as PEM files.

1. Copy the certificate to the computer where OpenSSL is installed (i.E c:\openssl\certs\my-cert.dom.pfx)
2. Export the trusting CA certificate as PKCS including all certificates in the certification path

3. Copy the exported certificate to the computer where OpenSSL is installed (i.E c:\openssl\certs\ca-cert.P7B)
4. Convert the certificates to PEM by opening the OpenSSL shell. Run "openssl" in the folder where it is installed
1. pkcs7 -print_certs -inform der -in cert\alpha.p7b -out alpha.pem
2. pkcs12 -in cert\wildcard.imagoverum.pfx -nokeys -out public-imagoverum.pem -nodes
3. pkcs12 -in cert\wildcard.imagoverum.pfx -nocerts -out private-imagoverum.pem -nodes
5. Copy the PEM files to a location on the server which than needs to be secured. The service account which runs the RabbitMQ service needs to have read access to this.

Please make sure the PEM file with the private key are not exposed to anyone. Remove from temporay loction and set NTFS rights to only allow the service account (local system) read access.

### Create RabbitMQ configuration file

RabbitMQ uses an optional configuration file "rabbitmq.conf" where the SSL/TLS configuration is defined.

1. Create a new text file rabbitmq.conf in the program folder of RabbitMQ (i.e. C:\Program Files\RabbitMQ Server\rabbitmq_server-3.8.0\rabbitmq.conf)

listeners.ssl.default             = 5671 ssl_options.cacertfile           = c:/cert/alpha.pem ssl_options.certfile             = c:/cert/public-imagoverum.pem ssl_options.keyfile              = c:/cert/private-imagoverum.pem ssl_options.verify               = verify_peer ssl_options.fail_if_no_peer_cert = false listeners.tcp = none

management.ssl.port       = 15671 management.ssl.cacertfile = c:/cert/alpha.pem management.ssl.certfile   = c:/cert/public-imagoverum.pem management.ssl.keyfile    = c:/cert/private-imagoverum.pem

In this example alpha.pem is the CA certificate which is the certification path for the private-imagoverum.pem and public-imagoverum.pem based certificate.

This option "listeners.tcp = none" prevents the system to be exposed for not secured connections. Only ampqs sessions can be established.

### Reinstall the RabbitMQ Service

In order to use the just created rabbitmq.conf file the service needs to be reinstalled. Perform the following steps in the correct order.

1. Open a command window on the server where RabbitMQ is installed and change to the program sbin folder (i.e. cd C:\Program Files\RabbitMQ Server\rabbitmq_server-3.8.0\sbin). This folder contains several batch files. Make sure not to accidently use rabbitmq-server.bat instead of rabbitmq-service.bat.
2. Run the following commands one after the other:
1. rabbitmq-service.bat stop
2. rabbitmq-service.bat remove
3. rabbitmq-service.bat install
4. rabbitmq-service.bat start
3. Check the status of the server once all commands are performed without an error: rabbitmqctl.bat status
4. After each change of the rabbitmq.conf file the steps above need to be performed again.

The output shows something similar to this at the end:

Interface: [::], port: 25672, protocol: clustering, purpose: inter-node and CLI tool communication
Interface: [::], port: 5671, protocol: amqp/ssl, purpose: AMQP 0-9-1 and AMQP 1.0 over TLS
Interface: 0.0.0.0, port: 5671, protocol: amqp/ssl, purpose: AMQP 0-9-1 and AMQP 1.0 over TLS
Interface: [::], port: 15671, protocol: https, purpose: HTTP API over TLS (HTTPS)
Interface: 0.0.0.0, port: 15671, protocol: https, purpose: HTTP API over TLS (HTTPS)


If the state cannot be retrieved because of authentication issues the used Windows user might not be the same as the installation user of RabbitMQ and Erlang. Therefore the session cookie might not be correct. Copy the file .erlang.cookie from C:\Windows\System32\config\systemprofile to your users profile root (i.e. c:\users\username\)

The server now requires secured ampq. All existing connections will be rejected. For testing purposes the option "listeners.tcp = none" can be removed. This would allow secure and insecure connections.

### Configuration of the connected Clients

All RabbitMQ clients need to be reconfigured.

#### ESB Extension for UUX

2. Navigate to Integration -> Enterprise Service Bus -> Settings
3. Select the current configuration and Edit
4. Provide the connection string as defined before with ampqs instead of ampq (i.e. amqps://USER:PASSWORD@SERVER.COMPANY.COM/mx42)
5. Save (the updated setting will be used after the execution of the ESBAdapterActivation engine activation and can take up to 5 minutes)
6. The checkbox "Is Connected" in the settings list should be selected after refreshing the page

#### Empirum

1. Open DBUtil on the Empirum server
2. Select Install/Configure Services from the Actions menu
3. Select Empirum-ServiceBus
4. Change the connection string to ampqs instead of ampq (i.e. amqps://USER:PASSWORD@SERVER.COMPANY.COM/mx42)
5. Click "Apply"
6. Right-Click the Empirum-ServiceBus in the list and select Install
1. If the certificate is not working the servcie cannot be installed. Please check the Log for details (C:\ProgramData\Matrix42\Logs\Empirum ServiceBus Service)

#### Silverback

1. Logon to the Silverback Server with the "Settings" user
2. Select "Service Bus"
3. Change the connection string to ampqs instead of ampq (i.e. amqps://USER:PASSWORD@SERVER.COMPANY.COM/mx42)
4. Click "Save"

#### EgoSecure Data Protection

1. Open the AdminTool.exe in the EgoSecure program folder (i.e. C:\Program Files\EgoSecure\EgoSecure Server)
2. Change the connection string to ampqs instead of ampq (i.e. amqps://USER:PASSWORD@SERVER.COMPANY.COM/mx42)
3. Click "Save"

### Checking the secured connection

Verify that the console and all clients are able to connect to the server with TLS/SSL:

1. Open the RabbitMQ Management console in a browser on the server where RabbitMQ is installed (https://server.dom.com:15671)
2. Select "Connections"
3. The list shows all current connections
4. The column SSL / TLS indicates if the connection is secured. The dot needs to be solid.