The module must supply the functions listed below. Together they define the function of a Linux-PAM module. Module developers are strongly urged to read the comments on security that follow this list.
Note, each of the following functions must be defined in all
modules. If a module developer does not want a specific one of these
functions to be used, it should be defined to simply return
PAM_IGNORE
.
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
argc
and argv
arguments are taken from the line
appropriate to this module---that is with a module_type of
auth
---in the configuration file (see pam(5)). Together
these arguments provide the number of arguments and an array of
pointers to the individual argument tokens. This will be familiar to C
programmers as the ubiquitous method of passing command arguments to
the function main()
.
The flags
argument can be a logically OR'd combination of the
following:
PAM_SILENT
do not generate any text (errors or otherwise),
PAM_DISALLOW_NULL_AUTHTOK
return PAM_AUTH_ERROR
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.
If the module authorization is un-sucessful, it will return
PAM_AUTH_ERR
. The application my susequently retry the
authentication procedure. However, if the module returns
PAM_MAXTRIES
, the application should not attempt to retry user
authentication.
Other valid responses of this function are:
PAM_CRED_INSUFFICIENT
User does not have sufficient credentials to be authenticated.
PAM_AUTHINFO_UNAVAIL
Module is unable to get authentication information.
PAM_USER_UNKNOWN
The module can find no record of the user.
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 ammend such information. Ordinarily, it is called after the user has been authenticated.
extern int pam_sm_acct_mgmt(pam_handle_t *pamh, int flags, int
argc, const char **argv);
extern int pam_sm_open_session(pam_handle_t *pamh, int flags, int
argc, const char **argv);
extern int pam_sm_close_session(pam_handle_t *pamh, int flags, int
argc, const char **argv);
extern int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int
argc, const char **argv);