From ea488580c42e8918445a945484de3c8a5addc761 Mon Sep 17 00:00:00 2001
From: "Andrew G. Morgan" <morgan@kernel.org>
Date: Tue, 20 Jun 2000 22:10:38 +0000
Subject: Initial revision

---
 doc/man/pam_fail_delay.3 | 130 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 doc/man/pam_fail_delay.3

(limited to 'doc/man/pam_fail_delay.3')

diff --git a/doc/man/pam_fail_delay.3 b/doc/man/pam_fail_delay.3
new file mode 100644
index 00000000..f6cd238a
--- /dev/null
+++ b/doc/man/pam_fail_delay.3
@@ -0,0 +1,130 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\" $Id$
+.\" 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" ". "
-- 
cgit v1.2.3