Unix Incompatibility Notes:
PAM Pluggable Authentication Module

With PAM the authenticators are implemented as dynamically-linked shared library files. A single standard API is used by all authentication programs, and a configuration file read at run time determines which authenticators are actually used for each program. Thus you can revise how authentication works by just installing new modules and/or editting the configuration files. You don't need to rebuild the application programs.

PAM was originally developed by Sun for Solaris. A DCE/OSF-RFC document describes it (not completely accurately). An open source version called Linux-PAM is widely used, and can be installed on most versions of Unix, not just Linux. It is standard on recent Linux distributions, FreeBSD 3.1 or greater, and probably lots of others. A newer open source version called OpenPAM is used in FreeBSD 5.0 and later. HP-UX supports PAM, but I have no experience with their version.

The normal config file formats for Linux and Solaris PAM are slightly different, and the names of the standard modules are entirely different. There are probably interesting portability issues involved in writing PAM modules which I haven't studied. This page discusses mainly the issues involved in invoking PAM modules.

Things to be aware of:

• As dynamically-linked libraries, PAM modules have the same access rights as the calling program. For example, a PAM module for authenticating from a shadow password file, which is only readable by root, will always fail if the calling program is not running as root.

• The third argument to pam_start() is a pointer to a struct pam_conv. This structure contains a pointer to the conversation function, and a void application data pointer. You are supposed to be able to use the application data pointer to pass information through to the conversation function. In the Solaris 2.6 version of PAM, this does not work. The application data passed to the conversation function will be NULL no matter what you set in the conversation structure that you pass to pam_start. This does work correctly in Linux-PAM, OpenPAM and Solaris 7 PAM.

• When the conversation function is called, it is passed an array of prompts. This is always passed in as struct pam_message **mesg. However, the interpretation varies. In Linux-PAM and OpenPAM this is a pointer to an array of pointers to pam_message structures, whereas in Solaris it is a pointer to a pointer to an array of pam_message structures. Frequently there is only one prompt being passed in, so it doesn't matter. Under either interpretation, the first structure is addressable as **msg. However, accessing subsequent elements is different. In Linux-PAM and OpenPAM, the second element is at *(msg[2]), while in Solaris it is at (*msg)[2].

  If you're writing a conversation function, there is little you can do about this other than put in some system dependent #ifdefs, but authors of modules can write code that works under both interpretations. The simplest way is never to pass more than one prompt to the conversation function - if you need to pass more, call the conversation function more than once. A more devious trick is to store the pam_message structures in an array, then create an array of pam_message * pointers with each pointer pointing to the corresponding pam_message structure. If a pointer the pointer array is passed to the conversation function, things will work right under either interpretation.

• The RFC specifies the syntax of the pam_strerror() function as:

       char *pam_strerror(int errnum);

  Versions of Linux-PAM before 0.59 implemented it this way. However, no Solaris versions ever did, and later versions of Linux-PAM have changed too. It is now:

       char *pam_strerror(pam_handle_t *pamh, int errnum);