$Id: README.txt,v 1.4.4.1 2009/06/24 10:43:20 ilo Exp $

Login Security
--------------
This module was developed to improve the security options in the login operation
of a Drupal site. By default, Drupal has only basic access control denying IP
access to the full content of the site.

With Login Security module, a site administrator may add any of the following
access control features to the login forms (default login form in /user and the
block login form).

These are the features included:


Soft Protections
----------------
Soft protections don't disrupt site navigation, but alter the way a login
operation is performed.

Currently, the login form submission can be soft-protected with these two 
options:

 - Request time delay: on any failed login, a time delay in included to the
   submit request, hardenning the bruteforce attack to the login form. Including
   a time delay in each submission, will reduce the number of login attempts a
   user or script can do. On each attempt, the delay time is increased, using
   the formula: (base time) x (login attempts)

 - Invalidate login form submission: when the soft-block protection flag is 
   enabled the login form is never submited, and any new login request will
   fail, but the host could still access the site.


Hard Protections
----------------
When there is evidence of hard account guessing operations, or when you need to
block users because of leak password guessing attempts, Hard protections may
help defeating the system.

 - Block account: it's common to block an account after a number of failed login
   attemps. Once this count is completed, the account can is blocked and user
   and admin are advised about this.

 - Block IP address: on a number of failed attempts, a host may be added to the 
   access control list. This action will leave the host completely banned from
   the site.


Track time: Protection time window
----------------------------------
The time the protections operate is defined as the track time (or time window).
It's, the time that login events are being considered for the protections. For
example, we can say that an account will be blocked on the third login attempt,
but these three attempts should have happened in the protection time window.
If the time protection window is 1 hour, the three attemps should be in the
last 60 minutes. If one of this attempts was done earlier it's not considered.

The time protection window is not the time each protection is active. Blocked 
accounts will remain blocked untill an administrator unblocks them, and banned
hosts need also administration interaction to be unbanned.


Duration of protections
-----------------------
The duration of the enabled protections depends of its type. Soft protections
are temporary, and will expire in the time defined by the 'track time' or
protection time window.

Hard protections are permanent, and an administrator should unblock or unban an
account or a host.

A blocked account could be unblocked through the administration section:
  /admin/user/user
A banned host could be un banned through the Access rules section:
  /admin/user/rules


Installation
------------
To install copy the login_security folder in your modules directory. Go to
Administer -> Site Building -> Modules and under the "Other" frame the
"Login Security" module Item will appear in the list. Enable the Checkbox
and save the configuration.


Configuration options
---------------------
Go to Administer -> User Management -> User Settings and new box will appear
close to the registering information with the following options. Any value
set to 0 will disable that option.

Basic options

 - Track time: The time window where to check for security violiations. It's,
   the time in hours the login information is kept to compute the login attempts
   count. A common example could be 24 hours. After that time, the attempt is
   deleted from the list, so it will not count.

 - Login delay base time: Delay in seconds for the next login count. It's 
   computed by host and user, so any attempt to login again with the same user
   from the same IP address will be delayed that number of seconds. The time the
   user has to wait for the next login operation is (attempts * delay), and
   the number of attempts is counted within the "Track time" time value. In the
   previous example of 24 hours, after 24h the login attemps will be cleared,
   and the delay decreased.

 - Maximum number of login failures before blocking a user: It's that easy,
   after this number of attempts to login as an user no matter the IP address
   attempting to, the user will be blocked. To remove the blocking of the user,
   you will have to go to: Administer -> User Management -> Users

 - Maximum number of login failures before soft blocking a host: After that 
   number of attempts to login from that IP address, no matter the username
   used, the host will not be allowed to submit the login form again, but the
   content of the site is still accesible for that IP address. Login attempts
   will start to clear of counts after the "Track Time" time window.

 - Maximum number of login failures before blocking a host: As the soft block
   protection does, but this time the IP address will be banned from the site,
   included in the access list as a deny rule. To remove the IP from this ban,
   you will have to go to:  Administer -> User Management -> Access Rules.

Notifications

 The module also provides some notifications for the users to understand what is
 happening.

 - Display last login timestamp: each time a user does success in login, this
   message will remember him when was the last time he logged in the site.

 - Display last access timestamp: each time a user does success in login, this
   message will remember him his last site access.

 - Notify the user about the number of remaining login attempts: It's also 
   possible to advice the user about the attempts available prior to block the
   account.

 - Disable login failure error message: Selecting this option no error message 
   will be shown at all, so user will not be aware of unsuccessful login
   attempt, or blocked account messages.

 - Send email message to the admin: An email could also be sent to the 
   administrator (uid 1), each time an account is blocked.

Some of the strings are configurable in the same administration section. The
strings can be personalized using the following placeholders:

    %date                  :  The (formated) date and time of the operation
    %ip                    :  The IP Address performing the operation
    %username              :  The username entered in the login form (sanitized)
    %email                 :  If the user exists, this will be it's name
    %uid                   :  ..and if exists, this will be it's uid
    %site                  :  The configured site's name
    %uri                   :  The base url of the Drupal site
    %edit_uri              :  Direct link to the user (name entered) edit page
    %hard_block_attempts   :  Configured attempts before hard blocking the IP 
    %soft_block_attempts   :  Configured attempts before soft blocking the IP 
    %user_block_attempts   :  Configured login attempts before blocking the user
    %user_ip_current_count :  The total attempts for the name by this IP address
    %ip_current_count      :  The total login attempts by this IP address
    %user_current_count    :  The total login attempts for this name 
    %tracking_time         :  The tracking time: in hours


Understanding protections
-------------------------
Internally, protections could consider user name, ip address or both. This is a
list of what's now implemented and how login submissions affect the protections:

 1.- On any login, the pair host<->username is saved for security, and only on a
   successfull login or by track time expiration, the pair host-username is 
   deleted from the security log.

 2.- For the delay operation, the host and the username are taken in count. This
   way, your login time will not be affected is someone is attempting to brute
   the account from other IP address.

 3.- For the soft blocking operation, any failed attempt from that host is being
   count, and when the number of attempts exceeds, the host is not allowed to
   submit the form.

   Note: (2nd and 3rd impose restrictions to the login form, and the time these
   restrictions are in rule is the time the information is being tracked: "Track
   Time").

 4.- For the user blocking operation, any failed attempt is count, so no matter
   what the source IP address is, when too many attempts appear the account is
   blocked. A successful login, even if the user is blocked will remove any
   tracking entry fron the database.

 5.- For the host blocking operation, only the host is taken in count. When too 
   many attempts appear, no matter the username being tested, the host IP
   address is banned.

   Note: (4th and 5th operations are not being cancelled automatically).
   Note: The tracking entries in the database for any host <-> username pair are
        being deleted on: 'login', 'update' and 'delete' user operations.


Most used configuration
-----------------------
The most common configuration options will look like this:

 Track time = 1 Hour
 Login delay base time = 5 secs.
 Max number of logon failures before blocking a user  = 5
 Max number of logon failures before soft blocking a host  = 10
 Max number of logon failures before blocking a host  = 15

 - The user will be blocked after five attemps of account guessing within the
   last 60 minutes.
 - Any host trying to guess an account will be punished with 5 seconds delay and
   growing on each attempt.
 - Any host trying 10 login attempts will be punished not being able to submit
   the form again within the 60 minutes track time.
 - If the number of attempts reaches 15, the host will be banned.


Other modules interaction
-------------------------
If you want your users to be informed when their accounts have been blocked,
you can use the module "Extended user status notifications":
 http://www.drupal.org/project/user_status


Other notes
-----------
The session ID (PHP session neither Drupal's session) is not taking in count for
the security operations, as automated bruteforce tool may request new sessions 
on any attempt, ignoring the session fixation from the server.


Thanks to..
-----------
Christefano and deekayen, both have done great contributions and help with this
module.
