3. What is expected of a module

Contents of this section

The module must supply a sub-set of the six functions listed below. Together they define the function of a Linux-PAM module. Module developers are strongly urged to read the comments on security that follow this list.

3.1 Overview

The six module functions are grouped into four independent management groups. These groups are as follows: authentication, account, session and password. To be properly defined, a module must define all functions within at least one of these groups. A single module may contain the necessary functions for all four groups.

Functional independence

The independence of the four groups of service a module can offer means that the module should allow for the possibility that any one of these four services may legitimately be called in any order. Thus, the module writer should consider the appropriateness of performing a service without the prior success of some other part of the module.

As an informative example, consider the possibility that an application applies to change a user's authentication token, without having first requested that Linux-PAM authenticate the user. In some cases this may be deemed appropriate: when root wants to change the authentication token of some lesser user. In other cases it may not be appropriate: when joe maliciously wants to reset alice's password; or when anyone other than the user themself wishes to reset their KERBEROS authentication token. A policy for this action should be defined by any reasonable authentication scheme, the module writer should consider this when implementing a given module.

Minimizing administration problems

To avoid system administration problems and the poor construction of a /etc/pam.conf file, the module developer may define all six of the following functions. For those functions that would not be called, the module should return PAM_SERVICE_ERR and write an appropriate message to the system log. When this action is deemed inappropriate, the function would simply return PAM_IGNORE.

Arguments supplied to the module

The flags argument of each of the following functions can be logically OR'd with PAM_SILENT, which is used to inform the module to not pass any text (errors or warnings) to the application.

The argc and argv arguments are taken from the line appropriate to this module---that is, with the service_name matching that of the application---in the configuration file (see the Linux-PAM System Administrators' Guide). Together these two parameters provide the number of arguments and an array of pointers to the individual argument tokens. This will be familiar to C programmers as the ubiquitous method of passing command arguments to the function main(). Note, however, that the first argument (argv[0]) is a true argument and not the name of the module.

Added requirements for statically loaded modules.

Modules may be statically linked into libpam. This should be true of all the modules distributed with the basic Linux-PAM distribution. To be statically linked, a module needs to export information about the functions it contains in a manner that does not clash with other modules.

The extra code necessary to build a static module should be delimited with #ifdef PAM_STATIC and #endif. The static code should do the following:

As a simple example, consider the following module code which defines a module that can be compiled to be static or dynamic:

#include <stdio.h>                                    /* for NULL define */

#define PAM_SM_PASSWORD         /* the only pam_sm_... function declared */
#include <security/pam_modules.h>

PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags,
                                int argc, const char **argv)
{
     return PAM_SUCCESS;
}

#ifdef PAM_STATIC             /* for the case that this module is static */

struct pam_module _pam_modname_modstruct = {       /* static module data */
     "pam_modname",
     NULL,
     NULL,
     NULL,
     NULL,
     NULL,
     pam_sm_chauthtok,
};

#endif                                                 /* end PAM_STATIC */

To be linked with libpam, staticly-linked modules must be built from within the Linux-PAM-X.YY/modules/ subdirectory of the Linux-PAM source directory as part of a normal build of the Linux-PAM system.

The Makefile, for the module in question, must execute the register_static shell script that is located in the Linux-PAM-X.YY/modules/ subdirectory. This is to ensure that the module is properly registered with libpam.

The two manditory arguments to register_static are the title, and the pathname of the object file containing the module's code. The pathname is specified relative to the Linux-PAM-X.YY/modules directory. The pathname may be an empty string---this is for the case that a single object file needs to register more than one struct pam_module. In such a case, exactly one call to register_static must indicate the object file.

Here is an example; a line in the Makefile might look like this:

register:
ifdef STATIC
        (cd ..; ./register_static pam_modname pam_modname/pam_modname.o)
endif

For some further examples, see the modules subdirectory of the current Linux-PAM distribution.

3.2 Authentication management

To be correctly initialized, PAM_SM_AUTH must be #define'd prior to including <security/pam_modules.h>. This will ensure that the prototypes for static modules are properly declared.

3.3 Account management

To be correctly initialized, PAM_SM_ACCOUNT must be #define'd prior to including <security/pam_modules.h>. This will ensure that the prototype for a static module is properly declared.

3.4 Session management

To be correctly initialized, PAM_SM_SESSION must be #define'd prior to including <security/pam_modules.h>. This will ensure that the prototypes for static modules are properly declared.

The following two functions are defined to handle the initialization/termination of a session. For example, at the beginning of a session the module may wish to log a message with the system regarding the user. Similarly, at the end of the session the module would inform the system that the user's session has ended.

It should be possible for sessions to be opened by one application and closed by another. This either requires that the module uses only information obtained from pam_get_item(), or that information regarding the session is stored in some way by the operating system (in a file for example).

3.5 Password management

To be correctly initialized, PAM_SM_PASSWORD must be #define'd prior to including <security/pam_modules.h>. This will ensure that the prototype for a static module is properly declared.


Next Chapter, Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter