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 to 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(). 

For security reasons, the item_type PAM_AUTHTOK and PAM_OLDAUTHTOK are available only to the module providers.  The authentication module, account module, and session management module should treat PAM_AUTHTOK as the current authentication token and 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. 

ATTRIBUTES

See attributes(5) for description of the following attributes:

SEE ALSO

pam(3), pam_acct_mgmt(3), pam_authenticate(3), pam_chauthtok(3), pam_get_user(3), pam_open_session(3), pam_setcred(3), pam_start(3), attributes(5)

NOTES

The interfaces in libpam() are MT-Safe only if each thread within the multi-threaded application uses its own PAM handle. 

SunOS 5.6  —  Last change: 28 Oct 1996