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.
PAM_EXTERN int pam_sm_authenticate(pam_handle_t *pamh, int flags,
int argc, const char **argv);
This function performs the task of authenticating the user.
The flags
argument can be a logically OR'd with PAM_SILENT
and optionally take the following value:
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.
Besides PAM_SUCCESS
return values that can be sent by this
function are one of the following:
PAM_AUTH_ERR
The user was not authenticated
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_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.
PAM_EXTERN int pam_sm_setcred(pam_handle_t *pamh, int flags, int
argc, const char **argv);
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 append such information to the application. It should only be called after the user has been authenticated.
Permitted flags, one of which, may be logically OR'd with
PAM_SILENT
are,
PAM_CRED_ESTABLISH
Set the credentials for the authentication service,
PAM_CRED_DELETE
Delete the credentials associated with the authentication service,
PAM_CRED_REINITIALIZE
Reinitialize the user credentials, and
PAM_CRED_REFRESH
Extend the lifetime of the user credentials.
Besides PAM_SUCCESS
, the module may return one of the following
errors:
PAM_CRED_UNAVAIL
This module cannot retrieve the user's credentials.
PAM_CRED_EXPIRED
The user's credentials have expired.
PAM_USER_UNKNOWN
The user is not known to this authentication module.
PAM_CRED_ERR
This module was unable to set the credentials of the user.