Parameter Passing Conventions in PAM

Structured Data Types

Wherever these PAM-API C-bindings describe structured data, only fields that must be provided by all PAM-API implementations are documented. Individual implementations may provide additional fields, either for internal use within PAM-API routines, or for use by non-portable applications.

Messages

The structure pam_message is used to pass prompt, error message, or any text information from the PAM services to the application or user. It is the responsibility of the PAM service modules to localize the messages. The memory used by pam_message has to be allocated and freed by the PAM modules. The pam_message structure has the following structure:

 

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

The msg_style can be set to a number of values. See Message Constants . The structure pam_response is used to get the response back from the application or user. The storage used by pam_response has to be allocated by the application and freed by the PAM modules. It is defined as:

 

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

Call Back Information

The structure pam_conv contains the address of the conversation function provided by the application. The underlying PAM service module invokes this function to output information to and retrieve input from the user. The pam_conv structure has the following entries:

 

struct pam_conv{
    int (*conv) (int, struct pam_message **,
          struct pam_response **, void *);
    void *appdata_ptr;
};

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

The function, conv() is called by a service module to hold a PAM conversation with the application or user. For window applications, the application can create a new pop-up window to be used by the interaction.

The parameter, num_msg is the number of messages associated with the call. The parameter, msg, is a pointer to an array of length num_msg of the pam_message structure.

appdata_ptr is an application data pointer which is passed by the application to the PAM service modules. Since the PAM modules pass it back through the conversation function, the applications can use this pointer to point to any application-specific data.

Opaque Data Types

pam_handle

This is opaque to the caller and returned to the caller upon initiation of a PAM session. It is subsequently passed as a parameter to each PAM-API call.

Status Values

One or more status codes are returned by each PAM-API routine. An implementation of PAM functions shall return PAM_SUCCESS and other status values appropriate for the implementation of the function. The characteristics of a particular implementation may make some status returns inappropriate for that implementation.

PAM Status Codes

PAM-API routines return PAM status codes as their int function value. These codes indicate major status errors that are independent of the underlying mechanism used to provide the security service.

Constants

Flags

Item_type

PAM Configuration Entry Constants

<service_name> <module_type> <control_flag> <module_path> <options>

An entry commencing with a "#" character will be ignored.

The following subsections define the string constants that are used within a PAM configuration entry.

Service Name

The keyword, other, indicates the module that should be used for all applications which have not been included in the PAM configuration under a specific service name. The other keyword can also be used if all services using the same module_type have the same requirements.

Module Type

Control Flags

The PAM framework processes each service module in the stack.

If a requisite module fails the PAM framework immediately returns to the application with the error returned by the requisite module and stops processing the module stack.

If all requisite and required modules in the stack succeed, then success is returned (optional and sufficient error values are ignored).

If one or more required modules fail, then the error value from the first required module that failed is returned.

If none of the service modules in the stack are designated as required or requisite, then the PAM framework requires that at least one optional or sufficient module succeed. If all fail then the error value from the first service module in the stack is returned.

The exception to the above is caused by the sufficient flag. If a service module that is designated as sufficient succeeds, then the PAM framework immediately returns success to the application (all subsequent service modules, even required and requisite ones, in the stack are ignored), given that all prior required and requisite modules have also succeeded. If a prior required module failed, then the error value from that module is returned.

If a module does not exist or cannot be opened, then the entry is ignored.

Module Path

The PAM configuration syntax does not dictate either the name or the location of the service specific modules. The convention, however, is the following:

/usr/lib/security/pam_<service_name>_<module_name>.<extension>

Options

The options field is used by the PAM framework layer to pass module specific options to the modules. It is up to the module to parse and interpret the options. This field can be used by the modules to turn on debugging or to pass any module specific parameters such as a TIMEOUT value. It can also be used to support unified login. The options supported by a modules shall be documented by the supplier of the module.