1
1
.\" Title: pam_fail_delay
3
.\" Generator: DocBook XSL Stylesheets v1.73.1 <http://docbook.sf.net/>
2
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
3
.\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
5
5
.\" Manual: Linux-PAM Manual
6
6
.\" Source: Linux-PAM Manual
8
.TH "PAM_FAIL_DELAY" "3" "04/16/2008" "Linux-PAM Manual" "Linux-PAM Manual"
9
.TH "PAM_FAIL_DELAY" "3" "03/02/2009" "Linux-PAM Manual" "Linux-PAM Manual"
10
.\" -----------------------------------------------------------------
11
.\" * (re)Define some macros
12
.\" -----------------------------------------------------------------
13
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
14
.\" toupper - uppercase a string (locale-aware)
15
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17
.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
19
.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
21
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22
.\" SH-xref - format a cross-reference to an SH section
23
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
33
.\" SH - level-one heading that works better for non-TTY output
34
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36
.\" put an extra blank line of space above the head in non-TTY output
43
.nr an-prevailing-indent \\n[IN]
47
.HTML-TAG ".NH \\n[an-level]"
49
.nr an-no-space-flag 1
51
\." make the size of the head bigger
56
.\" if n (TTY output), use uppercase
61
.\" if not n (not TTY), use normal case (not uppercase)
65
.\" if not n (not TTY), put a border/line under subheading
70
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71
.\" SS - level-two heading that works better for non-TTY output
72
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77
.nr an-prevailing-indent \\n[IN]
82
.nr an-no-space-flag 1
85
\." make the size of the head bigger
91
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92
.\" BB/BE - put background/screen (filled box) around block of text
93
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106
.if "\\$2"adjust-for-leading-newline" \{\
114
.nr BW \\n(.lu-\\n(.i
117
.ie "\\$2"adjust-for-leading-newline" \{\
118
\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
121
\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
132
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133
.\" BM/EM - put colored marker in margin next to block of text
134
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151
\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
159
.\" -----------------------------------------------------------------
160
.\" * set default formatting
161
.\" -----------------------------------------------------------------
9
162
.\" disable hyphenation
11
164
.\" disable justification (adjust text to left margin only)
14
pam_fail_delay - request a delay on failure
166
.\" -----------------------------------------------------------------
167
.\" * MAIN CONTENT STARTS HERE *
168
.\" -----------------------------------------------------------------
170
pam_fail_delay \- request a delay on failure
19
#include <security/pam_appl\.h>
177
#include <security/pam_appl\&.h>
183
.HP \w'int\ pam_fail_delay('u
23
184
.BI "int pam_fail_delay(pam_handle_t\ *" "pamh" ", unsigned\ int\ " "usec" ");"
27
189
\fBpam_fail_delay\fR
28
190
function provides a mechanism by which an application or module can suggest a minimum delay of
30
micro\-seconds\. The function keeps a record of the longest time requested with this function\. Should
192
micro\-seconds\&. The function keeps a record of the longest time requested with this function\&. Should
31
193
\fBpam_authenticate\fR(3)
32
fail, the failing return to the application is delayed by an amount of time randomly distributed (by up to 25%) about this longest value\.
194
fail, the failing return to the application is delayed by an amount of time randomly distributed (by up to 25%) about this longest value\&.
34
Independent of success, the delay time is reset to its zero default value when the PAM service module returns control to the application\. The delay occurs
196
Independent of success, the delay time is reset to its zero default value when the PAM service module returns control to the application\&. The delay occurs
36
198
all authentication modules have been called, but
38
control is returned to the service application\.
200
control is returned to the service application\&.
40
202
When using this function the programmer should check if it is available with:
213
.BB lightgray adjust-for-leading-newline
44
216
#ifdef HAVE_PAM_FAIL_DELAY
46
218
#endif /* HAVE_PAM_FAIL_DELAY */
220
.EB lightgray adjust-for-leading-newline
51
For applications written with a single thread that are event driven in nature, generating this delay may be undesirable\. Instead, the application may want to register the delay in some other way\. For example, in a single threaded server that serves multiple authentication requests from a single event loop, the application might want to simply mark a given connection as blocked until an application timer expires\. For this reason the delay function can be changed with the
231
For applications written with a single thread that are event driven in nature, generating this delay may be undesirable\&. Instead, the application may want to register the delay in some other way\&. For example, in a single threaded server that serves multiple authentication requests from a single event loop, the application might want to simply mark a given connection as blocked until an application timer expires\&. For this reason the delay function can be changed with the
52
232
\fIPAM_FAIL_DELAY\fR
53
item\. It can be queried and set with
233
item\&. It can be queried and set with
54
234
\fBpam_get_item\fR(3)
56
236
\fBpam_set_item \fR(3)
57
respectively\. The value used to set it should be a function pointer of the following prototype:
237
respectively\&. The value used to set it should be a function pointer of the following prototype:
248
.BB lightgray adjust-for-leading-newline
61
251
void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);
253
.EB lightgray adjust-for-leading-newline
66
264
The arguments being the
70
268
micro\-second delay that libpam is requesting and the
72
270
that the application has associated with the current
73
\fIpamh\fR\. This last value was set by the application when it called
271
\fIpamh\fR\&. This last value was set by the application when it called
74
272
\fBpam_start\fR(3)
75
273
or explicitly with
76
\fBpam_set_item\fR(3)\. Note, if PAM_FAIL_DELAY item is unset (or set to NULL), then no delay will be performed\.
274
\fBpam_set_item\fR(3)\&. Note, if PAM_FAIL_DELAY item is unset (or set to NULL), then no delay will be performed\&.
79
It is often possible to attack an authentication scheme by exploiting the time it takes the scheme to deny access to an applicant user\. In cases of
277
It is often possible to attack an authentication scheme by exploiting the time it takes the scheme to deny access to an applicant user\&. In cases of
81
279
timeouts, it may prove possible to attempt a
83
dictionary attack \-\- with an automated process, the attacker tries all possible passwords to gain access to the system\. In other cases, where individual failures can take measurable amounts of time (indicating the nature of the failure), an attacker can obtain useful information about the authentication process\. These latter attacks make use of procedural delays that constitute a
281
dictionary attack \-\- with an automated process, the attacker tries all possible passwords to gain access to the system\&. In other cases, where individual failures can take measurable amounts of time (indicating the nature of the failure), an attacker can obtain useful information about the authentication process\&. These latter attacks make use of procedural delays that constitute a
84
282
\fIcovert channel\fR
85
of useful information\.
283
of useful information\&.
87
To minimize the effectiveness of such attacks, it is desirable to introduce a random delay in a failed authentication process\. Preferable this value should be set by the application or a special PAM module\. Standard PAM modules should not modify the delay unconditional\.
285
To minimize the effectiveness of such attacks, it is desirable to introduce a random delay in a failed authentication process\&. Preferable this value should be set by the application or a special PAM module\&. Standard PAM modules should not modify the delay unconditional\&.
90
For example, a login application may require a failure delay of roughly 3 seconds\. It will contain the following code:
288
For example, a login application may require a failure delay of roughly 3 seconds\&. It will contain the following code:
299
.BB lightgray adjust-for-leading-newline
94
302
pam_fail_delay (pamh, 3000000 /* micro\-seconds */ );
95
303
pam_authenticate (pamh, 0);
305
.EB lightgray adjust-for-leading-newline
100
if the modules do not request a delay, the failure delay will be between 2\.25 and 3\.75 seconds\.
316
if the modules do not request a delay, the failure delay will be between 2\&.25 and 3\&.75 seconds\&.
102
318
However, the modules, invoked in the authentication process, may also request delays:
329
.BB lightgray adjust-for-leading-newline
106
332
module #1: pam_fail_delay (pamh, 2000000);
107
333
module #2: pam_fail_delay (pamh, 4000000);
335
.EB lightgray adjust-for-leading-newline
112
in this case, it is the largest requested value that is used to compute the actual failed delay: here between 3 and 5 seconds\.
346
in this case, it is the largest requested value that is used to compute the actual failed delay: here between 3 and 5 seconds\&.
113
347
.SH "RETURN VALUES"
117
Delay was successful adjusted\.
351
Delay was successful adjusted\&.
122
A NULL pointer was submitted as PAM handle\.
356
A NULL pointer was submitted as PAM handle\&.
added
removed
doc/man/pam_fail_delay.3
