From 9ada0093e92388590c7368600ca4e9e3e376f0d0 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 16:22:51 +0200 Subject: Adding upstream version 1.5.2. Signed-off-by: Daniel Baumann --- doc/man/pam_fail_delay.3.xml | 209 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 doc/man/pam_fail_delay.3.xml (limited to 'doc/man/pam_fail_delay.3.xml') diff --git a/doc/man/pam_fail_delay.3.xml b/doc/man/pam_fail_delay.3.xml new file mode 100644 index 0000000..53c1f89 --- /dev/null +++ b/doc/man/pam_fail_delay.3.xml @@ -0,0 +1,209 @@ + + + + + + + pam_fail_delay + 3 + Linux-PAM Manual + + + + pam_fail_delay + request a delay on failure + + + + + + + #include <security/pam_appl.h> + + int pam_fail_delay + pam_handle_t *pamh + unsigned int usec + + + + + + DESCRIPTION + + The pam_fail_delay function provides a + mechanism by which an application or module can suggest a minimum + delay of usec micro-seconds. The + function keeps a record of the longest time requested with this + function. Should + + pam_authenticate3 + fail, the failing return to the application is + delayed by an amount of time randomly distributed (by up to 50%) + about this longest value. + + + 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 after all + authentication modules have been called, but before + control is returned to the service application. + + + When using this function the programmer should check if it is + available with: + + +#ifdef HAVE_PAM_FAIL_DELAY + .... +#endif /* HAVE_PAM_FAIL_DELAY */ + + + + 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 + PAM_FAIL_DELAY item. It can be queried and + set with + + pam_get_item3 + + and + + pam_set_item3 + respectively. The value used to set it should be + a function pointer of the following prototype: + +void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr); + + The arguments being the retval return code + of the module stack, the usec_delay + micro-second delay that libpam is requesting and the + appdata_ptr that the application has associated + with the current pamh. This last value was set + by the application when it called + + pam_start3 + or explicitly with + + pam_set_item3 + . + + + 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. + + + + + RATIONALE + + 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 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 covert channel + of useful information. + + + 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. + + + + + 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 1.5 and 4.5 seconds. + + + + However, the modules, invoked in the authentication process, 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 2 and 6 seconds. + + + + + RETURN VALUES + + + PAM_SUCCESS + + + Delay was successful adjusted. + + + + + PAM_SYSTEM_ERR + + + A NULL pointer was submitted as PAM handle. + + + + + + + + SEE ALSO + + + pam_start3 + , + + pam_get_item3 + , + + pam_strerror3 + + + + + + STANDARDS + + The pam_fail_delay function is an + Linux-PAM extension. + + + + -- cgit v1.2.3