pwqcheck.1

.\" Copyright (c) 2009 Dmitry V. Levin
.\" All rights reserved.
.\" Copyright (c) 2000-2003,2005,2008,2010,2019,2020 Solar Designer
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd December 30, 2020
.Dt PWQCHECK 1
.Os "Openwall Project"
.Sh NAME
.Nm pwqcheck
.Nd Check passphrase quality
.Sh SYNOPSIS
.Nm Op Ar options
.Sh DESCRIPTION
The
.Nm
program checks passphrase quality using the libpasswdqc library.
By default, it expects to read 3 lines from standard input:
.Pp
.Bl -item -compact -offset indent
.It
first line is a new password,
.It
second line is an old password, and
.It
third line is either an existing account name or a
.Xr passwd 5
entry.
.El
.Pp
There are a number of supported options, which can be used to control the
.Nm
behavior.
.Pp
.Nm
prints
.Ar OK
on success.  Scripts invoking
.Nm
are suggested to check for both a zero exit status and the
.Ar OK
line.
.Sh OPTIONS
.Bl -tag -width Ds
.Sm off
.It Xo
.Cm min No =
.Ar N0 , N1 , N2 , N3 , N4
.Xc
.Sm on
.Pq default: min=disabled,24,11,8,7
The minimum allowed password lengths for different kinds of
passwords/passphrases.
The keyword
.Cm disabled
can be used to
disallow passwords of a given kind regardless of their length.
Each subsequent number is required to be no larger than the preceding
one.
.Pp
.Ar N0
is used for passwords consisting of characters from one character
class only.
The character classes are: digits, lower-case letters, upper-case
letters, and other characters.
There is also a special class for
.No non- Ns Tn ASCII
characters, which could not be classified, but are assumed to be non-digits.
.Pp
.Ar N1
is used for passwords consisting of characters from two character
classes that do not meet the requirements for a passphrase.
.Pp
.Ar N2
is used for passphrases.
Note that besides meeting this length requirement,
a passphrase must also consist of a sufficient number of words (see the
.Cm passphrase
option below).
.Pp
.Ar N3
and
.Ar N4
are used for passwords consisting of characters from three
and four character classes, respectively.
.Pp
When calculating the number of character classes, upper-case letters
used as the first character and digits used as the last character of a
password are not counted.
.Pp
In addition to being sufficiently long, passwords are required to
contain enough different characters for the character classes and
the minimum length they have been checked against.
.Pp
.It Cm max Ns = Ns Ar N
.Pq default: Cm max Ns = Ns 72
The maximum allowed password length.
This can be used to prevent users from setting passwords that may be
too long for some system services.
The value 8 is treated specially: if
.Cm max
is set to 8, passwords longer than 8 characters will not be rejected,
but will be truncated to 8 characters for the strength checks and the
user will be warned.
This is to be used with the traditional DES-based password hashes,
which truncate the password at 8 characters.
.Pp
It is important that you do set
.Cm max Ns = Ns 8
if you are using the traditional
hashes, or some weak passwords will pass the checks.
.It Cm passphrase Ns = Ns Ar N
.Pq default: Cm passphrase Ns = Ns 3
The number of words required for a passphrase.
.It Cm match Ns = Ns Ar N
.Pq default: Cm match Ns = Ns 4
The length of common substring required to conclude that a password is
at least partially based on information found in a character string,
or 0 to disable the substring search.
Note that the password will not be rejected once a weak substring is
found; it will instead be subjected to the usual strength requirements
with the weak substring partially discounted.
.Pp
The substring search is case-insensitive and is able to detect and
remove a common substring spelled backwards.
.It Xo
.Sm off
.Cm similar No = Cm permit | deny
.Sm on
.Xc
.Pq default: Cm similar Ns = Ns Cm deny
Whether a new password is allowed to be similar to the old one.
The passwords are considered to be similar when there is a sufficiently
long common substring and the new password with the substring partially
discounted would be weak.
.It Cm wordlist Ns = Ns Ar FILE
Deny passwords that are based on lines of the tiny external text
.Ar FILE ,
which can reasonably be e.g. a list of a few thousand common passwords.
Common dictionary words may also reasonably be included, especially in a
local language other than English, or longer yet common English words.
(passwdqc includes a list of a few thousand common English words of
lengths from 3 to 6 built in.  Any word list possibly specified with
this option is used in addition to the built-in word list.)
.Pp
Substring matching and discounting will be used if the
.Cm match
setting
above is non-zero.  Please note that this is very inefficient, and isn't
to be used with large wordlists.
.It Cm denylist Ns = Ns Ar FILE
Deny passwords or passphrases directly appearing in the tiny external text
.Ar FILE .
That file can reasonably be e.g. a list of common passwords if
only a relaxed policy is desired and stricter checks are thus disabled
(using their separate options).  Such policy would only be somewhat
effective against online/remote attacks, but not against offline attacks
on hashed passwords.
.It Cm filter Ns = Ns Ar FILE
Deny passwords or passphrases directly appearing in a maybe huge binary
filter
.Ar FILE
created with pwqfilter.  This is very efficient, needing at
most two random disk reads per query.  A filter created from millions of
leaked passwords can reasonably be used on top of passwdqc's other
checks to further reduce the number of passing yet weak passwords
without causing unreasonable inconvenience (as e.g. higher minimum
lengths and character set requirements could).
.It Cm config Ns = Ns Ar FILE
Load config
.Ar FILE
in the
.Cm passwdqc.conf
format.  This file may define any options described in
.Xr passwdqc.conf 5 , but only the
.Cm min ,
.Cm max ,
.Cm passphrase ,
.Cm match Ns ,
and
.Cm config
options are honored by
.Nm .
.It Cm -1
Read just 1 line (new passphrase).
This is needed to use
.Nm
as the passwordcheck program on OpenBSD - e.g., with
":passwordcheck=/usr/bin/pwqcheck \-1:\\"
(without the quotes, but with the trailing backslash)
in the "default" section in
.Cm /etc/login.conf .
.It Cm -2
Read just 2 lines (new and old passphrases).
.It Cm --multi
Check multiple passphrases (until EOF).
This option may be used on its own or along with the
.Cm -1
or
.Cm -2
options.
.Nm
will read 1, 2, or 3 lines and will output one line per passphrase to check.
The lines will start with either
.Ar OK
or a message explaining why the passphrase did not pass the checks,
followed by a colon and a space, and finally followed by the passphrase.
The explanatory message is guaranteed to not include a colon.
With this option, the exit status of
.Nm
depends solely on whether there were any errors preventing the strength of
passphrases from being fully checked or not.
A primary use for this option is to test different policies and/or different
versions of passwdqc on large passphrase lists.
.It Cm --version
Output
.Nm
program version and exit.
.It Cm -h , --help
Output
.Nm
help text and exit.
.El
.Sh EXIT STATUS
.Nm
exits with non-zero status when it encounters invalid config file,
invalid option, invalid parameter value, invalid data in standard input,
and in any case when it fails to check passphrase strength.
Without the
.Cm --multi
option,
.Nm
also exits with non-zero status when it detects a weak passphrase.
.Sh FILES
.Pa /etc/passwdqc.conf
(not read unless this suggested file location is specified with the
.Cm config=/etc/passwdqc.conf
option).
.Sh SEE ALSO
.Xr pwqgen 1 ,
.Xr libpasswdqc 3 ,
.Xr passwd 5 ,
.Xr passwdqc.conf 5 ,
.Xr pam_passwdqc 8 .
.Pp
https://www.openwall.com/passwdqc/
.Sh AUTHORS
The pam_passwdqc module was written for Openwall GNU/*/Linux by Solar Designer.
The
.Nm
program was originally written for ALT GNU/*/Linux by Dmitry V. Levin,
indirectly reusing code from pam_passwdqc (via libpasswdqc).
This manual page (derived from the pam_passwdqc documentation)
was written for Openwall GNU/*/Linux by Dmitry V. Levin.