diff options
Diffstat (limited to 'contrib/pam_modules/pam_passwdqc/pwqcheck.1')
| -rw-r--r-- | contrib/pam_modules/pam_passwdqc/pwqcheck.1 | 269 |
1 files changed, 269 insertions, 0 deletions
diff --git a/contrib/pam_modules/pam_passwdqc/pwqcheck.1 b/contrib/pam_modules/pam_passwdqc/pwqcheck.1 new file mode 100644 index 000000000000..fb13b3649363 --- /dev/null +++ b/contrib/pam_modules/pam_passwdqc/pwqcheck.1 @@ -0,0 +1,269 @@ +.\" 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. |