Add a manual page based on Solar Designer's README.

Sponsored by:	DARPA, NAI Labs

2 files changed, 234 insertions, 1 deletions

diff --git a/lib/libpam/modules/pam_passwdqc/Makefile b/lib/libpam/modules/pam_passwdqc/Makefile
index b66a1fd..7c9bdd92 100644
--- a/lib/libpam/modules/pam_passwdqc/Makefile
+++ b/lib/libpam/modules/pam_passwdqc/Makefile
@@ -8,7 +8,7 @@ CFLAGS+=	-I${SRCDIR}
 NO_WERROR=	yes
 DPADD=		${LIBCRYPT}
 LDADD=		-lcrypt
-MAN=		#pam_passwdqc.8
+MAN=		pam_passwdqc.8
 
 .include <bsd.lib.mk>
 
diff --git a/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8 b/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8
new file mode 100644
index 0000000..f140f40
--- /dev/null
+++ b/lib/libpam/modules/pam_passwdqc/pam_passwdqc.8
@@ -0,0 +1,233 @@
+.\" Copyright (c) 2000-2002 Solar Designer.
+.\" All rights reserved.
+.\" Copyright (c) 2001 Networks Associates Technology, Inc.
+.\" All rights reserved.
+.\"
+.\" Portions of this software were developed for the FreeBSD Project by
+.\" ThinkSec AS and NAI Labs, the Security Research Division of Network
+.\" Associates, Inc.  under DARPA/SPAWAR contract N66001-01-C-8035
+.\" ("CBOSS"), as part of the DARPA CHATS research program.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. The name of the author may not be used to endorse or promote
+.\"    products derived from this software without specific prior written
+.\"    permission.
+.\"
+.\" 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd April 15, 2002
+.Dt PAM_PASSWDQC 8
+.Os
+.Sh NAME
+.Nm pam_passwdqc
+.Nd Password quality-control PAM module
+.Sh SYNOPSIS
+.Op Ar service-name
+.Ar module-type
+.Ar control-flag
+.Pa pam_passwdqc
+.Op Ar options
+.Sh DESCRIPTION
+The 
+.Nm
+module is a simple password strength checking module for
+PAM.
+In addition to checking regular passwords, it offers support for
+passphrases and can provide randomly generated passwords.
+.Pp
+The
+.Nm
+module provides functionality for only one PAM category:
+password changing.
+In terms of the
+.Ar module-type
+parameter, this is the
+.Dq Li password
+feature.
+.Pp
+The 
+.Fn pam_chauthtok
+service function will ask the user for a new password, and verify that
+it meets certain minimum standards.
+If the chosen password is unsatisfactory, the service function returns
+.Dv PAM_AUTHTOK_ERR .
+.Pp
+The following options may be passed to the authentication module:
+.Bl -tag -width 18n
+.It Cm min Ns = Ns Ar N0 Ns , Ns Ar N1 Ns , Ns Ar N2 Ns , Ns Ar N3 Ns , Ns Ar N4
+(min=disabled,24,12,8,7) 
+The minimum allowed password lengths for different kinds of passwords
+/ passphrases.
+The keyword
+.Dq 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
+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 non-ASCII characters which couldn't
+be classified, but are assumed to be non-digits.
+.Pp
+N1 is used for passwords consisting of characters from two character
+classes, which don't meet the requirements for a passphrase.
+.Pp
+N2 is used for passphrases.  
+A passphrase must consist of sufficient words (see the 
+.Cm passphrase
+option below).
+.Pp
+N3 and 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've been checked against.
+.Pp
+.It Cm max Ns = Ns Ar N
+(max=40)
+The maximum allowed password length.  
+This can be used to prevent users from setting passwords which 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 for compatibility with the traditional DES password hashes,
+which truncate the password at 8 characters.
+.Pp
+It is important that you do set max=8 if you're using the traditional
+hashes, or some weak passwords will pass the checks.
+.It Cm passphrase Ns = Ns Ar N
+(passphrase=3)
+The number of words required for a passphrase, or 0 to disable
+passphrase support.
+.It Cm match Ns = Ns Ar N
+(match=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 removed.
+.Pp
+The substring search is case-insensitive and is able to detect and
+remove a common substring spelled backwards.
+.It Cm similar Ns = Ns Ar permit Ns | Ns Ar deny
+(similar=deny)
+Whether a new password is allowed to be similar to the old one.  
+The passwords are considered to be similar when there's a sufficiently
+long common substring and the new password with the substring removed
+would be weak.
+.It Cm random Ns = Ns Ar N Ns Op , Ns Ar only
+(random=42)
+The size of randomly-generated passwords in bits, or 0 to disable this
+feature.  
+Passwords that contain the offered randomly-generated string will be
+allowed regardless of other possible restrictions.
+.Pp
+The
+.Dq only
+modifier can be used to disallow user-chosen passwords.
+.It Cm enforce Ns = Ns Ar none Ns | Ns Ar users Ns | Ns Ar everyone
+(enforce=everyone)
+The module can be configured to warn of weak passwords only, but not
+actually enforce strong passwords.  
+The
+.Dq users
+setting will enforce strong passwords for non-root users only.
+.It Cm non-unix
+Normally, 
+.Nm
+uses 
+.Xr getpwnam 3
+to obtain the user's personal login information and use that during
+the password strength checks.
+This behavior can be disabled with the
+.Cm non-unix 
+option.
+.It Cm retry Ns = Ns Ar N
+(retry = 3)
+The number of times the module will ask for a new password if the user
+fails to provide a sufficiently strong password and enter it twice the
+first time.
+.It Cm ask_oldauthtok Ns Op = Ns Ar update
+Ask for the old password as well.  
+Normally, pam_passwdqc leaves this task for subsequent modules.
+With no argument, the
+.Cm ask_oldauthtok
+option will cause
+.Nm
+to ask for the old password during the preliminary check phase.
+If the
+.Cm ask_oldauthtok
+option is specified with the
+.Dq update
+argument,
+.Nm
+will do that during the update phase.
+.It Cm check_oldauthtok
+This tells pam_passwdqc to validate the old password before giving a
+new password prompt.
+Normally, this task is left for subsequent modules.
+.Pp
+The primary use for this option is when
+.Cm ask_oldauthtok Ns = Ns Ar update
+is also specified, in which case no other modules gets a chance to ask
+for and validate the password.
+Of course, this will only work with Unix passwords.
+.It Cm use_first_pass Ns , Ns Cm use_authtok
+Use the new password obtained by modules stacked before
+.Nm .
+This disables user interaction within
+.Nm .
+The only difference between
+.Cm use_first_pass
+and
+.Cm use_authtok
+is that the former is incompatible with 
+.Cm ask_oldauthtok .
+.Sh SEE ALSO
+.Xr getpwnnam 3 ,
+.Xr pam.conf 5 ,
+.Xr pam 8
+.Sh AUTHORS
+The
+.Nm
+module was written by
+.An Solar Designer Aq solar@openwall.com .
+This manual page, derived from the author's documentation, was written
+for the
+.Fx
+Project by
+ThinkSec AS and NAI Labs, the Security Research Division of Network
+Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
+.Pq Dq CBOSS ,
+as part of the DARPA CHATS research program.