# mod_security

### MODULE

mod_security

### MODULE SUMMARY

Security Audit and Trailing Functionality

### DESCRIPTION

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:

- <Directory>
- SecurityDataFile
- SecurityMaxRetries
- SecurityBlockTime
- SecurityFailExpireTime
- SecurityAuthTimeout
- SecurityCallbackModule

### DIRECTIVE: "SecurityDataFile"

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 `SecurityDataFile`.

### DIRECTIVE: "SecurityMaxRetries"

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.

### DIRECTIVE: "SecurityBlockTime"

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.

### DIRECTIVE: "SecurityFailExpireTime"

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.

### DIRECTIVE: "SecurityAuthTimeout"

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.

### DIRECTIVE: "SecurityCallbackModule"

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.

### EXPORTS

`list_auth_users(Port) -> Users | []`
`list_auth_users(Address, Port) -> Users | []`
`list_auth_users(Port, Dir) -> Users | []`
`list_auth_users(Address, Port, Dir) -> Users | []`

Types:

`Port = integer()`
`Address = {A,B,C,D} | string() | undefined`
`Dir = string()`
`Users = list() = [string()]`

`list_auth_users/1`, `list_auth_users/2` and `list_auth_users/3` 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(Address, Port) -> Users | []`
`list_blocked_users(Port, Dir) -> Users | []`
`list_blocked_users(Address, Port, Dir) -> Users | []`

Types:

`Port = integer()`
`Address = {A,B,C,D} | string() | undefined`
`Dir = string()`
`Users = list() = [string()]`

`list_blocked_users/1`, `list_blocked_users/2` and `list_blocked_users/3` returns a list of users that are currently blocked from access.

`block_user(User, Port, Dir, Seconds) -> true | {error, Reason}`
`block_user(User, Address, Port, Dir, Seconds) -> true | {error, Reason}`

Types:

`User = string()`
`Port = integer()`
`Address = {A,B,C,D} | string() | undefined`
`Dir = string()`
`Seconds = integer() | infinity`
`Reason = no_such_directory`

`block_user/4` and `block_user/5` blocks the user `User` from the directory `Dir` for a specified amount of time.

`unblock_user(User, Port) -> true | {error, Reason}`
`unblock_user(User, Address, Port) -> true | {error, Reason}`
`unblock_user(User, Port, Dir) -> true | {error, Reason}`
`unblock_user(User, Address, Port, Dir) -> true | {error, Reason}`

Types:

`User = string()`
`Port = integer()`
`Address = {A,B,C,D} | string() | undefined`
`Dir = string()`
`Reason = term()`

`unblock_user/2`, `unblock_user/3` and `unblock_user/4` removes the user `User` from the list of blocked users for the Port (and Dir) specified.

### The SecurityCallbackModule

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.

### EXPORTS

`event(What, Port, Dir, Data) -> ignored`
`event(What, Address, Port, Dir, Data) -> ignored`

Types:

`What = atom()`
`Port = integer()`
`Address = {A,B,C,D} | string() <v>Dir = string()`
`What = [Info]`
`Info = {Name, Value}`

`event/4` or `event/4` is called whenever an event occurs in the mod_security EWSAPI module (`event/4` is called if Address is undefined and `event/5` otherwise). 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 `user_unblock` event is not triggered when a user is removed from the block list explicitly using the `unblock_user` function.

### AUTHORS

Mattias Nilsson - support@erlang.ericsson.se

inets 4.5
Copyright © 1991-2005 Ericsson AB