PAM_FAIL_DELAY(3) Programmers' Manual PAM_FAIL_DELAY(3)NAMEpam_fail_delay - request a delay on failure
SYNOPSIS
#include <security/pam_appl.h>
or,
#include <security/pam_modules.h>
int pam_fail_delay(pam_handle_t *pamh, unsigned int usec);
DESCRIPTION
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 short timeouts, it may
prove possible to attempt a brute force dictionary attack
-- with an automated process, the attacker tries all pos-
sible 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 authenti-
cation process. These latter attacks make use of procedu-
ral delays that constitute a covert channel of useful
information.
To minimize the effectiveness of such attacks, it is
desirable to introduce a random delay in a failed authen-
tication process. Linux-PAM provides such a facility.
The delay occurs upon failure of the pam_authenticate(3)
and pam_chauthtok(3) functions. It occurs after all
authentication modules have been called, but before con-
trol is returned to the service application.
The function, pam_fail_delay(3), is used to specify a
required minimum for the length of the failure-delay; the
usec argument. This function can be called by the service
application and/or the authentication modules, both may
have an interest in delaying a reapplication for service
by the user. The length of the delay is computed at the
time it is required. Its length is pseudo-gausianly dis-
tributed about the maximum requested value; the resultant
delay will differ by as much as 25% of this maximum
requested value (both up and down).
On return from pam_authenticate(3) or pam_chauthtok(3),
independent of success or failure, the new requested delay
is reset to its default value: zero.
EXAMPLE
For example, a login application may require a failure
delay of roughly 3 seconds. It will contain the following
code:
pam_fail_delay(pamh, 3000000 /* micro-seconds */ );
pam_authenticate(pamh, 0);
if the modules do not request a delay, the failure delay
will be between 2.25 and 3.75 seconds.
However, the modules, invoked in the authentication pro-
cess, may also request delays:
(module #1) pam_fail_delay(pamh, 2000000);
(module #2) pam_fail_delay(pamh, 4000000);
in this case, it is the largest requested value that is
used to compute the actual failed delay: here between 3
and 5 seconds.
RETURN VALUE
Following a successful call to pam_fail_delay(3), PAM_SUC-
CESS is returned. All other returns should be considered
serious failures.
ERRORS
May be translated to text with pam_strerror(3).
CONFORMING TO
Under consideration by the X/Open group for future inclu-
sion in the PAM RFC. 1996/1/10
BUGS
none known.
SEE ALSOpam_start(3), pam_get_item(3) and pam_strerror(3).
Also, see the three Linux-PAM Guides, for System adminis-
trators, module developers, and application developers.
Linux-PAM 0.56 1997 Jan 12 PAM_FAIL_DELAY(3)
