Add documentation. Prerelease 0.9.9 - RC candidate.libpwquality-0.9.9

6 files changed, 527 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..ad800b6
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = man
diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
new file mode 100644
index 0000000..1d00097
--- /dev/null
+++ b/doc/man/Makefile.am
@@ -0,0 +1 @@
+dist_man_MANS = pwmake.1 pwscore.1 pam_pwquality.8 pwquality.conf.5
diff --git a/doc/man/pam_pwquality.8 b/doc/man/pam_pwquality.8
new file mode 100644
index 0000000..aead0c3
--- /dev/null
+++ b/doc/man/pam_pwquality.8
@@ -0,0 +1,346 @@
+.de FN
+\fI\|\\$1\|\fP
+..
+.TH PAM_PWQUALITY 8 "10 Nov 2011" "Red Hat, Inc."
+.SH NAME
+pam_pwquality \- PAM module to perform password quality checking
+.SH SYNOPSIS
+\fBpam_pwquality\&.so\fR [\fI\&.\&.\&.\fR]
+.SH DESCRIPTION
+.PP
+This module can be plugged into the
+\fIpassword\fR
+stack of a given service to provide some plug\-in strength\-checking
+for passwords\&. The code was originaly based on pam_cracklib module
+and the module is backwards compatible with its options\&.
+.PP
+The action of this module is to prompt the user for a password and check
+its strength against a system dictionary and a set of rules for identifying
+poor choices\&.
+.PP
+The first action is to prompt for a single password, check its strength
+and then, if it is considered strong, prompt for the password a second time
+(to verify that it was typed correctly on the first occasion)\&. All being
+well, the password is passed on to subsequent modules to be installed as the
+new authentication token\&.
+.PP
+The strength checks works in the following manner: at first the
+\fBCracklib\fR
+routine is called to check if the password is part of a dictionary; if this
+is not the case an additional set of strength checks are done\&. These checks
+are:
+.PP
+Palindrome
+.RS 4
+Is the new password a palindrome?
+.RE
+.PP
+Case Change Only
+.RS 4
+Is the new password the the old one with only a change of case?
+.RE
+.PP
+Similar
+.RS 4
+Is the new password too much like the old one? This is primarily controlled
+by one argument,
+\fBdifok\fR
+which is a number of changes between the old and new are enough to accept
+the new password\&.
+.RE
+.PP
+Simple
+.RS 4
+Is the new password too small? This is controlled by 5 arguments
+\fBminlen\fR,
+\fBdcredit\fR,
+\fBucredit\fR,
+\fBlcredit\fR, and
+\fBocredit\fR\&. See the section on the arguments for the details of how
+these work and there defaults\&.
+.RE
+.PP
+Rotated
+.RS 4
+Is the new password a rotated version of the old password?
+.RE
+.PP
+Same consecutive characters
+.RS 4
+Optional check for same consecutive characters\&.
+.RE
+.PP
+Contains user name
+.RS 4
+Optional check whether the password contains the user name in some form\&.
+.RE
+.PP
+These checks are configurable either by use of the module arguments
+or by modifying the \fB/etc/security/pwquality.conf\fR configuration file.
+.PD
+.SH OPTIONS
+.PP
+\fBdebug\fR
+.RS 4
+This option makes the module write information to
+\fBsyslog\fR(3)
+indicating the behavior of the module (this option does not write password
+information to the log file)\&.
+.RE
+.PP
+\fBauthtok_type=\fR\fB\fIXXX\fR\fR
+.RS 4
+The default action is for the module to use the following prompts when
+requesting passwords: "New UNIX password: " and
+"Retype UNIX password: "\&. The example word
+\fIUNIX\fR
+can be replaced with this option, by default it is empty\&.
+.RE
+.PP
+\fBretry=\fR\fB\fIN\fR\fR
+.RS 4
+Prompt user at most
+\fIN\fR
+times before returning with error\&. The default is
+\fI1\fR\&.
+.RE
+.PP
+\fBdifok=\fR\fB\fIN\fR\fR
+.RS 4
+This argument will change the default of
+\fI5\fR
+for the number of changes in the new password from the old password\&.
+.RE
+.PP
+\fBminlen=\fR\fB\fIN\fR\fR
+.RS 4
+The minimum acceptable size for the new password (plus one if credits are not
+disabled which is the default)\&. In addition to the number of characters in
+the new password, credit (of +1 in length) is given for each different kind
+of character (\fIother\fR,
+\fIupper\fR,
+\fIlower\fR
+and
+\fIdigit\fR)\&. The default for this parameter is
+\fI9\fR
+\&. Note that there is a pair of length limits also in
+\fICracklib\fR,
+which is used for dictionary checking, a "way too short" limit of 4 which
+is hard coded in and a build time defined limit (6) that will be checked
+without reference to \fBminlen\fR\&.
+.RE
+.PP
+\fBdcredit=\fR\fB\fIN\fR\fR
+.RS 4
+(N >= 0) This is the maximum credit for having digits in the new password\&.
+If you have less than or
+\fIN\fR
+digits, each digit will count +1 towards meeting the current
+\fBminlen\fR
+value\&. The default for
+\fBdcredit\fR
+is 1 which is the recommended value for
+\fBminlen\fR
+less than 10\&.
+.sp
+(N < 0) This is the minimum number of digits that must be met for a new
+password\&.
+.RE
+.PP
+\fBucredit=\fR\fB\fIN\fR\fR
+.RS 4
+(N >= 0) This is the maximum credit for having upper case letters in the
+new password\&. If you have less than or
+\fIN\fR
+upper case letters each letter will count +1 towards meeting the current
+\fBminlen\fR
+value\&. The default for
+\fBucredit\fR
+is
+\fI1\fR
+which is the recommended value for
+\fBminlen\fR
+less than 10\&.
+.sp
+(N < 0) This is the minimum number of upper case letters that must be met
+for a new password\&.
+.RE
+.PP
+\fBlcredit=\fR\fB\fIN\fR\fR
+.RS 4
+(N >= 0) This is the maximum credit for having lower case letters in the
+new password\&. If you have less than or
+\fIN\fR
+lower case letters, each letter will count +1 towards meeting the current
+\fBminlen\fR
+value\&. The default for
+\fBlcredit\fR
+is 1 which is the recommended value for
+\fBminlen\fR
+less than 10\&.
+.sp
+(N < 0) This is the minimum number of lower case letters that must be met
+for a new password\&.
+.RE
+.PP
+\fBocredit=\fR\fB\fIN\fR\fR
+.RS 4
+(N >= 0) This is the maximum credit for having other characters in the new
+password\&. If you have less than or
+\fIN\fR
+other characters, each character will count +1 towards meeting the current
+\fBminlen\fR
+value\&. The default for
+\fBocredit\fR
+is 1 which is the recommended value for
+\fBminlen\fR
+less than 10\&.
+.sp
+(N < 0) This is the minimum number of other characters that must be met for
+a new password\&.
+.RE
+.PP
+\fBminclass=\fR\fB\fIN\fR\fR
+.RS 4
+The minimum number of required classes of characters for the new password\&.
+The default number is zero\&. The four classes are digits, upper and lower
+letters and other characters\&. The difference to the
+\fBcredit\fR
+check is that a specific class if of characters is not required\&. Instead
+\fIN\fR
+out of four of the classes are required\&.
+.RE
+.PP
+\fBmaxrepeat=\fR\fB\fIN\fR\fR
+.RS 4
+Reject passwords which contain more than N same consecutive characters\&.
+The default is 0 which means that this check is disabled\&.
+.RE
+.PP
+\fBuse_authtok\fR
+.RS 4
+This argument is used to
+\fIforce\fR
+the module to not prompt the user for a new password but use the one
+provided by the previously stacked
+\fIpassword\fR
+module\&.
+.RE
+.PP
+\fBdictpath=\fR\fB\fI/path/to/dict\fR\fR
+.RS 4
+Path to the cracklib dictionaries\&.
+.RE
+
+.PD
+.SH "MODULE TYPES PROVIDED"
+.PP
+Only the
+\fBpassword\fR
+module type is provided\&.
+
+.PD
+.SH "RETURN VALUES"
+.PP
+.PP
+PAM_SUCCESS
+.RS 4
+The new password passes all checks\&.
+.RE
+.PP
+PAM_AUTHTOK_ERR
+.RS 4
+No new password was entered, the username could not be determined or the
+new password fails the strength checks\&.
+.RE
+.PP
+PAM_AUTHTOK_RECOVERY_ERR
+.RS 4
+The old password was not supplied by a previous stacked module or got not
+requested from the user\&. The first error can happen if
+\fBuse_authtok\fR
+is specified\&.
+.RE
+.PP
+PAM_SERVICE_ERR
+.RS 4
+A internal error occurred\&.
+.RE
+.SH "EXAMPLES"
+.PP
+For an example of the use of this module, we show how it may be stacked with the password component of
+\fBpam_unix\fR(8)
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+#
+# These lines stack two password type modules\&. In this example the
+# user is given 3 opportunities to enter a strong password\&. The
+# "use_authtok" argument ensures that the pam_unix module does not
+# prompt for a password, but instead uses the one provided by
+# pam_pwquality\&.
+#
+passwd  password required       pam_pwquality\&.so retry=3
+passwd  password required       pam_unix\&.so use_authtok
+
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Another example (in the
+/etc/pam\&.d/passwd
+format) is for the case that you want to use md5 password encryption:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+#%PAM\-1\&.0
+#
+# These lines allow a md5 systems to support passwords of at least 14
+# bytes with extra credit of 2 for digits and 2 for others the new
+# password must have at least three bytes that are not present in the
+# old password
+#
+password  required pam_pwquality\&.so \e
+               difok=3 minlen=15 dcredit= 2 ocredit=2
+password  required pam_unix\&.so use_authtok nullok md5
+
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+And here is another example in case you don\'t want to use credits:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+#%PAM\-1\&.0
+#
+# These lines require the user to select a password with a minimum
+# length of 8 and with at least 1 digit number, 1 upper case letter,
+# and 1 other character
+#
+password  required pam_pwquality\&.so \e
+               dcredit=\-1 ucredit=\-1 ocredit=\-1 lcredit=0 minlen=8
+password  required pam_unix\&.so use_authtok nullok md5
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.PD
+.SH "SEE ALSO"
+pwscore(1), pwquality.conf(5), pam_pwquality(8),
+pam.conf(5), PAM(8)
+
+.SH AUTHORS
+.nf
+Tomas Mraz <tmraz@redhat\&.com>
+Original author of pam_cracklib module Cristian Gafton <gafton@redhat\&.com>
+.fi
diff --git a/doc/man/pwmake.1 b/doc/man/pwmake.1
new file mode 100644
index 0000000..700cddb
--- /dev/null
+++ b/doc/man/pwmake.1
@@ -0,0 +1,45 @@
+.de FN
+\fI\|\\$1\|\fP
+..
+.TH PWMAKE 1 "10 Nov 2011" "Red Hat, Inc."
+.SH NAME
+pwmake \- simple tool for generating random relatively easily pronounceable
+passwords
+.SH SYNOPSIS
+\fBpwmake\fR <entropy-bits>
+.SH DESCRIPTION
+\fBpwmake\fR is a simple configurable tool for generating random and relatively
+easily pronounceable passwords. The tool allows you to specify the number of
+entropy bits that are used to generate the password.
+
+The entropy is pulled from \fB/dev/urandom\fR.
+
+The minimum number of bits is \fB56\fR which is usable for passwords on
+systems/services where brute force attacks are of very limited rate of tries.
+The \fB64\fR bits should be adequate for applications where the attacker
+does not have direct access to the password hash file. For situations where
+the attacker might obtain the direct access to the password hash or the
+password is used as an encryption key \fB80\fR to \fB128\fR bits should be
+used depending on your level of paranoia.
+
+.PD
+.SH OPTIONS
+The first and only argument is the number of bits of entropy used to generate
+the password.
+
+.SH FILES
+\fB/etc/security/pwquality.conf\fR - The configuration file for the libpwquality
+library.
+
+.PD
+.SH "RETURN CODES"
+\fBpwmake\fR returns 0 on success, non zero on error.
+
+.PD
+.SH "SEE ALSO"
+pwscore(1), pam_pwquality(8)
+
+.SH AUTHORS
+.nf
+Tomas Mraz <tmraz@redhat.com>
+.fi
diff --git a/doc/man/pwquality.conf.5 b/doc/man/pwquality.conf.5
new file mode 100644
index 0000000..0418ff3
--- /dev/null
+++ b/doc/man/pwquality.conf.5
@@ -0,0 +1,93 @@
+.de FN
+\fI\|\\$1\|\fP
+..
+.TH PWQUALITY.CONF 5 "10 Nov 2011" "Red Hat, Inc."
+.SH NAME
+pwquality.conf \- configuration for the libpwquality library
+.SH SYNOPSIS
+\fB/etc/security/pwquality.conf\fR
+.SH DESCRIPTION
+\fBpwquality.conf\fR provides a way to configure the default password
+quality requirements for the system passwords. This file is read by the
+libpwquality library and utilities that use this library for checking
+and generating passwords.
+
+The file has a very simple \fIname = value\fR format with possible comments
+starting with \fB#\fR character.
+
+.PD
+.SH OPTIONS
+The possible options in the file are:
+.RS 4
+.PP
+\fBdifok\fR
+.RS 4
+Number of characters in the new password that must not be present in the
+old password. (default 5)
+.RE
+.PP
+\fBdifignore\fR
+.RS 4
+How many characters should the password have before difok will be
+ignored. (default 23)
+.RE
+.PP
+\fBminlen\fR
+.RS 4
+Minimum acceptable size for the new password (plus one if credits are not
+disabled which is the default). (See \fIpam_pwquality(8)\fR.)
+Cannot be set to lower value than 6. (default 9)
+.RE
+.PP
+\fBdcredit\fR
+.RS 4
+The maximum credit for having digits in the new password. If less than 0
+it is the minimum number of digits in the new password. (default 1)
+.RE
+.PP
+\fBucredit\fR
+.RS 4
+The maximum credit for having uppercase characters in the new password.
+If less than 0 it is the minimum number of uppercase characters in the new
+password. (default 1)
+.RE
+.PP
+\fBlcredit\fR
+.RS 4
+The maximum credit for having lowercase characters in the new password.
+If less than 0 it is the minimum number of lowercase characters in the new
+password. (default 1)
+.RE
+.PP
+\fBocredit\fR
+.RS 4
+The maximum credit for having other characters in the new password.
+If less than 0 it is the minimum number of other characters in the new
+password. (default 1)
+.RE
+.PP
+\fBminclass\fR
+.RS 4
+The minimum number of required classes of characters for the new
+password (digits, uppercase, lowercase, others). (default 0)
+.RE
+.PP
+\fBmaxrepeat\fR
+.RS 4
+The maximum number of allowed same consecutive characters in the new password.
+The check is disabled if the value is 0. (default 0)
+.RE
+.PP
+\fBdictpath\fR
+.RS 4
+Path to the cracklib dictionaries. Default is to use the cracklib default.
+.RE
+
+.PD
+.SH "SEE ALSO"
+pwscore(1), pwmake(1), pam_pwquality(8)
+
+.SH AUTHORS
+.nf
+Tomas Mraz <tmraz@redhat.com>
+.fi
diff --git a/doc/man/pwscore.1 b/doc/man/pwscore.1
new file mode 100644
index 0000000..3604304
--- /dev/null
+++ b/doc/man/pwscore.1
@@ -0,0 +1,41 @@
+.de FN
+\fI\|\\$1\|\fP
+..
+.TH PWSCORE 1 "10 Nov 2011" "Red Hat, Inc."
+.SH NAME
+pwscore \- simple configurable tool for checking quality of a password
+.SH SYNOPSIS
+\fBpwscore\fR [user]
+.SH DESCRIPTION
+\fBpwscore\fR is a simple tool for checking quality of a password. The password
+is read from stdin.
+
+The tool uses the \fBlibpwquality\fR library to perform configurable checks
+for minimum length, dictionary checking against cracklib dictionaries,
+and other checks.
+
+It either reports an error if the password fails any of the checks, or it
+prints out the password quality score as an integer value between \fB0\fR and
+\fB100\fR.
+
+.PD
+.SH OPTIONS
+The first and only optional argument is the user name that is used to check
+the similarity of the password to the username.
+
+.SH FILES
+\fB/etc/security/pwquality.conf\fR - The configuration file for the libpwquality
+library.
+
+.PD
+.SH "RETURN CODES"
+\fBpwscore\fR returns 0 on success, non zero on error.
+
+.PD
+.SH "SEE ALSO"
+pwscore(1), pwquality.conf(5), pam_pwquality(8)
+
+.SH AUTHORS
+.nf
+Tomas Mraz <tmraz@redhat.com>
+.fi