The six module functions are grouped into four independent management groups. These groups are as follows: authentication, account, session and password. To be properly defined, a module must define all functions within at least one of these groups. A single module may contain the necessary functions for all four groups.
The independence of the four groups of service a module can offer means that the module should allow for the possibility that any one of these four services may legitimately be called in any order. Thus, the module writer should consider the appropriateness of performing a service without the prior success of some other part of the module.
As an informative example, consider the possibility that an
application applies to change a user's authentication token, without
having first requested that Linux-PAM authenticate the user. In
some cases this may be deemed appropriate: when root
wants to
change the authentication token of some lesser user. In other cases it
may not be appropriate: when joe
maliciously wants to reset
alice
's password; or when anyone other than the user themself
wishes to reset their KERBEROS authentication token. A policy for
this action should be defined by any reasonable authentication scheme,
the module writer should consider this when implementing a given
module.
To avoid system administration problems and the poor construction of a
/etc/pam.conf
file, the module developer may define all
six of the following functions. For those functions that would not be
called, the module should return PAM_SERVICE_ERR
and write an
appropriate message to the system log. When this action is deemed
inappropriate, the function would simply return PAM_IGNORE
.
The flags
argument of each of the following functions can be
logically OR'd with PAM_SILENT
, which is used to inform the
module to not pass any text (errors or warnings) to the
application.
The argc
and argv
arguments are taken from the line
appropriate to this module---that is, with the service_name
matching that of the application---in the configuration file (see the
Linux-PAM System Administrators' Guide). Together these two
parameters 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()
. Note, however, that the first argument (argv[0]
) is
a true argument and not the name of the module.