OpenLDAP directory server with the ppolicy overlay allows to manage a powerful passwords policy. All aspects of this policy are directly supported by the ppolicy overlay, apart from the password content quality. The passwords content strength management is left to an external plug-in that must be a native shared library. The pqChecker component provides this feature. It allows to check the content of passwords, i.e:
- Number of required uppercase characters.
- Number of required lowercase characters.
- Number of required special characters (non-alphabetical characters).
- Number of required digits (0-9).
- Forbidden characters.
- Setting the passwords content quality programmatically.
- Real-time broadcast to other information systems of the modified passwords.
At each modification, or first password entry in the directory, pqChecker is involved. It receives the new value of this attribute and checks its compliance with the defined strength settings. At the end of this control, this value is accepted or rejected.
In addition, it is possible to read and modify the quality settings through pqMessenger component. This feature allows to manage these parameters without any particular system constraint (need to involve a system administrator). It even allows the use of a graphical user interface for this purpose.
Also, pqChecker allows to real-time broadcast the new password value, after its validation. This feature provides the ability to synchronize passwords stored in the OpenLDAP directory with other systems that use it like RDBMS, email servers and other LDAP servers. The passwords broadcasting isn't the default behavior of pqChecker. Default deactivated, It may be activated by simple setting.
pqChecker is a free and opensource software. It is licensed under the GNU GPL v3+ license.
The ppolicy overlay documentation provides information about the single function that the pqChecker plugin should contain. When OpenLDAP server with ppolicy overlay is installed:
...
int check_password (char *pPasswd, char **ppErrStr, Entry *pEntry);
...
The most important parameters are the received password and the value returned to the server.
- pPasswd contains the modified password.
- The value returned to the server, must be LDAP_SUCCESS (slapd.h) when password value is accepted, or any other value when it is rejected.
Password content check treatment is performed according settings stored in a text file named pqparams.dat. A system administrator can, manually, modify those settings to make a change of password content quality policy. More effectively, the modification of these settings may be done programmatically. This makes it possible to provide the feature of modifying them through a user-friendly interface. It also allows to avoid involving system administrator to achieve modifying settings. This is why the component provide two additional functions for reading and modifying the passwords strength settings.
When a password is validated, it can be broadcast to other systems, if this feature is enabled in the operating setting. The passwords are broadcast through the pqMessenger middleware.
pqMessenger uses the JNI interface to communicate with pqChecker on one side. On the other side, it communicates with a JMS server. It is an intermediary module between the native pqChecker plug-in and a Java application. An external application which provides the feature of modifying these settings through a user-friendly interface and a data broadcasting feature can use this message transmission chain in a very simple way.
The ppolicy overlay must be loaded and well configured, see the OpenLDAP administrator guide and password policy setting tutorial for further details. The following command, executed on the server, allows to verify this. The response must shows the ppolicy overlay loaded status ({x}ppolicy).
olcModuleLoad: {0}back_mdb
olcModuleLoad: {1}ppolicy
Especially, take care at 2 settings of this overlay. Assuming ppolicy settings DN is cn=ppolicy,dc=ldaptuto,dc=net, the following command allows to verify those settings values:
pwdCheckQuality: 2
pwdCheckModule: pqchecker.so
- pwdCheckModule must contain the name of the password checker plug-in, we use pqchecker.so
- pwdCheckQuality must contain the password control level, 3 values may be used:
| pwdCheckQuality | Meaning |
|---|---|
| 0 (default value) | No check is done, pqChecker is deactivated. |
| 1 | Default, the password is accepted. Especially, it's accepted when it's already encrypted or, for some reason, pqChecker does not work. The check is done only if pqChecker works and the password isn't encrypted. |
| 2 | Default, the password is rejected. Especially, it's rejected when it's already encrypted or, for some reason, pqChecker does not work. The check is done only if pqChecker works and the password isn't encrypted. |
To accept or reject passwords, pqChecker relies on settings stored in a text file: pqparams.dat. A single line of text contains all those settings. 6 fields constitute this line:
| Order (left to right) | Field | Length | Sequence | Range | Meaning of content |
|---|---|---|---|---|---|
| 1 | N| | 2 characters | 1,2 | 0| or 1| | 1| → Broadcasts passwords, 0| → Don't broadcasts |
| 2 | UU | 2 characters | 3,4 | 00 → 99 | Number of required uppercase characters |
| 3 | LL | 2 characters | 5,6 | 00 → 99 | Number of required lowercase characters |
| 4 | DD | 2 characters | 7,8 | 00 → 99 | Number of required digits |
| 5 | SS | 2 characters | 9,10 | 00 → 99 | Number of required special characters |
| 6 | The rest | indefinite | 11 → end of line | All characters | List of forbidden characters. This list may be empty |
Versions of pqChecker prior to 2.0 don't support field 1. This field act on passwords broadcasting. Only the last 5 fields are valid for these previous versions. Versions 2.0 and above support both formats.
pqChecker is deployed on the same machine than OpenLDAP server. Care must be taken, in particular, to the location of two files.
- pqchecker.so must be in the location defined by olcModulePath setting (modulepath in old style slapd.conf file).
- pqparams.dat must be in the location defined at build time of pqchecker.so library (PARAMDIR setting of configure script). See INSTALL file provided with sources and build from sources explanation for further details.
'Constraint violation', code 19
The server responds with a general error message. Further details may be shown in the server log file:
If the modified password is compliant with quality settings, no error message is chown and slapd log look like:
pqChecker 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 The Bitbucket platform.
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 rpm -iv pqcheckerxxxxxxx.rpm # Install pqChecker
sudo dpkg -r pqchecker
sudo rpm -ev pqchecker # Uninstall it
Security warning: Due to the sensitivity of the data accessed by this software component, never use a binary from untrusted third-party source.
Installation from the source code is available for any POSIX compliant system. The tools of software's build must be installed on the target system: The C compiler, Make utility and the system C header files. Due to use of JNI, the Java JDK 1.8+ is needed also.
Download the source archive of the target version, or get them from the Git repository.
git checkout v2.0.0 # provides the sources of this stable version
The INSTALL file contains all the instructions to complete this operation. Especially:
sudo make install # allows pqChecker installation
sudo make uninstall # allows its uninstallation