PAM_SET_ITEM(3PAM) PAM Library Functions PAM_SET_ITEM(3PAM)

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,
const void **item);

DESCRIPTION

The pam_get_item() and pam_set_item() functions 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_AUSER
The authenticated user name. Applications that
are trusted to correctly identify the
authenticated user should set this item to the
authenticated user name. See NOTES and
pam_unix_cred(7).


PAM_AUTHTOK
The user authentication token.


PAM_CONV
The pam_conv structure.


PAM_OLDAUTHTOK
The old user authentication token.


PAM_RESOURCE
A semicolon-separated list of key=value pairs that
represent the set of resource controls for
application by pam_setcred(3PAM) or
pam_open_session(3PAM). See the individual service
module definitions, such as pam_unix_cred(7), for
interpretations of the keys and values.


PAM_RHOST
The remote host name.


PAM_RUSER
The rlogin/rsh untrusted remote user name.


PAM_SERVICE
The service name.


PAM_TTY
The tty name.


PAM_USER
The user name.


PAM_USER_PROMPT
The default prompt used by pam_get_user().


PAM_REPOSITORY
The repository that contains the authentication
token information.


The pam_repository structure is defined as:

struct pam_repository {
char *type; /* Repository type, e.g., files, */
/* nis, ldap */
void *scope; /* Optional scope information */
size_t scope_len; /* length of scope information */
};


The item_type PAM_SERVICE can be set only by pam_start() and is read-
only to both applications and service modules.


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.


The pam_set_item() function 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.


The pam_get_item() function 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(3PAM) for information on error
related return values.

ATTRIBUTES

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


+--------------------+-------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------------+
|Interface Stability | Stable |
+--------------------+-------------------------+
|MT-Level | MT-Safe with exceptions |
+--------------------+-------------------------+


The functions in libpam(3LIB) are MT-Safe only if each thread within
the multithreaded application uses its own PAM handle.

SEE ALSO

libpam(3LIB), pam(3PAM), pam_acct_mgmt(3PAM), pam_authenticate(3PAM),
pam_chauthtok(3PAM), pam_get_user(3PAM), pam_open_session(3PAM),
pam_setcred(3PAM), pam_start(3PAM), attributes(7), pam_unix_cred(7)

NOTES

If the PAM_REPOSITORY item_type is set and a service module does not
recognize the type, the service module does not process any
information, and returns PAM_IGNORE. If the PAM_REPOSITORY item_type
is not set, a service module performs its default action.


PAM_AUSER is not intended as a replacement for PAM_USER. It is
expected to be used to supplement PAM_USER when there is an
authenticated user from a source other than pam_authenticate(3PAM).
Such sources could be sshd host-based authentication, kerberized
rlogin, and su(8).

July 6, 2024 PAM_SET_ITEM(3PAM)