NAME
pam_passwd+ - PAM authentication module
DESCRIPTION
This file, and the source code, started life as the 'passwd+' package from Dartmouth University. The code has been heaviliy changed to make it a suitable addition to the PAM password validation suite.
CONFIGURATION FILE ------------- ----
To be accepted a password must undergo a series of tests. The tests are:
number==number fail if the two numbers are equal
string==string fail if the two strings are identical
string=~pattern fail if the string matches the pattern
[filename]==string fail if a line in the file and the string
are identical (newlines are discarded)
[filename]=~pattern fail if a line in the file matches the
pattern (newlines are discarded)
{program}==string fail if a line in the output of the program
and the string are identical (newlines are
discarded)
{program}=~pattern fail if a line in the output of the program
matches the pattern (newlines are discarded)
(test1) fail if test1 passes (grouping)
~test1 fail if test1 fails
!test1 fail if test1 fails
test1&&test2 fail if test1 and test2 are both satisfied
test1||test2 fail if either test1 or test2 are satisfied
If a password fails any listed test, it is rejected. Note any of !=, <>, <, >, >=, <=, == may be substituted for = above (with the obvious meaning), and !~ may be substituted for =~ to invert the sense of the match. Only == and != may be used to compare strings. "number" may be an expression using any of +, -, *, /, %, &, |, and ( and ) for grouping (precedence is the usual.) Use to escape a string delimiter. The & character means perform a
Certain values may be interpolated into tests by using a notation like printf's. The form is:
% [ +- ] [ <n1> ] [ . <n2> ] [ ^*|# ] <escape> The <escapes> are divided into two classes: numbers and strings. The escapes are: escape what meaning
A-Z string user defined strings (#A through #Z inclusive)
a number number of alphanumeric characters in password
b number number of alphabetic characters in password
c number number of capital letters in password
d string domain name of machine
f string first name of user
i string initials of user
l number number of lower case letters in password
m string middle name of user
n string full name of user
o string office of user
p string proposed password
q string current pasword (as typed)
s string surname of user
t string telephone number of user
u string login name of user
v number 1 if password has mixed case, 0 otherwise
w number number of (decimal) digits in password
x number home telephone number of user The escape sequence is interpreted slightly differently for numbers and strings. For numbers:
% [ +- ] [ <n1> ] [ . <n2> ] [ ^*|# ] <escape>
^ ^ ^ ^ ^ ^--- escape character
| | | | +------------ ignored
| | | +---------------------- ignored
| | +-------------------------------- ignored
| +---------------------------------------- complement
+-------------------------------------------- begin escape sequence Here, with all numbers except "%v", complementation means the relevant number is subtracted from the length of the password (where length is the lesser of the number of characters in the password and the number of significant characters). With "%v", complementation means boolean negation; if "%v" is 1, "%-v" is 0, and vice versa. "+" is ignored; "-" does the complementing. For strings:
% [ +- ] [ <n1> ] [ . <n2> ] [ $ ] [ ^*|# ] <escape>
^ ^ ^ ^ ^ ^--- escape character
| | | | +------------ format control
| | | +---------------------- ending number
| | +-------------------------------- beginning number
| +---------------------------------------- reverse
+-------------------------------------------- begin escape sequence Here, for all strings, reverse means to reverse the string beginning number
is the number of the position of the first character
to be interpolated; for example, "%1.3h" would interpolate
the first, second, and third characters of the host name
(the first character position is "1".) If there is no following
period (ie, "%1h"), it is the number of initial characters to
interpolate. ending number is the number of the position of the last character
to be interpolated; see "beginning number" above. format control controls how the word is interpolated
^ all alphabetic characters are capitalized
* all alphabetic characters are made lower case
| the first character is capitalized if alphabetic
# the length of the string is interpolated escape character
says what is to be interpolated
So, to match passwords of length 6 or less with only 'a-z' as characters:
(%#p<=6)&&("%p"=~"[a-z]*") To reject passwords of any length with only one case and only letters:
(%#v==1)&&(#%b==#%p) <or> (%#v==1)&&(%-#b==0)
WARNING: If you are using the pattern matcher to look for passwords,
ALWAYS put the string on the left and the pattern on the right.
The pattern matcher assumes what is on the left is a string.
There are a few other things that can be set in the configuration file:
1. Interpretation of GECOS field
Define the format your site uses with the constants above.
Thus, we use a field like
Matt Bishop,N230-102,6921,5551212,
so the format line would be either:
GECOS: "%s %s,%s,%s,%s,%s" f s o t x
or
GECOS: "[^,],[^,],[^,],[^,],%s" n o t x
or
SETGECOS: "%s %s,%s,%s" f s o t s
and %m would be set to NUL (so, %i would be "MB".) The letters
following the string are from the escape list; only the following
may be so set:
0 1 2 3 4 5 6 7 8 9 f i m n o s t
The part in "..." is used as a format argument to sscanf, and
the GECOS field is scanned AFTER any '&' are replaced by the
login name. If any of the escape characters are not matched
(for example, if the GECOS field above had no ','), nothing is
reset. So, if your password file has several formats for the
GECOS field, just list all of them, and the last one that matches
controls how things are set up.
Setting the GECOS field is done using this in conjunction with
two other format lines. When running in this mode (ie, when the
GECOS field is to be changed), the "GECOS:" format line above will
set variables. To have the user change these interactively, the
format line "SETGECOS:" must be used; the user will be asked to
verify or change the setting of each field.
A third format line, "FORCEGECOS:", should appear last. This
format line is ignored except when the GECOS field is being changed;
in that case, if no "SETGECOS:" line matched, the user will
be prompted using the format of that line and the GECOS field
will br written out in that format.
2. Setting Other Variables
Just in case there is no GECOS field, you are allowed to set
the variables using a "SET" statement, as follows:
SET: n "howie"
The string may be replaced by a file name, in [ ], or program
output, in { }, in which case the first line of the output or
file becomes the value of the variable. Note it will always
be a string.
2. Number of significant characters in the password
By default, all pattern matching and string compares use the
first 8 characters of the password. To change this, put the
following line in the file:
SIGCHARS: 6
This makes 6 characters significant. If the 6 were replaced by 0,
ALL characters would be significant. Only the first number is used;
any others are ignored.
Suppose there are n significant characters. String comparisons
are done on the first n characters of the strings ONLY. Pattern
matches are done on a password of length n; characters after the
(n-1)st are IGNORED. If n is 0, it is (internally) treated as
being the same as the length of the password. The aim is to
prevent a user from setting his/her password to "ambidext", which
is not in the dictionary, but will still be found by a dictionary
search when the dictionary word "ambidextrously" IS tried.
On most UNIX systems, there may not be more than 8 significant
characters in the password because the password reading routine
will only read the first 8, and discard the rest. (Don't bother
changing that routine to fix this; the encryption function also
only uses the first 8 characters.) In this case, setting the number
of significant characters to more than 8 causes only the first 8
characters to be significant. There is an internal limit on how
many characters may be significant, but it is very generous
(currently, 1023.)
3. Error messages
When a password satisfies a test in the password file, by default
the error message "password invalid -- no change" is printed.
This is unhelpful, to say the least. Users should be told why
their choice of password is not suitable. To cause a specific
error message to be printed when a password satisfies a given test,
put the error message on the same line as the test and separate it
with a tab character; thus, if a user asked his/her password to
be changed to his/her login name, the line
"%p"=="%u"<tab>password cannot be your login name
would cause the proposed password to be rejected and the error message
"password cannot be your login name" to be printed.
4. Comment lines
If the first character of a line is '#', the line is a comment
and is ignored.
A comment is also denoted by the rule containing a @ character. The
parser will stop at the first @ character. If you wish to include this
character, then prefix it with a leading character.
5. What can be logged
Different types of logging may be done:
system logs system errors which may or may not
be announced to the user
use logs who is using the program, whose password
is being changed, and the password file in
which it is being changed
result logs the result (success or failure) of the
attempted change
syntax logs any syntax errors in GECOS, LOGTYPE, or
test lines; if a test has a syntax error, it
fails
item if the password is not changed, this logs the
line number of the specific test that passed
and the error message given to the user
debug this is used for debugging; it prints all
parameters set by GECOS and SIGCHARS lines,
and the buffer passed to each test
Logging is controlled by a line of the form
LOGTYPE: type,type,...
in the test file. The types are evaluated in order, and initially
the types of logging done are LOG_DEFAULT, currently "system,syntax".
To turn off all logging, use "clear"; to turn on all types of logging,
use "all"; to turn off specific types of logging, put "!" in front of
the type. For example, "clear,all,!system" turns on all types of
logging except system logging. Saying "use,result,syntax,item,debug"
would not do the same thing, since initially "syntax" logging is on
and the other types are just or'ed in.
There are four ways logging information can be dealt with.
| command logging output is used as input to command
> file logging output is appended to file
syslog logging output is written to "syslog"
stderr logging output is written to conversational
hook. This is usually the standard error
By default, logging output goes to LG_OUTDEF. To specify another
place, say
LOGTYPE: type,type,...<tab>location
So,
LOGTYPE: all<tab>| mail staff
sends logging output for debugging to "staff".
=============================================================================