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.
