Debian Codegraph @

upstream/debian-unstable/man3/pam_fail_delay.3

raw
1 '\" t
2 .\" Title: pam_fail_delay
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 06/29/2025
6 .\" Manual: Linux-PAM Manual
7 .\" Source: Linux-PAM
8 .\" Language: English
9 .\"
10 .TH "PAM_FAIL_DELAY" "3" "06/29/2025" "Linux\-PAM" "Linux\-PAM Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 pam_fail_delay \- request a delay on failure
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <security/pam_appl\&.h>
37 .fi
38 .ft
39 .HP \w'int\ pam_fail_delay('u
40 .BI "int pam_fail_delay(pam_handle_t\ *" "pamh" ", unsigned\ int\ " "usec" ");"
41 .SH "DESCRIPTION"
42 .PP
43 The
44 \fBpam_fail_delay\fR
45 function provides a mechanism by which an application or module can suggest a minimum delay of
46 \fIusec\fR
47 micro\-seconds\&. The function keeps a record of the longest time requested with this function\&. Should
48 \fBpam_authenticate\fR(3)
49 fail, the failing return to the application is delayed by an amount of time randomly distributed (by up to 50%) about this longest value\&.
50 .PP
51 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
52 \fIafter\fR
53 all authentication modules have been called, but
54 \fIbefore\fR
55 control is returned to the service application\&.
56 .PP
57 When using this function the programmer should check if it is available with:
58 .sp
59 .if n \{\
60 .RS 4
61 .\}
62 .nf
63 #ifdef HAVE_PAM_FAIL_DELAY
64 \&.\&.\&.\&.
65 #endif /* HAVE_PAM_FAIL_DELAY */
66
67 .fi
68 .if n \{\
69 .RE
70 .\}
71 .PP
72 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
73 \fIPAM_FAIL_DELAY\fR
74 item\&. It can be queried and set with
75 \fBpam_get_item\fR(3)
76 and
77 \fBpam_set_item\fR(3)
78 respectively\&. The value used to set it should be a function pointer of the following prototype:
79 .sp
80 .if n \{\
81 .RS 4
82 .\}
83 .nf
84 void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);
85
86 .fi
87 .if n \{\
88 .RE
89 .\}
90 .sp
91 The arguments being the
92 \fIretval\fR
93 return code of the module stack, the
94 \fIusec_delay\fR
95 micro\-second delay that libpam is requesting and the
96 \fIappdata_ptr\fR
97 that the application has associated with the current
98 \fIpamh\fR\&. This last value was set by the application when it called
99 \fBpam_start\fR(3)
100 or explicitly with
101 \fBpam_set_item\fR(3)\&.
102 .PP
103 Note that the PAM_FAIL_DELAY item is set to NULL by default\&. This indicates that PAM should perform a random delay as described above when authentication fails and a delay has been suggested\&. If an application does not want the PAM library to perform any delay on authentication failure, then the application must define a custom delay function that executes no statements and set the PAM_FAIL_DELAY item to point to this function\&.
104 .SH "RATIONALE"
105 .PP
106 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
107 \fIshort\fR
108 timeouts, it may prove possible to attempt a
109 \fIbrute force\fR
110 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
111 \fIcovert channel\fR
112 of useful information\&.
113 .PP
114 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\&.
115 .SH "EXAMPLE"
116 .PP
117 For example, a login application may require a failure delay of roughly 3 seconds\&. It will contain the following code:
118 .sp
119 .if n \{\
120 .RS 4
121 .\}
122 .nf
123 pam_fail_delay (pamh, 3000000 /* micro\-seconds */ );
124 pam_authenticate (pamh, 0);
125
126 .fi
127 .if n \{\
128 .RE
129 .\}
130 .PP
131 if the modules do not request a delay, the failure delay will be between 1\&.5 and 4\&.5 seconds\&.
132 .PP
133 However, the modules, invoked in the authentication process, may also request delays:
134 .sp
135 .if n \{\
136 .RS 4
137 .\}
138 .nf
139 module #1: pam_fail_delay (pamh, 2000000);
140 module #2: pam_fail_delay (pamh, 4000000);
141
142 .fi
143 .if n \{\
144 .RE
145 .\}
146 .PP
147 in this case, it is the largest requested value that is used to compute the actual failed delay: here between 2 and 6 seconds\&.
148 .SH "RETURN VALUES"
149 .PP
150 PAM_SUCCESS
151 .RS 4
152 Delay was successful adjusted\&.
153 .RE
154 .PP
155 PAM_SYSTEM_ERR
156 .RS 4
157 A NULL pointer was submitted as PAM handle\&.
158 .RE
159 .SH "SEE ALSO"
160 .PP
161 \fBpam_start\fR(3),
162 \fBpam_get_item\fR(3),
163 \fBpam_strerror\fR(3)
164 .SH "STANDARDS"
165 .PP
166 The
167 \fBpam_fail_delay\fR
168 function is an Linux\-PAM extension\&.