pam_sm_setcred Subroutine

Edit online

Purpose

PAM module-specific implementation of pam_setcred.

Library

PAM Library (libpam.a)

Syntax

#include <security/pam_appl.h>
#include <security/pam_modules.h>

int pam_sm_setcred (PAMHandle, Flags, Argc, Argv)
pam_handle_t *PAMHandle;
int Flags;
int Argc;
const char **Argv;

Description

When an application invokes pam_setcred(), the PAM Framework calls pam_sm_setcred for each module in the authentication module stack. The pam_sm_setcred module interface allows for the setting of module-specific credentials in the PAM handle. The user's credentials should be set based upon the user's authentication state. This information can usually be retrieved with a call to pam_get_data().

Parameters

Item Description
PAMhandle The PAM handle representing the current user authentication session. This handle is obtained by a call to pam_start().
Flags The flags are used to set pam_setcred options. The recognized flags are:
  • PAM_SILENT
    • No messages should be displayed.
  • PAM_ESTABLISH_CRED*
    • Sets the user's credentials. This is the default.
  • PAM_DELETE_CRED*
    • Removes the user credentials.
  • PAM_REINITIALIZE_CRED*
    • Renews the user credentials.
  • PAM_REFRESH_CRED*
    • Refreshes the user credentials, extending their lifetime.
*Mutually exclusive. If one of them is not set, PAM_ESTABLISH_CRED is assumed.
Argc The number of module options defined.
Argv The module options. These options are module-dependent. Any modules receiving invalid options should ignore them.

Return Values

Upon successful completion, pam_sm_setcred returns PAM_SUCCESS. If the routine fails, a different error is returned, depending on the actual error.

Error Codes

Item Description
PAM_CRED_UNAVAIL The user credentials cannot be found.
PAM_CRED_EXPIRED The user's credentials have expired.
PAM_CRED_ERR A failure occurred while setting user credentials.
PAM_USER_UNKNOWN The user is not known.
PAM_OPEN_ERR One of the PAM authentication modules could not be loaded.
PAM_SYMBOL_ERR A necessary item is not available to a PAM module.
PAM_SERVICE_ERR An error occurred in a PAM module.
PAM_SYSTEM_ERR A system error occurred.
PAM_BUF_ERR A memory error occurred.
PAM_CONV_ERR A conversation error occurred.
PAM_PERM_DENIED Access permission was denied to the user.