2.2 Other functions provided by libpam

Understanding errors

• extern const char *pam_strerror(int errnum);

  This function returns some text describing the Linux-PAM error associated with the argument errnum. If the error is not recognized ``Unknown Linux-PAM error'' is returned.

Planning for delays

• extern int pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec)

  This function is offered by Linux-PAM to facilitate time delays following a failed call to pam_authenticate() and before control is returned to the application.

  Generally, an application requests that a user is authenticated by Linux-PAM through a call to pam_authenticate() or pam_chauthtok(). These functions calls each of the stacked authentication modules listed in the /etc/pam.conf file. As directed by this file, one of more of the modules may fail causing the pam_...() call to return an error. It is desirable for there to also be a pause before the application continues. The principal reason for such a delay is security: a delay acts to discourage brute force dictionary attacks primarily, but also helps hinder timed (covert channel) attacks.

  The pam_fail_delay() function provides the mechanism by which an application or module can suggest a minimum delay (of micro_sec micro-seconds). Linux-PAM keeps a record of the longest time requested with this function. Should pam_authenticate() fail, the failing return to the application is delayed by an amount of time randomly distributed (by up to 25%) about this longest value.

  Independent of success, the delay time is reset to its zero default value when Linux-PAM returns control to the application.