This module serves as a filter for authenticated requests handled in mod_auth. It provides possibility to restrict users from access for a specified amount of time if they fail to authenticate several times. It logs failed authentication as well as blocking of users, and it also calls a configurable call-back module when the events occur.
There is also an API to manually block, unblock and list blocked users or users, who have been authenticated within a configurable amount of time.
This module understands the following configuration directives:
Syntax: SecurityDataFile
filename
Default: - None -
Module: mod_security(3)
Context: <Directory>
Related: SecurityMaxRetries,
SecurityBlockTime,
SecurityFailExpireTime,
SecurityAuthTimeout,
SecurityCallbackModule
SecurityDataFile
sets the name of the security modules
for a directory. The filename can be either absolute or relative to the
ServerRoot
. This file is used to store persistent data for the mod_security
module.
Several directories can have the same |
Syntax: SecurityMaxRetries
integer() | infinity
Default: 3
Module: mod_security(3)
Context: <Directory>
Related: SecurityDataFile,
SecurityBlockTime,
SecurityFailExpireTime,
SecurityAuthTimeout,
SecurityCallbackModule
SecurityMaxRetries
specifies the maximum number of tries to authenticate
a user has before he is blocked out. If a user successfully authenticates when
he is blocked, he will receive a 403 (Forbidden) response from the server.
For security reasons, failed authentications made by this user will return a message 401 (Unauthorized), even if the user is blocked. |
Syntax: SecurityBlockTime
integer() | infinity
Default: 60
Module: mod_security(3)
Context: <Directory>
Related: SecurityDataFile,
SecurityMaxRetries,
SecurityFailExpireTime,
SecurityAuthTimeout,
SecurityCallbackModule
SecurityBlockTime
specifies the number of minutes a user is blocked.
After this amount of time, he automatically regains access.
Syntax: SecurityFailExpireTime
integer() | infinity
Default: 30
Module: mod_security(3)
Context: <Directory>
Related: SecurityDataFile,
SecurityMaxRetries,
SecurityFailExpireTime,
SecurityAuthTimeout,
SecurityCallbackModule
SecurityFailExpireTime
specifies the number of minutes a failed user
authentication is remembered. If a user authenticates after this amount of
time, his previous failed authentications are forgotten.
Syntax: SecurityAuthTimeout
integer() | infinity
Default: 30
Module: mod_security(3)
Context: <Directory>
Related: SecurityDataFile,
SecurityMaxRetries,
SecurityFailExpireTime,
SecurityFailExpireTime,
SecurityCallbackModule
SecurityAuthTimeout
specifies the number of seconds a successful user
authentication is remembered. After this time has passed, the authentication
will no longer be reported by the list_auth_users
function.
Syntax: SecurityCallbackModule
atom()
Default: - None -
Module: mod_security(3)
Context: <Directory>
Related: SecurityDataFile,
SecurityMaxRetries,
SecurityFailExpireTime,
SecurityFailExpireTime,
SecurityAuthTimeout
SecurityCallbackModule
specifies the name of a callback module. This module
only has one export, event/4, which
is called whenever a security event occurs. Read the
callback module documentation to find out more.
list_auth_users(Port) -> Users | []
list_auth_users(Port, Dir) -> Users | []
Port = integer()
Users = list() = [string()]
list_auth_users/1
and list_auth_users/2
returns a list
of users that are currently authenticated. Authentications are stored
for SecurityAuthTimeout seconds, and are then discarded.
list_blocked_users(Port) -> Users | []
list_blocked_users(Port, Dir) -> Users | []
Port = integer()
Users = list() = [string()]
list_blocked_users/1
returns a list of users that are currently
blocked from access.
block_user(User, Port, Dir, Seconds) -> true | {error, no_such_directory}
Port = integer()
User = string()
Dir = string()
Seconds= integer() | infinity
block_user/1
blocks the user User
from the directory
Directory
for a specified amount of time.
unblock_user(User, Port) -> true | {error, Reason}
unblock_user(User, Port, Dir) -> true | {error, Reason}
Port = integer()
User = string()
Dir = string()
Reason = term()
unblock_user/1
removes the user User
from the list of
blocked users for the Port (and Dir) specified.
The SecurityCallbackModule is a user written module that can receive events from the mod_security EWSAPI module. This module only exports one function, event/4, which is described below.
event(What, Port, Dir, Data) -> ignored
What = atom()
Port = integer()
Dir = string()
What = [Info]
Info = {Name, Value}
event/4
is called whenever an event occurs in the mod_security EWSAPI
module. The What
argument specifies the type of event that has occurred,
and should be one of the following reasons; auth_fail
(a failed user authentication),
user_block
(a user is being blocked from access) or user_unblock
(a user is being removed from the block list).
Note that the |