head	1.1;
access;
symbols;
locks; strict;
comment	@# @;


1.1
date	96.05.21.04.55.00;	author morgan;	state Exp;
branches;
next	;


desc
@@


1.1
log
@Initial revision
@
text
@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
'bitwise AND' while the | character means to perform a 'bitwise OR'.

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".

=============================================================================

@
