.\" Copyright (c) 2005 Stanislav Sedov .\" Copyright (c) 2005 MBSD labs .\" Copyright (c) 2005 by 310.ru [Tridesyatoe], Moscow, Russian Federation .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Id: pam_af.8,v 1.9 2005/10/15 13:26:34 stas Exp $ .\" .Dd August 18, 2005 .Dt PAM_AF 8 .Os .Sh NAME .Nm pam_af .Nd Anti brute-force protection PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_af .Op Ar options .Sh DESCRIPTION The .Nm module for PAM, typically .Pa /usr/lib/pam_af.so , provides functionality for PAM authentification category. The main purpose of the .Nm 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. .Pp The .Nm module is a shared object and can be loaded dynamically to provide the requred functionality to application. The following PAM functions are implemeted in .Nm module: .Bl -inset -offset indent .It Fn pam_sm_authenticate Use this function to check if the host can be authentificated or not. The .Nm 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 .Fn 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. .Pp Simillary, if the .Nm module detects the block time has been passed, it unlocks host and executes given external command. .It Fn 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. .El .Pp .Sh External programs execution As has already mentioned above, the .Nm 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: .Bl -tag -width indent .It Ev PAM_RHOST the hostname of the applicant .It Ev PAM_RUSER the name of the applicant .It Ev PAM_USER the name of the user the application is trying to authentificate .It Ev PAM_SERVICE the name of the requested service .It Ev PAM_TTY current terminal .El .Pp .Sh Runtime configuration The following options may be passed to the authentication module: .Bl -tag -width indent .It Cm debug Report debugging information using .Xr syslog 3 (at .Dv LOG_DEBUG level). .It Cm no_warn Suppress warning messages to the user. These messages include reasons why the auth attempt was denied. .It Cm allow_on_error By default, the .Nm module declines the user's authentification attempt, if unrecoverable error occurs. Specifing this option forces the PAM_SUCCESS to be returned in this case. .It Cm update_locked specify this option to force the .Nm 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. .It Cm statdb=file Use file as backing storage for the statistics databse. By default .Pa /var/db/pam_af.db will be used. Notice: .db suffix will be added, so if you want, for example, to use .Pa /tmp/pam_af.db as backing storage, you must specify .Cm statdb=/tmp/pam_af as argument. .It Cm cfgdb=file Use file as backing storage for the configuration databse. By default .Pa /etc/pam_af.conf.db will be used. Above notice also has place. .El .Sh FILES .Bl -tag -width indent .It Pa /var/db/pam_af.db default statistics database. .It Pa /etc/pam_af.conf.db default configuration database. .El .Sh SEE ALSO .Xr pam_af_tool 8 , .Xr dbm 3 , .Xr syslog 3 , .Xr pam.conf 5 , .Xr pam 8 .Sh 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. .Pp The PAM_RHOST and PAM_TTY enviropment variables would only be set, if previous modules have defined it. .Pp Not all runtime options available on all platforms. .Sh AUTHORS The .Nm module and this manual page was written by .An Stanislav Sedov Aq stas@FreeBSD.org .