{ "content": [ { "type": "text", "text": "# pam_fail_delay (man)\n\n## NAME\n\npamfaildelay - request a delay on failure\n\n## SYNOPSIS\n\n#include \nint pamfaildelay(pamhandlet *pamh, unsigned int usec);\n\n## DESCRIPTION\n\nThe pamfaildelay function provides a mechanism by which an application or module can\nsuggest a minimum delay of usec micro-seconds. The function keeps a record of the longest\ntime requested with this function. Should pamauthenticate(3) fail, the failing return to the\napplication is delayed by an amount of time randomly distributed (by up to 50%) about this\nlongest value.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **RATIONALE**\n- **EXAMPLE**\n- **RETURN VALUES**\n- **SEE ALSO**\n- **STANDARDS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "pam_fail_delay", "section": "", "mode": "man", "summary": "pamfaildelay - request a delay on failure", "synopsis": "#include \nint pamfaildelay(pamhandlet *pamh, unsigned int usec);", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "For example, a login application may require a failure delay of roughly 3 seconds. It will", "contain the following code:", "pamfaildelay (pamh, 3000000 /* micro-seconds */ );", "pamauthenticate (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: pamfaildelay (pamh, 2000000);", "module #2: pamfaildelay (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." ], "see_also": [ { "name": "pamstart", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/pamstart/3/json" }, { "name": "pamgetitem", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/pamgetitem/3/json" }, { "name": "pamstrerror", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/pamstrerror/3/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 4, "subsections": [] }, { "name": "DESCRIPTION", "lines": 40, "subsections": [] }, { "name": "RATIONALE", "lines": 12, "subsections": [] }, { "name": "EXAMPLE", "lines": 18, "subsections": [] }, { "name": "RETURN VALUES", "lines": 6, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "STANDARDS", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "pamfaildelay - request a delay on failure\n", "subsections": [] }, "SYNOPSIS": { "content": "#include \n\nint pamfaildelay(pamhandlet *pamh, unsigned int usec);\n", "subsections": [] }, "DESCRIPTION": { "content": "The pamfaildelay function provides a mechanism by which an application or module can\nsuggest a minimum delay of usec micro-seconds. The function keeps a record of the longest\ntime requested with this function. Should pamauthenticate(3) fail, the failing return to the\napplication is delayed by an amount of time randomly distributed (by up to 50%) about this\nlongest value.\n\nIndependent of success, the delay time is reset to its zero default value when the PAM\nservice module returns control to the application. The delay occurs after all authentication\nmodules have been called, but before control is returned to the service application.\n\nWhen using this function the programmer should check if it is available with:\n\n#ifdef HAVEPAMFAILDELAY\n....\n#endif /* HAVEPAMFAILDELAY */\n\n\nFor applications written with a single thread that are event driven in nature, generating\nthis delay may be undesirable. Instead, the application may want to register the delay in\nsome other way. For example, in a single threaded server that serves multiple authentication\nrequests from a single event loop, the application might want to simply mark a given\nconnection as blocked until an application timer expires. For this reason the delay function\ncan be changed with the PAMFAILDELAY item. It can be queried and set with pamgetitem(3)\nand pamsetitem(3) respectively. The value used to set it should be a function pointer of\nthe following prototype:\n\nvoid (*delayfn)(int retval, unsigned usecdelay, void *appdataptr);\n\n\nThe arguments being the retval return code of the module stack, the usecdelay micro-second\ndelay that libpam is requesting and the appdataptr that the application has associated with\nthe current pamh. This last value was set by the application when it called pamstart(3) or\nexplicitly with pamsetitem(3).\n\nNote that the PAMFAILDELAY item is set to NULL by default. This indicates that PAM should\nperform a random delay as described above when authentication fails and a delay has been\nsuggested. If an application does not want the PAM library to perform any delay on\nauthentication failure, then the application must define a custom delay function that\nexecutes no statements and set the PAMFAILDELAY item to point to this function.\n", "subsections": [] }, "RATIONALE": { "content": "It is often possible to attack an authentication scheme by exploiting the time it takes the\nscheme to deny access to an applicant user. In cases of short timeouts, it may prove possible\nto attempt a brute force dictionary attack -- with an automated process, the attacker tries\nall possible passwords to gain access to the system. In other cases, where individual\nfailures can take measurable amounts of time (indicating the nature of the failure), an\nattacker can obtain useful information about the authentication process. These latter attacks\nmake use of procedural delays that constitute a covert channel of useful information.\n\nTo minimize the effectiveness of such attacks, it is desirable to introduce a random delay in\na failed authentication process. Preferable this value should be set by the application or a\nspecial PAM module. Standard PAM modules should not modify the delay unconditional.\n", "subsections": [] }, "EXAMPLE": { "content": "For example, a login application may require a failure delay of roughly 3 seconds. It will\ncontain the following code:\n\npamfaildelay (pamh, 3000000 /* micro-seconds */ );\npamauthenticate (pamh, 0);\n\n\nif the modules do not request a delay, the failure delay will be between 1.5 and 4.5 seconds.\n\nHowever, the modules, invoked in the authentication process, may also request delays:\n\nmodule #1: pamfaildelay (pamh, 2000000);\nmodule #2: pamfaildelay (pamh, 4000000);\n\n\nin this case, it is the largest requested value that is used to compute the actual failed\ndelay: here between 2 and 6 seconds.\n", "subsections": [] }, "RETURN VALUES": { "content": "PAMSUCCESS\nDelay was successful adjusted.\n\nPAMSYSTEMERR\nA NULL pointer was submitted as PAM handle.\n", "subsections": [] }, "SEE ALSO": { "content": "pamstart(3), pamgetitem(3), pamstrerror(3)\n", "subsections": [] }, "STANDARDS": { "content": "The pamfaildelay function is an Linux-PAM extension.\n\n\n\nLinux-PAM Manual 06/08/2020 PAMFAILDELAY(3)", "subsections": [] } } } }