PAM_AF(8)

NAME
pam_af - Anti brute-force protection PAM module

SYNOPSIS
[service-name] module-type control-flag pam_af [options]

DESCRIPTION
The pam_af module for PAM, typically /usr/lib/pam_af.so, provides functionality for PAM authentification category. The main purpose of the pam_af module is to prevent brute-force attacks against protected services, like SSH. Although, it is desirable for users to enforce strong passwords, weak password's practice are still very common. In these cases brute-force attack can be succesful. Also these attacks can mess-up system log with useless records, and system administrator can pass something really important.

The pam_af module is a shared object and can be loaded dynamically to provide the requred functionality to application. The following PAM functions are implemeted in pam_af module:

pam_sm_authenticate() Use this function to check if the host can be authentificated or not. The pam_af module maintains statistics for each host, that tries to authetificate. It stores the number of attempts and last attempt's timestamp. When called. the authetification stage the pam_sm_authenticate() function finds the configuration rule for given host and makes appropiate decision using failed attempt's count from host statistics. If this number exceeds configured limit, host would be rejected and blocked for time, specified in the host's rule. Additionally, external command can be executed in that case. It is useful, for example, to block the 'bad' host in firewall.

Simillary, if the pam_af module detects the block time has been passed, it unlocks host and executes given external command.

pam_am_setcred() This routine must be called after a successful login. The main objective of this function is to clear the host's statistics. It zerofies the attempts count and stores updated value in the backing storage.

External programs execution
As has already mentioned above, the pam_af module can execute external commands, when changing locked/unlocked status of the host. The following enviropment variables would be set in addition to standart PAM enviropment:

PAM_RHOST
    the hostname of the applicant

PAM_RUSER
    the name of the applicant

PAM_USER
    the name of the user the application is trying to authentificate

PAM_SERVICE
    the name of the requested service

PAM_TTY
    current terminal

Runtime configuration
The following options may be passed to the authentication module:

debug
    Report debugging information using syslog(3) (at LOG_DEBUG level).

no_warn
    Suppress warning messages to the user. These messages include reasons why the auth attempt was denied.

allow_on_error
    By default, the pam_af module declines the user's authentification attempt, if unrecoverable error occurs. Specifing this option forces the PAM_SUCCESS to be returned in this case.

update_locked
    specify this option to force the pam_af module to update host's statistics even if the host is locked. This can increase module's overhead. This option can be useful if you wants the lock time to be measured from the last attempt.

statdb=file
    Use file as backing storage for the statistics databse. By default /var/db/pam_af.db will be used. Notice: .db suffix will be added, so if you want, for example, to use /tmp/pam_af.db as backing storage, you must specify statdb=/tmp/pam_af as argument.

cfgdb=file
    Use file as backing storage for the configuration databse. By default /etc/pam_af.conf.db will be used. Above notice also has place.

FILES

/var/db/pam_af.db
    default statistics database.

/etc/pam_af.conf.db
    default configuration database.

SEE ALSO
pam_af_tool(8), dbm(3), syslog(3), pam.conf(5), pam(8)

BUGS
Host statistics is stored using hostname as hash key, so if the host has several names, the statistics would not be accurate. Disable hostnames lookup to avoid this.

The PAM_RHOST and PAM_TTY enviropment variables would only be set, if previous modules have defined it.

Not all runtime options available on all platforms.

AUTHORS
The pam_af module and this manual page was written by Stanislav Sedov <stas@FreeBSD.org>.