3.2. Authentication management

3.2. Authentication management
Prev	Chapter 3. What is expected of a module	Next

To be correctly initialized, PAM_SM_AUTH must be #define'd prior to including <security/pam_modules.h>. This will ensure that the prototypes for static modules are properly declared.

3.2.1. Service function for user authentication

#define PAM_SM_AUTH

#include <security/pam_modules.h>

`PAM_EXTERN int pam_sm_authenticate(`	`pamh`,
	`flags`,
	`argc`,
	`argv)`;

pam_handle_t *pamh;
int flags;
int argc;
const char **argv;

3.2.1.1. DESCRIPTION

The pam_sm_authenticate function is the service module's implementation of the pam_authenticate(3) interface.

This function performs the task of authenticating the user.

Valid flags, which may be logically OR'd with PAM_SILENT, are:

PAM_SILENT: Do not emit any messages.
PAM_DISALLOW_NULL_AUTHTOK: Return PAM_AUTH_ERR if the database of authentication tokens for this authentication mechanism has a NULL entry for the user. Without this flag, such a NULL token will lead to a success without the user being prompted.

3.2.1.2. RETURN VALUES

PAM_AUTH_ERR: Authentication failure.
PAM_CRED_INSUFFICIENT: For some reason the application does not have sufficient credentials to authenticate the user.
PAM_AUTHINFO_UNAVAIL: The modules were not able to access the authentication information. This might be due to a network or hardware failure etc.
PAM_SUCCESS: The authentication token was successfully updated.
PAM_USER_UNKNOWN: The supplied username is not known to the authentication service.
PAM_MAXTRIES: One or more of the authentication modules has reached its limit of tries authenticating the user. Do not try again.

3.2.2. Service function to alter credentials

#define PAM_SM_AUTH

#include <security/pam_modules.h>

`PAM_EXTERN int pam_sm_setcred(`	`pamh`,
	`flags`,
	`argc`,
	`argv)`;

pam_handle_t *pamh;
int flags;
int argc;
const char **argv;

3.2.2.1. DESCRIPTION

The pam_sm_setcred function is the service module's implementation of the pam_setcred(3) interface.

This function performs the task of altering the credentials of the user with respect to the corresponding authorization scheme. Generally, an authentication module may have access to more information about a user than their authentication token. This function is used to make such information available to the application. It should only be called after the user has been authenticated but before a session has been established.

Valid flags, which may be logically OR'd with PAM_SILENT, are:

PAM_SILENT: Do not emit any messages.
PAM_ESTABLISH_CRED: Initialize the credentials for the user.
PAM_DELETE_CRED: Delete the credentials associated with the authentication service.
PAM_REINITIALIZE_CRED: Reinitialize the user credentials.
PAM_REFRESH_CRED: Extend the lifetime of the user credentials.

The way the auth stack is navigated in order to evaluate the pam_setcred() function call, independent of the pam_sm_setcred() return codes, is exactly the same way that it was navigated when evaluating the pam_authenticate() library call. Typically, if a stack entry was ignored in evaluating pam_authenticate(), it will be ignored when libpam evaluates the pam_setcred() function call. Otherwise, the return codes from each module specific pam_sm_setcred() call are treated as required.

3.2.2.2. RETURN VALUES

PAM_CRED_UNAVAIL: This module cannot retrieve the user's credentials.
PAM_CRED_EXPIRED: The user's credentials have expired.
PAM_CRED_ERR: This module was unable to set the credentials of the user.
PAM_SUCCESS: The user credential was successfully set.
PAM_USER_UNKNOWN: The user is not known to this authentication module.

These, non-PAM_SUCCESS, return values will typically lead to the credential stack failing. The first such error will dominate in the return value of pam_setcred().

Prev	Up	Next
3.1. Overview	Home	3.3. Account management