diff options
Diffstat (limited to 'contrib/libpam/doc/man/pam_fail_delay.3')
-rw-r--r-- | contrib/libpam/doc/man/pam_fail_delay.3 | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/contrib/libpam/doc/man/pam_fail_delay.3 b/contrib/libpam/doc/man/pam_fail_delay.3 new file mode 100644 index 0000000..42bccd6 --- /dev/null +++ b/contrib/libpam/doc/man/pam_fail_delay.3 @@ -0,0 +1,130 @@ +.\" Hey Emacs! This file is -*- nroff -*- source. +.\" $Id: pam_fail_delay.3,v 1.2 1997/02/15 18:47:46 morgan Exp morgan $ +.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net> +.TH PAM_FAIL_DELAY 3 "1997 Jan 12" "Linux-PAM 0.56" "Programmers' Manual" +.SH NAME + +pam_fail_delay \- request a delay on failure + +.SH SYNOPSIS +.B #include <security/pam_appl.h> +.br +or, +.br +.B #include <security/pam_modules.h> +.sp +.BI "int pam_fail_delay(pam_handle_t " "*pamh" ", unsigned int " "usec" ");" +.sp 2 +.SH DESCRIPTION +.br +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 +.I short +timeouts, it may prove possible to attempt a +.I brute force +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 +.I covert channel +of useful information. + +.br +To minimize the effectiveness of such attacks, it is desirable to +introduce a random delay in a failed authentication process. +.B Linux-PAM +provides such a facility. The delay occurs upon failure of the +.BR pam_authenticate "(3) " +and +.BR pam_chauthtok "(3) " +functions. It occurs +.I after +all authentication modules have been called, but +.I before +control is returned to the service application. + +.br +The function, +.BR pam_fail_delay "(3)," +is used to specify a required minimum for the length of the +failure-delay; the +.I 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 distributed about the +.I maximum +requested value; the resultant delay will differ by as much as 25% of +this maximum requested value (both up and down). + +.br +On return from +.BR pam_authenticate "(3) or " pam_chauthtok "(3)," +independent of success or failure, the new requested delay is reset to +its default value: zero. + +.SH EXAMPLE +.br +For example, a +.B login +application may require a failure delay of roughly 3 seconds. It will +contain the following code: +.sp +.br +.B " pam_fail_delay(pamh, 3000000 /* micro-seconds */ );" +.br +.B " pam_authenticate(pamh, 0);" +.sp +.br +if the modules do not request a delay, the failure delay will be +between 2.25 and 3.75 seconds. + +.br +However, the modules, invoked in the authentication process, may +also request delays: +.sp +.br +.RB " (module #1) " "pam_fail_delay(pamh, 2000000);" +.sp +.br +.RB " (module #2) " "pam_fail_delay(pamh, 4000000);" +.sp +.br +in this case, it is the largest requested value that is used to +compute the actual failed delay: here between 3 and 5 seconds. + +.SH "RETURN VALUE" +Following a successful call to +.BR pam_fail_delay "(3), " PAM_SUCCESS +is returned. All other returns should be considered serious failures. + +.SH ERRORS +May be translated to text with +.BR pam_strerror "(3). " + +.SH "CONFORMING TO" +Under consideration by the X/Open group for future inclusion in the +PAM RFC. 1996/1/10 + +.SH BUGS +.sp 2 +none known. + +.SH "SEE ALSO" + +.BR pam_start "(3), " +.BR pam_get_item "(3) " +and +.BR pam_strerror "(3). " + +Also, see the three +.BR Linux-PAM +Guides, for +.BR "System administrators" ", " +.BR "module developers" ", " +and +.BR "application developers" ". " |