Enabling TLS Protocol Connection to the ActiveMQ (v9.0.0)

Owned by David P (Deactivated)
Last updated: Jun 02, 2021 by Eliezer Basner (Unlicensed)
4 min read

TLS (Transport Layer Security) and SSL (Secure Sockets Layer) are cryptographic protocols designed to provide communication security over networks. Websites can use TLS to secure all communications between their servers and web browsers. TLS aims primarily to provide privacy and data integrity between two or more communicating applications.

ActiveMQ supports secure communication channels. The most common way to establish a secure communication channel is to associate a certificate with the target (broker). This section provides instructions on how to enable the TLS protocol connection to the ActiveMQ. The instructions include links to topics that are directly related to this procedure.

These instructions define the procedure for enabling the TLS protocol connection to the ActiveMQ.

Contents

SAST ActiveMQ Clients

The following services operate as ActiveMQ clients:

  • Access Control (IIS)

  • Engine Service

  • Scans Manager Service

  • Results Service

Configuring ActiveMQ Server Certificates

In some instances, ActiveMQ servers are also referred to as ActiveMQ brokers.

Server certificates can be configured in several ways. For the purposes of this guide, we provide examples for a self-signed certificate and a CA certificate.

Self-Signed Certificate

Self-signed certificates are used for testing and development.

 1. Navigate to the Checkmarx ActiveMQ\conf folder.

 2. In the Search field, enter cmd and execute the relevant command according to the respective scenarios listed below.

 3. Create the server certificate (self-signed) as illustrated:



During the process of self-signed certification creation, you are prompted for the following credentials and information:

  • Password. Required, the key store password.
  • Your first and last name, which is going to be your domain name (FQDN). Required by the ActiveMQ URI for the certificate to operate.
  • Additional organizational information. Optional
  • Certificate Password. Required, it is recommended to use the same password as for the key store password.

You can use the wildcard * for subdomains, for example *.cxdomain.com


     

 4. Export the server certificate.

The certificate must be available to every client.

 5. Install the desired certificate on every client as explained in the relevant section below.

CA Certificate

CA certificates are used for production. 

CA Certificates must be in .pfx format.

 1. Navigate to the Checkmarx ActiveMQ\conf folder.

 2. Enter cmd in the Search field and execute the relevant command according to the respective scenarios listed below:

 3. Create a key store from an existing CA certificate (cert.pfx). 


 4. Copy the CA certificate to every client.

 5. Install the desired certificate on every client as explained in the relevant section below.

Installing the Certificate

This section explains how to install the respective certificate under Windows: 

  • Copy the certificate to the client and then double-click it or use the Certificate Management tool (certmgr.msc) to install.

Certificates must be installed in the Trusted Root Certificate Store on every client host.

Enabling TLS Protocol Connection

The TLS protocol connection to the ActiveMQ can be enabled by first configuring the ActiveMQ server via a configuration file (activemq.xml) and then updating the ActiveMQ client configuration via the database (CxDB).


Configuring the ActiveMQ Server

Once the CxSAST environment has been installed and fully configured, do the following:, 

 1. Navigate to the Checkmarx ActiveMQ\conf folder and open activemq.xml.

 2. Edit the <sslContext> tag accordingly, using either a KS or a PFX file, as shown in the following examples:


or

2. Edit the <transportConnectors> tag accordingly:


The transportConnector defines the port that will be used for ActiveMQ communications.
This port will be required for the ActiveMQ URI.


It is required to use TLS v1.2 and relevant Cipher suites:

ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-CHACHA20-POLY1305, ECDHE-RSA-CHACHA20-POLY1305,DHE-RSA-AES128-GCM-SHA256, DHE-RSA-AES256-GCM-SHA384

 3. Navigate to C:\Program Files\Checkmarx\Checkmarx ActiveMQ\bin and open a command line window (cmd instance) for that folder.

 4. Use the ActiveMQ encryption utility to encrypt your password by entering the following in the command line:

activemq encrypt --password CxManager --input CxExamplePassword

Note: The password argument is related to the “ACTIVEMQ_ENCRYPTION_PASSWORD” environment variable, which is by default “CxManager”.

 5. Copy the encrypted text (yellow fonts in the screen image below).

    

 6. Navigate to C:\Program Files\Checkmarx\Checkmarx ActiveMQ\conf and edit credentials-enc.properties.

 7. Add a new variable in the same format as the existing value to the text file with the encrypted text between the brackets, for example:




High Availability Environment

if High Availability cluster setup is used, copy the following files to every server:

  • activemq.xml
  • server.ks
  • credentials-enc.properties

Restart each relevant ActiveMQ service on the respective server after copying all the files.

ActiveMQ Connection URI

  1. For TLS connections, use ssl as the protocol prefix of the URI. The URI format is as follows:


  2. Define additional connection parameters as follows:


TLS Server Example


HA TLS Example

Refer to the High Availability user guide at Configuring ActiveMQ for High Availability Environments (v9.0.0).



  • The parameter value must be ULR encoded

  • Disabling server name verification is not recommended.

  • High Availability setup broker certificate must be deployed to all clients in a similar environment.

  • For advanced URI configuration options please refer to ActiveMQ documentation: https://activemq.apache.org/activemq-connection-uris

Configuring ActiveMQ Clients

To configure ActiveMQ clients, do the following:

  1. Open MS SQL Server Management Studio.

  2. Connect to the SQL server.

  3. Navigate to Databases > CxDB > Tables.

     

 4. Expand the Tables repository to view its content and navigate to dbo.CxComponentConfiguration .

 5. Right-click dbo.CxComponentConfiguration and then select Edit Rows.

 6. In the ActiveMessageQueueURL key field, enter the ActiveMQ URI.

 7. In the Tables repository, right-click Config.CxEngineConfigurationKeysMeta and select Edit Rows.

 8. In the ACTIVE_MESSAGE_QUEUE_URL key field, enter the ActiveMQ URI:


These steps can be performed by using the following DB TSQL script:
Replace <host.domain> with your relevant value:

DECLARE @AmqString varchar(1000)
SET @AmqString = 'ssl://<host.domain>:61617'
Update [CxDB].[dbo].CxComponentConfiguration
set [Value] = @AmqString
where [Key] = 'ActiveMessageQueueURL'
Update [CxDB].[Config].[CxEngineConfigurationKeysMeta]
set [DefaultValue] = @AmqString
where [KeyName] = 'ACTIVE_MESSAGE_QUEUE_URL'

 9. Restart the following services for the changes to take effect:

  • Scans Manager Service

  • Results Service

  • Access Control (IIS)

Configuring M&O with ActiveMQ TLS

In the C:\Program Files\Checkmarx\Checkmarx Risk Management\AMQclient folder, create the mnoTrustStore.ts file. The Client trust store file contains the certificate of the server. This file is mandatory and must always be available in the AMQclient folder to configure AMQ SSL. The Client keystore file is only needed in case of mutual TLS.

To create the mnoTrustStore.ts file:

  1. Open the Windows command line interface (cmd)

  2. Enter copy client.ts mnoTrustStore.ts

  3. Create a file called ssl_for_amq.properties with the password of the client truststore. The file content looks as follows:



  • TRUST_STORE_PASSWORD - Mandatory and must always be set.

  • AMQ_BROKER_URL - Not mandatory in this file. If supplied, it is used by MnO instead of the URL in the CxComponentConfiguration table. The URL must not contain certificate information like the broker URL in CxComponentConfiguration since this information is supplied by the passwords in ssl_for_amq.properties and mnoTrustStore.ts.

  • The file ssl_for_amq.properties is relevant for AMQ SSL configuration only.


  • When using self-signed certificate, the URL must contain the name of the domain (FQDN) used when creating the server certificate.
  • The values are encrypted after restarting CXARM.

.