2. What can be expected by the module

Contents of this section

Here we list the interface that the conventions that all Linux-PAM modules must adhere to.

2.1 Getting and setting PAM_ITEMs and data

First, we cover what the module should expect from the Linux-PAM library and a Linux-PAM aware application. Essesntially this is the libpam.* library.

The conversation mechanism

Following the call pam_get_item(pamh,PAM_CONV,&item), the pointer item points to a conversation-function that provides limited but direct access to the application. The purpose of this function is to allow the module to prompt the user for their password and pass other information in a manner consistent with the application. For example, an X-windows based program might pop up a dialog box to report a login failure. Just as the application should not be concerned with the method of authentication, so the module should not dictate the manner in which input (output) is obtained from (presented to) to the user.

The reader is strongly urged to read the more complete description of the pam_conv structure, written from the perspective of the application developer, in the Linux-PAM Application Developers' Guide.

The pam_response structure returned after a call to the pam_conv function must be free()'d by the module. Since the call to the conversation function originates from the module, it is clear that either this pam_response structure could be either statically or dynamically (using malloc() etc.) allocated within the application. Repeated calls to the conversation function would likely overwrite static memory, so it is required that for a successful return from the conversation function the memory for the response structure is dynamically allocated by the application with one of the malloc() family of commands and must be free()'d by the module.

If the pam_conv mechanism is used to enter authentication tokens, the module should either pass the result to the pam_set_item() library function, or copy it itself. In such a case, once the token has been stored (by one of these methods or another one), the memory returned by the application should be overwritten with 0's, and then free()'d.

The return values for this function are listed in the Linux-PAM Application Developers' Guide.

Getting the name of a user

2.2 Other functions provided by libpam

Undserstanding errors

Planning for delays

*** WARNING *** THIS IS LIKELY TO BE REMOVED BY THE TIME WE GET TO Linux-PAM-1.0


Next Chapter, Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter