Previous page Next page Table of contents

2. The public interface to Linux-PAM

Firstly, the relevant include file for the Linux-PAM library is <security/pam_appl.h>. It contains the definitions for a number of functions. Before listing these functions, we collect some guiding remarks for programmers.

2.1 Programming notes

In general writers of authorization-granting applications should assume that each module is likely to call any or all `libc' functions. For `libc' functions that return pointers to static/dynamically allocated structures (ie. the library allocates the memory and the user is not expected to `free()' it) any module call to this function is likely to corrupt a pointer previously obtained by the application. The application programmer should either re-call such a libc function after any call to the Linux-PAM library, or copy the structure contents to some safe area of memory before passing control to the Linux-PAM library.

2.2 What can be expected by the application

Here we document those functions in the Linux-PAM library that may be called from an application.

2.3 What is expected of an application

An application must provide a ``conversation function''. It is used for direct communication between a loaded module and the application and will typically provide a means for the module to prompt the user for a password etc. . The structure pam_conv is defined in <security/pam_appl.h> to be,

struct pam_conv {
    int (*conv)(int num_msg,
        const struct pam_message **msg,
        struct pam_response **resp,
        void *appdata_ptr);
    void *appdata_ptr;
};

It is initialized by the application before it is passed to the library. The contents of this structure are attached to the *pamh handle. The point of this argument is to provide a mechanism for any loaded module to interact directly with the application program. This is why it is called a conversation structure.

When a module calls the referenced conv() function, the argument *appdata_ptr is set to the second element of this structure.

The other arguments of a call to conv() concern the information exchanged by module and application. That is to say, num_msg holds the length of the array of pointers, msg. After a successful return, the pointer *resp points to a pam_response structure, holding the application supplied text.

The message (from the module to the application) passing structure is defined in <security/pam_appl.h> as:

struct pam_message {
    int msg_style;
    char *msg;
};

Valid choices for msg_style are:

PAM_PROMPT_ECHO_OFF

Obtain a string without echoing any text

PAM_PROMPT_ECHO_ON

Obtain a string whilst echoing text

PAM_ERROR_MSG

Display an error

PAM_TEXT_INFO

Display some text.

The response (from the application to the module) passing structure is defined in <security/pam_appl.h> as:

struct pam_response {
    char *resp;
    int resp_retcode;
};

Currently, there are no definitions for resp_retcode values. The normal response is 0. XXX - see notes


Previous page Next page Table of contents