NAME

pam_sm_setcred - service provider implementation for pam_setcred

SYNOPSIS

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

int pam_sm_setcred(
    pam_handle_t    *pamh,
    int              flags,
    int              argc,
    const char     **argv
);

DESCRIPTION

In response to a call to pam_set_cred(), the PAM framework calls pam_sm_setcred() from the modules listed in the PAM configuration. The authentication provider supplies the back-end functionality for this interface function.

pam_sm_setcred() is called to set the credentials of the current user associated with the authentication handle, pamh.

The authentication status (success or reason for failure) is typically saved as module-specific state in the authentication handle by the authentication module. The status should be retrieved using pam_get_data(), and used to determine if user credentials should be set.

The arguments for pam_sm_setcred() are:

pamh (in)

The PAM authentication handle, obtained from a previous call to pam_start().

flags (in)

The following flags may be set in the flags field. Note that the first four flags are mutually exclusive:

PAM_ESTABLISH_CRED

Set user credentials for the authentication service.

PAM_DELETE_CRED

Delete user credentials associated with the authentication service.

PAM_REINITIALIZE_CRED

Reinitialize user credentials.

PAM_REFRESH_CRED

Extend lifetime of user credentials.

PAM_SILENT

Authentication service should not generate messages.

If none of these flags are set, PAM_ESTABLISH_CRED is used as the default.

argc (in)

The argc argument represents the number of module options passed in from the PAM configuration.

argv (in)

Specifies the module options, which are interpreted and processed by the authentication service. If an unknown option is to the module, an error should be logged and the option ignored.

RETURN VALUE

The following PAM status codes shall be returned:

[PAM_SUCCESS]

Successful completion.

[PAM_CRED_UNAVAIL]

Underlying authentication service cannot retrieve user credentials.

[PAM_CRED_EXPIRED]

User credentials have expired.

[PAM_USER_UNKNOWN]

User unknown to authentication service.

[PAM_CRED_ERR]

Failure in setting user credentials.

[PAM_IGNORE]

Ignore underlying session module regardless of whether the control flag is required, optional or sufficient.

[PAM_PERM_DENIED]

The caller does not possess the required authority.

[PAM_SERVICE_ERR]

Error in service module.

[PAM_SYSTEM_ERR]

System error.

[PAM_BUF_ERR]

Memory buffer error.

[PAM_CONV_ERR]

Conversation error.

[??] Some characters or strings that appear in the printed document are not easily representable using HTML.