pam_start Subroutine

Purpose

Initiates a new PAM user authentication session.

Library

PAM Library (libpam.a)

Syntax

#include <security/pam_appl.h>

int pam_start (Service, User, Conversation, PAMHandle)
const char *Service;
const char *User;
const struct pam_conv *Conversation;
pam_handle_t **PAMHandle;

Description

The pam_start subroutine begins a new PAM session for authentication within one of the four realms of the PAM environment [authentication, account, session, password]. This routine is called only at the start of the session, not at the start of each module comprising the session. The PAM handle, PAMHandle, returned by this subroutine is subsequently used by other PAM routines. The handle must be cleaned up at the end of use, which can easily be done by passing it as an argument to pam_end.

Parameters

Item Description
Service The name of the service initiating this PAM session.
User The user who is being authenticated.
Conversation The PAM conversation struct enabling communication with the user. This structure, pam_conv, consists of a pointer to a conversation function, as well as a pointer to application data. 
struct pam_conv {
    int (**conv)();
    void (**appdata_ptr);
}
The argument conv is defined as: 
int conv( int num_msg, const struct pam_message **msg,
          const struct pam_response **resp, void *appdata );
The conversation function, conv, allows PAM to send messages to, and get input from, a user. The arguments to the function have the following definition and behavior:
num_msg
The number of lines of messages to be displayed (all messages are returned in one-line fragments, each no longer than PAM_MAX_MSG_SIZE characters and with no more lines than PAM_MAX_NUM_MSG)
msg
Contains the message text and its style. 
struct pam_message {
    int style;    /* Message style */
    char *msg;    /* The message */
}
The message style, can be one of:
PAM_PROMPT_ECHO_OFF
Prompts users with message and does not echo their responses; it is typically for use with requesting passwords and other sensitive information.
PAM_PROMPT_ECHO_ON
Prompts users with message and echoes their responses back to them.
PAM_ERROR_MSG
Displays message as an error message.
PAM_TEXT_INFO
Displays general information, such as authentication failures.
resp
Holds the user's response and a response code. 
struct pam_response {
    char **resp;       /* Reference to the response */
    int resp_retcode;  /* Not used, should be 0 */
}
appdata, appdata_ptr
Pointers to the application data that can be passed by the calling application to the PAM modules. Use these to allow PAM to send data back to the application.
PAMHandle The PAM handle representing the current user authentication session is returned upon successful completion.

Return Values

Upon successful completion, pam_start returns PAM_SUCCESS, and a reference to the pointer of a valid PAM handle is returned through PAMHandle. If the routine fails, a value different from PAM_SUCCESS is returned, and the PAMHandle reference is NULL.

Error Codes

Item Description
PAM_SERVICE_ERR An error occurred in a PAM module.
PAM_SYSTEM_ERR A system error occurred.
PAM_BUF_ERR A memory error occurred.