forked from stass/pam_af
-
Notifications
You must be signed in to change notification settings - Fork 0
/
pam_af.8
174 lines (174 loc) · 5.98 KB
/
pam_af.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
.\" Copyright (c) 2005 Stanislav Sedov <[email protected]>
.\" 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.11 2006/11/07 00:10:13 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 sleep_on_deny=seconds
Use this option to sleep a time every time
.Nm
denies access.
The time is multiplied by the number of recorded login attempts.
.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 [email protected] .