Next Previous Contents

2. What can be expected by the module

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

2.1 Getting and setting PAM{[lowbar]}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.

Setting data

Synopsis:

extern int pam_set_data(pam_handle_t *pamh,
                        const char *module_data_name,
                        void *data,
                        void (*cleanup)(pam_handle_t *pamh,
                                        void *data, int error_status) );

The modules may be dynamically loadable objects. In general such files should not contain static variables. This and the subsequent function provide a mechanism for a module to associate some data with the handle pamh. Typically a module will call the pam{[lowbar]}set{[lowbar]}data() function to register some data under a (hopefully) unique module{[lowbar]}data{[lowbar]}name. The data is available for use by other modules too but not by an application.

The function cleanup() is associated with the data and, if non-NULL, it is called when this data is over-written or following a call to pam{[lowbar]}end() (see the Linux-PAM Application Developers' Guide).

The error{[lowbar]}status argument is used to indicate to the module the sort of action it is to take in cleaning this data item. As an example, Kerberos creates a ticket file during the authentication phase, this file might be associated with a data item. When pam{[lowbar]}end() is called by the module, the error{[lowbar]}status carries the return value of the pam{[lowbar]}authenticate() or other libpam function as appropriate. Based on this value the Kerberos module may choose to delete the ticket file (authentication failure) or leave it in place.

The error{[lowbar]}status may have been logically OR'd with either of the following two values:

PAM{[lowbar]}DATA{[lowbar]}REPLACE

When a data item is being replaced (through a second call to pam{[lowbar]}set{[lowbar]}data()) this mask is used. Otherwise, the call is assumed to be from pam{[lowbar]}end().

PAM{[lowbar]}DATA{[lowbar]}SILENT

Which indicates that the process would prefer to perform the cleanup() quietly. That is, discourages logging/messages to the user.

Getting data

Synopsis:

extern int pam_get_data(const pam_handle_t *pamh,
                        const char *module_data_name,
                        const void **data);

This function together with the previous one provides a method of associating module-specific data with the handle pamh. A successful call to pam{[lowbar]}get{[lowbar]}data will result in *data pointing to the data associated with the module{[lowbar]}data{[lowbar]}name. Note, this data is not a copy and should be treated as constant by the module.

Note, if there is an entry but it has the value NULL, then this call returns PAM{[lowbar]}NO{[lowbar]}MODULE{[lowbar]}DATA.

Setting items

Synopsis:

extern int pam_set_item(pam_handle_t *pamh,
                        int item_type,
                        const void *item);

This function is used to (re)set the value of one of the item{[lowbar]}types. The reader is urged to read the entry for this function in the Linux-PAM application developers' manual.

In addition to the items listed there, the module can set the following two item{[lowbar]}types:

PAM{[lowbar]}AUTHTOK

The authentication token (often a password). This token should be ignored by all module functions besides pam{[lowbar]}sm{[lowbar]}authenticate() and pam{[lowbar]}sm{[lowbar]}chauthtok(). In the former function it is used to pass the most recent authentication token from one stacked module to another. In the latter function the token is used for another purpose. It contains the currently active authentication token.

PAM{[lowbar]}OLDAUTHTOK

The old authentication token. This token should be ignored by all module functions except pam{[lowbar]}sm{[lowbar]}chauthtok().

Both of these items are reset before returning to the application. When resetting these items, the Linux-PAM library first writes 0's to the current tokens and then free()'s the associated memory.

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

Getting items

Synopsis:

extern int pam_get_item(const pam_handle_t *pamh,
                        int item_type,
                        const void **item);

This function is used to obtain the value of the specified item{[lowbar]}type. It is better documented in the Linux-PAM Application Developers' Guide. However, there are three things worth stressing here:

The conversation mechanism

Following the call pam{[lowbar]}get{[lowbar]}item(pamh,PAM{[lowbar]}CONV,{[amp ]}item), the pointer item points to a structure containing an a pointer 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{[lowbar]}conv structure, written from the perspective of the application developer, in the Linux-PAM Application Developers' Guide.

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

The pam{[lowbar]}response structure returned after a call to the pam{[lowbar]}conv function must be free()'d by the module. Since the call to the conversation function originates from the module, it is clear that this pam{[lowbar]}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{[lowbar]}conv mechanism is used to enter authentication tokens, the module should either pass the result to the pam{[lowbar]}set{[lowbar]}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.

There is a handy macro {[lowbar]}pam{[lowbar]}drop{[lowbar]}reply() to be found in {[lt ]}security/{[lowbar]}pam{[lowbar]}macros.h{[gt ]} that can be used to conveniently cleanup a pam{[lowbar]}response structure. (Note, this include file is specific to the Linux-PAM sources, and whilst it will work with Sun derived PAM implementations, it is not generally distributed by Sun.)

Getting the name of a user

Synopsis:

extern int pam_get_user(pam_handle_t *pamh, 
                        const char **user,
                        const char *prompt);

This is a Linux-PAM library function that returns the (prospective) name of the user. To determine the username it does the following things, in this order:

By whatever means the username is obtained, a pointer to it is returned as the contents of *user. Note, this memory should not be free()'d by the module. Instead, it will be liberated on the next call to pam{[lowbar]}get{[lowbar]}user(), or by pam{[lowbar]}end() when the application ends its interaction with Linux-PAM.

Also, in addition, it should be noted that this function sets the PAM{[lowbar]}USER item that is associated with the pam{[lowbar]}[gs]et{[lowbar]}item() function.

The return value of this function is one of the following:

Setting a Linux-PAM environment variable

Synopsis:

extern int pam_putenv(pam_handle_t *pamh, const char *name_value);

Linux-PAM comes equipped with a series of functions for maintaining a set of environment variables. The environment is initialized by the call to pam{[lowbar]}start() and is erased with a call to pam{[lowbar]}end(). This environment is associated with the pam{[lowbar]}handle{[lowbar]}t pointer returned by the former call.

The default environment is all but empty. It contains a single NULL pointer, which is always required to terminate the variable-list. The pam{[lowbar]}putenv() function can be used to add a new environment variable, replace an existing one, or delete an old one.

In all cases PAM{[lowbar]}SUCCESS indicates success.

Getting a Linux-PAM environment variable

Synopsis:

extern const char *pam_getenv(pam_handle_t *pamh, const char *name);

This function can be used to return the value of the given variable. If the returned value is NULL, the variable is not known.

Listing the Linux-PAM environment

Synopsis:

extern char * const *pam_getenvlist(pam_handle_t *pamh);

This function returns a pointer to the entire Linux-PAM environment array. At first sight the type of the returned data may appear a little confusing. It is basically a read-only array of character pointers, that lists the NULL terminated list of environment variables set so far.

Although, this is not a concern for the module programmer, we mention here that an application should be careful to copy this entire array before executing pam{[lowbar]}end() otherwise all the variable information will be lost. (There are functions in libpam{[lowbar]}misc for this purpose: pam{[lowbar]}misc{[lowbar]}copy{[lowbar]}env() and pam{[lowbar]}misc{[lowbar]}drop{[lowbar]}env().)

2.2 Other functions provided by libpam

Understanding errors

Planning for delays


Next Previous Contents