NAME

pam_start - initiate a PAM transaction

SYNOPSIS

#include <security/pam_appl.h>

int pam_start (
    const char               *service,
    const har                *user,
    const struct pam_conv    *pam_conv,
    pam_handle_t            **pamh
);

DESCRIPTION

The pam_start() function initiates a PAM transaction. On successful completion, pamh refers to a PAM handle for use with subsequent calls to the authentication library.

The arguments for pam_start() are:

service (in)

The name of the current service.

user (in)

The name of the user to be authenticated.

pam_conv (in)

The address of the conversation structure.

pamh (out)

The pam authentication handle is returned. This is then used for all subsequent calls to the authentication library.

The pam_conv 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)();        /* Conversation function */
    void    (**appdata_ptr;    /* Application data */
};
    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.

The structure pam_message is used to pass prompt, error message, or any text information from the authentication service 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 entries:

 

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

The message style, msg_style, can be set to one of the following values:

PAM_PROMPT_ECHO_OFF

Prompt user, disabling echoing of response.

PAM_PROMPT_ECHO_ON

Prompt user, enabling echoing of response.

PAM_ERROR_MSG

Print error message.

PAM_TEXT_INFO

Print general text information.

The maximum size of the message and the response string is PAM_MAX_MSG_SIZE defined in <security/pam_appl.h>.

The structure pam_response is used by the authentication service to get the user's 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. The pam_response structure has the following entries:

 

struct pam_response{
    char (**resp;
    int     resp_retcode;  /* currently not used, should be set to 0 */
};

It is the responsibility of the conversation function to strip off newline characters for PAM_PROMPT_ECHO_OFF and PAM_PROMPT_ECHO_ON message styles, and to add newline characters (if appropriate) for PAM_ERROR_MSG and PAM_TEXT_INFO message styles.

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.

pam_end() is called to terminate the authentication transaction identified by pamh and to free any storage area allocated by the authentication module. The argument, status, is passed to the cleanup() function stored within the pam handle, and is used to determine what module-specific state must be purged. A cleanup function is attached to the handle by the underlying PAM modules through a call to pam_set_item() to free module-specific data.

RETURN VALUE

The following PAM status codes shall be returned:

[PAM_SUCCESS]

Successful completion.

[PAM_SERVICE_ERR]

Error in underlying service module.

[PAM_SYSTEM_ERR]

System error.

[PAM_BUF_ERR]

Memory buffer error.

[??] Some characters or strings that appear in the printed document are not easily representable using HTML.