pqMessenger: communication middleware for pqChecker

The plug-in of OpenLDAP directory server pqChecker,allows to control the passwords content robustness. It exposes, also, a Java compliant programming interface (API). This API allows you to read / modify the operating parameters of pqChecker programmatically. It allows, also, to broadcast the new values of passwords in real time.

The pqMessenger application is a software component that uses this pqChecker programming interface to allow it to communicate with a MoM that supports JMS. So, an application connected to the same MoM must be able to provide the functions:

View the operating settings of pqChecker
Modify these password strength settings
Broadcast, in real time, new values of modified passwords

To ensure the confidentiality of the data exchanged, mainly passwords, this communication is done within a TLS siphered tunnel.

The Security managemet application is able to read and change password quality settings through communication with pqChecker provided by the MoM - pqMessenger chain. For this purpose, this application must be able to communicate with the MoM used by the global system. This operating mechanism makes it possible to manage these settings through a simple interface and without any particular system constraint, such as the need for involving a system administrator

On the other hand, if the password broadcast feature is enabled in the pqChecker setup, this settings management application or another connected to the MoM, will be able to receive the new password values in real time as soon as they are modified. This allows to integrate a functionality of synchronization of these values with other systems. So, the real-time synchronization of the passwords can be ensured to LDAP servers of another kind ;-) like MS Active Directory or different systems like database servers.

pqMessenger is a free and opensource software. It is licensed under the GNU GPL v3+ license.

Latest stable version: 2.0.0

How does it works

pqMessenger operate between pqChecker and a MoM that supports the JMS protocol. It calls the three functions of pqChecker using the JNI gateway that it implements. On the other side it connects to the MoM. To exchange messages with the MoM, pqMessenger uses an address of type Topic which must be called: PwdChannel.

An application that synchronizes passwords with another system must subscribe (in the JMS meaning) to the Topic PwdChannel. Listening to this Topic, this application will receive in real time the new values of the passwords created or modified within the OpenLDAP server.

pqMessenger requires prior installation Java JRE 1.8 or above on the system. The single JAR file pqmessenger-x.x.jar contains the entire application. Deployment must be done on the same server as pqChecker. Launch parameters and two configuration files are required for the correct operation of the application.

The launch script provided pqmessenger.boot allows to correctly set the launch parameters
The application configuration file pqmessenger.yml contains the necessary operating parameters, including the connection parameters to the MoM. A template of this file is provided
The log configuration file log4j2.xml

All of these files are in the sys-resources/ source distribution folder.
Installation from binary packages installs these mandatory files and well sets them. The source distribution includes an installation script that performs this task on the target system. See How to install from source code for further details.

When deploying a cluster of OpenLDAP servers for scaling or high availability, simply connect all instances of pqMessenger (one per deployment node) to the same MoM. Each server will be identified by its fully qualified host name (FQN) that will accompany the messages exchanged with the MoM. Such deployment configuration ensures that all servers in the cluster are configured identically for password content each time this configuration is changed. It also ensures that the MoM receives all new password values regardless of the server used for its modification.

Operation testing

To be able to test pqMessenger it is necessary to have in addition to the installation of the application itself:

An OpenLDAP server installation + pqChecker plug-in on the same server machine
A functional installation of a MoM, e.g. Apache ActiveMQ Artemis
At least one valid person entry in the OpenLDAP server to test passwords broadcast
A way to send and receive messages from the MoM (Apache Artemis provided an optional interface that allows it)

When you have those prerequisites and become ready, set up:

The MoM:
- Create a Topic called PwdChannel and a test user who has read and write rights to this Topic.
- Set the MoM logs to a sufficient level to monitor the flow of messages
pqMessenger: customize the «pqmessenger.yml» file for the test

Parameter servers: a single server, set host and port to the values used for the MoM (e.g. localhost and 61614)
login and password parameters: set to the values of the MoM test user, see the MoM parameter setting above
activetls parameter: set to false to disable TLS and make the test easier to perform

pqMessenger logs: Set the log level to «debug» in the file «log4j2.xml»

The pqMessenger configuration files must be in the «/etc/ldap/pqchecker/» folder for a Debian compliant system and «/etc/openldap/pqchecker/» for a Redhat compliant system.

A test that include the entire functional features of the communication performed by pqMessenger will proceed as follows:

Start the MoM, then pqMessenger. Check the success of connection to the MoM in the pqmessenger logs: /var/log/pqmessenger/pqmessenger.log
Create a subscription to the PwdChannel Topic of the MoM
Send a message to read the passwords quality parameters and check the response message
Send a message to change the passwords quality parameters. Check that these parameters have actually been modified: contents of the pqparams.dat file
Modify the password of a person contained in the directory. Check in the MoM logs that the broadcast message for this password has been sent

Get and Install It

pqMessenger is free & opensource software. It's licensed under the GNU GPL v3+ license. There are binary installation packages for Debian/Ubuntu & RedHat/CentOS systems, to download from the download section of this website. The source code of the latest stable release is also available in the download section. The history of the source code is available to anonymous download on Bitbucket platform.

git clone https://bitbucket.org/ameddeb/pqmessenger.git

Installation from binary packages is available for Debian/Ubuntu & Redhat/CentOS and compliants systems. The installation procedure is done through the dpkg or rpm utility. The detailed instructions for the installation are given in the README file provided with the binary files. Especially:

sudo dpkg -i pqmessengerxxxxxxx.deb
sudo rpm -iv pqmessengerxxxxxxx.rpm # Install pqMessenger

sudo dpkg -r pqmessenger
sudo rpm -ev pqmessenger # Uninstall it

Security warning: Due to the sensitivity of the data accessed by this software component, never install a binary package whose origin is unknown.

Installation from the source code is available for any POSIX compliant system. The Java JDK 1.8+, the Maven utility and an active Internet connection are needed.

Download the source archive of the target version, or get them from the Git repository.

git tag # lists all the available stable releases
git checkout v2.0.0 # provides the sources of this stable version

The INSTALL file contains all the instructions to complete this operation. Especially:

mvn clean package # build pqMesenger
sudo ./pqmessenger-install.sh # allows pqMessenger installation
sudo ./pqmessenger-install.sh --uninstall # allows pqMessenger uninstallation