Relevant BUGIDs: Red Hat bz 60930

Purpose of commit: bugfix, new feature

Commit summary:
---------------
major rewrite of the pam_tally module

1 files changed, 53 insertions, 33 deletions

diff --git a/modules/pam_tally/README b/modules/pam_tally/README
index 4c421648..6c7d87f4 100644
--- a/modules/pam_tally/README
+++ b/modules/pam_tally/README
@@ -1,5 +1,5 @@
 SUMMARY:
-  pam_tally:
+  pam_tally.so:
 
         Maintains a count of attempted accesses, can reset count on success,
                 can deny access if too many attempts fail.
@@ -11,41 +11,54 @@ SUMMARY:
                 * file=/where/to/keep/counts (default /var/log/faillog)
 
         (auth)
-            Authentication phase increments attempted login counter.
-                * no_magic_root (root DOES increment counter. Use for
-                        daemon-based stuff, like telnet/rsh/login)
+            Authentication phase first checks if user should be denied access
+	    and if not it increments attempted login counter. Then on call to
+	    pam_setcred it resets the attempts counter if the user is NOT
+	    magic root.
+                * deny=n (deny access if tally for this user exceeds n)
+		
+		* lock_time=n (always deny for n seconds after failed attempt)
+		
+		* unlock_time=n (allow access after n seconds after the last
+		        failed attempt with exceeded tally)
                 
-        (account)
-            Account phase can deny access and/or reset attempts counter.
-                * deny=n (deny access if tally for this user exceeds n;
-                        The presence of deny=n changes the default for 
-                        reset/no_reset to reset, unless the user trying to
-                        gain access is root and the no_magic_root option
-                        has NOT been specified.)
-                
-                * no_magic_root (access attempts by root DON'T ignore deny.
-                        Use this for daemon-based stuff, like telnet/rsh/login)
+                * magic_root (access attempts by root as requesting user ignore
+			deny and don't change counter.
+                        Use this for su and similar services.)
+
                 * even_deny_root_account (Root can become unavailable. BEWARE.
                         Note that magic root trying to gain root bypasses this,
                         but normal users can be locked out.)
                 
-                * reset (reset count to 0 on successful entry, even for
-                        magic root)
-                * no_reset (don't reset count on successful entry)
-                        This is the default unless deny exists and the
-                        user attempting access is NOT magic root.
-
 		* per_user (If /var/log/faillog contains a non-zero
-			.fail_max field for this user then use it
-			instead of deny=n parameter)
+			.fail_max/.fail_locktime field for this user then use it
+			instead of deny=n/lock_time=n parameter.)
 
 		* no_lock_time (Don't use .fail_locktime filed in
 			/var/log/faillog for this user)
 
+                * no_reset (don't reset count on successful entry,
+		        only decrement)
+
+                
+        (account)
+            Account phase resets attempts counter if the user is NOT magic root.
+	    This phase can be used optionaly for services which don't call
+	    pam_setcred correctly or if the reset should be done regardless
+	    of the failure of the account phase of other modules.
+	    
+                * magic_root (access attempts by root as requesting user 
+			don't change counter.
+                        Use this for su and similar services.)
+
+                * no_reset (don't reset count on successful entry,
+		        only decrement)
+
         Also checks to make sure that the counts file is a plain
         file and not world writable.
 
         - Tim Baverstock <warwick@sable.demon.co.uk>, v0.1 5 March 1997
+	- Tomas Mraz <tmraz@redhat.com>, v0.2 5 January 2005
 
 LONGER:
 
@@ -53,20 +66,20 @@ pam_tally comes in two parts: pam_tally.so and pam_tally.
 
 pam_tally.so sits in a pam config file, in the auth and account sections.
 
-In the auth section, it increments a per-uid counter for each attempted
-login, in the account section, it denies access if attempted logins 
-exceed some threashold and/or resets that counter to zero on successful
-login.
+In the auth section, it denies access if attempted logins exceed some
+threshold and it increments a per-uid counter for each attempted login,
+in the account section, it resets that counter to zero on successful
+login. If the module isn't used in the account section it resets the counter
+to zero on call to pam_setcred.
 
 Root is treated specially:
 
-1. When a process already running as root tries to access some service, the
-access is `magic', and bypasses pam_tally's checks: handy for `su'ing from
-root into an account otherwise blocked. However, for services like telnet or
-login which always effectively run from the root account, root (ie everyone)
-shouldn't be granted this magic status, and the flag `no_magic_root' should
-be set in this situation, as noted in the summary above.  [This option may
-be obsolete, with `sufficient root' processing.]
+1. When a process already running as root tries to access some service and the
+'magic_root' flag is set, the access is `magic', and bypasses pam_tally's 
+checks: handy for `su'ing from root into an account otherwise blocked.
+NOTE: This was changed from the previous version of pam_tally where the default
+was to treat root as magic and there were the 'no_magic_root' flag. However
+for most of services the current default make sense.
 
 2. Normally, failed attempts to access root will NOT cause the root 
 account to become blocked, to prevent denial-of-service: if your users aren't 
@@ -93,3 +106,10 @@ The (4.0 Redhat) utilities seem to do funny things with uid, and I'm
 not wholly sure I understood what I should have been doing anyway so
 the `keep a count of current logins' bit has been #ifdef'd out and you
 can only reset the counter on successful authentication, for now.
+
+IMPORTANT NOTICE:
+In the original version of pam_tally there was a bug where the information
+if the password was correct or not was leaked by returning error from
+different pam management phases. This was solved by moving the denying
+functionality to the auth phase. However it's necessary to update the pam
+configuration by moving the required options (as deny=N) to the auth phase.