pam_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


            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 ALSO

       pam_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.


Man(1) output converted with man2html