pam_set_item(3)

NAME
pam_set_item, pam_get_item - authentication information routines for PAM

SYNOPSIS

cc [ flag ... ] file ... -lpam [ library ... ]

#include <security/pam_appl.h>

int pam_set_item(pam_handle_t *pamh, int item_type, const void *item);

int pam_get_item(const pam_handle_t *pamh, int item_type, void **item);

DESCRIPTION
pam_get_item() and pam_set_item() allow applications and PAM service modules to access and update PAM information as needed. The information is specified by item_type, and can be one of the following:

    PAM_SERVICE
        The service name

    PAM_USER
        The user name

    PAM_AUTHTOK
        The user authentication token

    PAM_OLDAUTHTOK
        The old user authentication token

    PAM_TTY
        The tty name

    PAM_RHOST
        The remote host name

    PAM_RUSER
        The remote user name

    PAM_CONV
        The pam_conv structure

    PAM_USER_PROMPT
        The default prompt used by pam_get_user()

The item_type PAM_AUTHTOK and PAM_OLDAUTHTOK are available only to the module providers for security reasons. The authentication module, account module, and session management module should treat PAM_AUTHTOK as the current authentication token, and should ignore PAM_OLDAUTHTOK. The password management module should treat PAM_OLDAUTHTOK as the current authentication token and PAM_AUTHTOK as the new authentication token.

pam_set_item() is passed the authentication handle, pamh, returned by pam_start(), a pointer to the object, item, and its type, item_type. If successful, pam_set_item() copies the item to an internal storage area allocated by the authentication module and returns PAM_SUCCESS. An item that had been previously set will be overwritten by the new value.

pam_get_item() is passed the authentication handle, pamh, returned by pam_start(), an item_type, and the address of the pointer, item, which is assigned the address of the requested object. The object data is valid until modified by a subsequent call to pam_set_item() for the same item_type, or unless it is modified by any of the underlying service modules. If the item has not been previously set, pam_get_item() returns a NULL pointer. An item retrieved by pam_get_item() should not be modified or freed. The item will be released by pam_end().

RETURN VALUES

Upon success pam_get_item() returns PAM_SUCCESS; otherwise it returns an error code. Refer to pam(3) for information on error related return values.

SEE ALSO
pam_start(3), pam_authenticate(3), pam_acct_mgmt(3), pam_open_session(3), pam_setcred(3), pam_chauthtok(3), pam_get_user(3), pam(3)