openldap2/ppolicy-check-password.5

.\"/* 
.\" * All rights reserved
.\" * Copyright (c) 2016 SUSE LINUX GmbH, Nuernberg, Germany.
.\" * Authors: Howard Guo <hguo@suse.com>
.\" *
.\" * This program is free software; you can redistribute it and/or
.\" * modify it under the terms of the GNU General Public License
.\" * as published by the Free Software Foundation; either version 2
.\" * of the License, or (at your option) any later version.
.\" *
.\" * This program is distributed in the hope that it will be useful,
.\" * but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" * GNU General Public License for more details.
.\" */
.\"
.TH PPOLICY-CHECK-PASSWORD 5 "2016/02/18" "OpenLDAP password quality check"
.SH NAME
ppolicy\-check\-password \- Password quality checker for OpenLDAP ppolicy overlay
.SH SYNOPSIS
pwdCheckModule ppolicy-check-password.so
.SH DESCRIPTION
ppolicy\-check\-password is an implementation of password quality check module, it can be plugged into OpenLDAP
.BR slapo\-ppolicy (5)
overlay to enforce organisational password strength policies for password-change operations.

.SH PREREQUISITES
In order to use the module, you should enable and configure
.BR slapo\-ppolicy (5)
overlay on the OpenLDAP server. You may use the following example to enable ppolicy overlay:
.HP 4
Enable ppolicy overlay

To enable ppolicy overlay on the server using static configuration file
.BR slapd.conf (5)
, first enable ppolicy schema by adding line:

.br
include /etc/openldap/schema/ppolicy.schema

and then append the following lines to the database definition in which password policy should be enforced:

.br
overlay ppolicy
.br
ppolicy_default "cn=PolicyContainer,dc=my-domain,dc=com"

Save slapd.conf and (re)start OpenLDAP server.

If you use cn=config (online configuration) instead of static configuration file, add the schema /etc/openldap/schema/ppolicy.ldif to cn=schema,cn=config, then enable ppolicy overlay in olcDatabase.
.LP

.HP 4
Create ppolicy container entry

The ppolicy container entry stores attributes that describe the password policy in detail, create the entry with

.BR ldapadd (1)
:

.br
dn: cn=PolicyContainer,dc=my-domain,dc=com
.br
cn: PolicyContainer
.br
objectClass: pwdPolicy
.br
objectClass: person
.br
objectClass: top
.br
pwdAllowUserChange: TRUE
.br
pwdAttribute: userPassword
.br
pwdCheckQuality: 2
.br
pwdExpireWarning: 600
.br
pwdFailureCountInterval: 
.br
pwdGraceAuthNLimit: 5
.br
pwdInHistory: 5
.br
pwdLockout: TRUE
.br
pwdLockoutDuration: 0
.br
pwdMaxAge: 0
.br
pwdMaxFailure: 
.br
pwdMinAge: 0
.br
pwdMinLength: 5
.br
pwdMustChange: FALSE
.br
pwdSafeModify: FALSE
.br
sn: dummy value
.br

The password policy becomes effective immediately, there is no need to restart OpenLDAP server.
.LP

.HP 4
Enable ppolicy-check-password.so module

Modify the ppolicy container entry with
.BR ldapmodify (1)
:

.br
dn: cn=PolicyContainer,dc=my-domain,dc=com
.br
changeType: modify
.br
add: objectClass
.br
objectClass: pwdPolicyChecker
.br
\-
.br
add: pwdCheckModule
.br
pwdCheckModule: ppolicy-check-password.so

The password check module becomes effective immediately, there is no need to restart OpenLDAP server.
.LP

.SH CONFIGURATION

The password check module reads configuration parameters from
.B /etc/openldap/check_password.conf

Edits made to the configuration file become effective immediately, there is no need to restart OpenLDAP server.

List of parameters:
.TP
.BI use_cracklib \ 1|0
CrackLib is a library for checking that a password is not easily crackable, making sure that the password is not based on simple patterns or dictionary words. If the parameter is set to 1, cracklib will be involved and new passwords must pass cracklib quality check in addition to all other policies such as min_points
.TP
.BI min_points \ <integer>
The parameter holds an integer value in between 0 and 4. The value denotes "quality points" that a password must acquire in order to pass the check. Usage of each character class awards one quality point. If the parameeter is set to 0, the check is disabled.

The character classes are: upper case letters, lower case letters, numeric digits, punctuations.
.TP
.BI min_upper \ <integer>
The minimal number of upper case characters a password must contain. If the parameter is set to 0, the check is disabled.
.TP
.BI min_lower \ <integer>
The minimal number of lower case characters a password must contain. If the parameter is set to 0, the check is disabled.
.TP
.BI min_digit \ <integer>
The minimal number of numeric digit characters a password must contain. If the parameter is set to 0, the check is disabled.
.TP
.BI min_punct \ <integer>
The minimal number of punctuation characters a password must contain. If the parameter is set to 0, the check is disabled.
.TP
.BI max_consecutive_per_class \ <integer>
The maximum number of characters from each character class that may appear consecutively. If the parameter is set to 0, the check is disabled.

.SH USAGE
After the module is enabled, the OpenLDAP server will invoke the password checker module on every user password change, the new user password must pass all quality checks before it is accepted. If the new password does not pass quality checks, the detailed reason will be logged on the OpenLDAP server, and the client will receive a Constraint Violation and a generic error message "Password fails quality checking policy" \- the lack of details is by design.

If the password change is carried out by RootDN, password checker module will not enforce the quality checks, and any password is acceptable.

.SH FILES
.TP
/etc/openldap/check_password.conf
Define the password strength policy.
.SH SEE ALSO
.BR slapd.conf (5),
.BR slapd\-config (5),
.BR slapd (8),
.BR slapo\-ppolicy (5)

.SH ACKNOWLEDGEMENTS
.P
The module was originally authored by LTB-project (ltb\-project.org), and further maintained by Onyx Point (onyxpoint.com).