pam_modules-4.html
Next
pam_modules-2.html
Previous
pam_modules.html#toc3
Contents
3. What is expected of a module
The module must supply a sub-set of the six 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.
3.1 Overview
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.
Functional independence
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.
Minimizing administration problems
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
.
Arguments supplied to the module
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.
3.2 Authentication management
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 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.
Permitted flags, one of which, may be logically OR'd with
PAM_SILENT
are,
PAM_ESTABLISH_CRED
Set the credentials for the authentication service,
PAM_DELETE_CRED
Delete the credentials associated with the authentication service,
PAM_REINITIALIZE_CRED
Reinitialize the user credentials, and
PAM_REFRESH_CRED
Extend the lifetime of the user credentials.
Prior to
Linux-PAM-0.75
, and due to a deficiency with the way the
auth
stack was handled in the case of the setcred stack being
processed, the module was required to attempt to return the same error
code as
pam_sm_authenticate
did.  This was necessary to preserve
the logic followed by libpam as it executes the stack of
authentication
modules, when the application called either
pam_authenticate()
or
pam_setcred()
.  Failing to do this,
led to confusion on the part of the System Administrator.
For
Linux-PAM-0.75
and later, libpam handles the credential stack
much more sanely. 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
.
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.
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()
.
3.3 Account management
To be correctly initialized,
PAM_SM_ACCOUNT
must be
#define
'd prior to including
<security/pam_modules.h>
.
This will ensure that the prototype for a static module is properly
declared.
PAM_EXTERN int pam_sm_acct_mgmt(pam_handle_t *pamh, int flags, int
argc, const char **argv);
This function performs the task of establishing whether the user is
permitted to gain access at this time. It should be understood that
the user has previously been validated by an authentication
module. This function checks for other things. Such things might be:
the time of day or the date, the terminal line, remote
hostname, etc. .
This function may also determine things like the expiration on
passwords, and respond that the user change it before continuing.
Valid flags, which may be logically OR'd with
PAM_SILENT
, are the
same as those applicable to the
flags
argument of
pam_sm_authenticate
.
This function may return one of the following errors,
PAM_ACCT_EXPIRED
The user is no longer permitted access to the system.
PAM_AUTH_ERR
There was an authentication error.
PAM_AUTHTOKEN_REQD
The user's authentication token has expired. Before calling
this function again the application will arrange for a new one to be
given. This will likely result in a call to
pam_sm_chauthtok()
.
PAM_USER_UNKNOWN
The user is not known to the module's account management
component.
3.4 Session management
To be correctly initialized,
PAM_SM_SESSION
must be
#define
'd prior to including
<security/pam_modules.h>
.  This will ensure that the
prototypes for static modules are properly declared.
The following two functions are defined to handle the
initialization/termination of a session. For example, at the beginning
of a session the module may wish to log a message with the system
regarding the user. Similarly, at the end of the session the module
would inform the system that the user's session has ended.
It should be possible for sessions to be opened by one application and
closed by another. This either requires that the module uses only
information obtained from
pam_get_item()
, or that information
regarding the session is stored in some way by the operating system
(in a file for example).
PAM_EXTERN int pam_sm_open_session(pam_handle_t *pamh, int flags, int
argc, const char **argv);
This function is called to commence a session. The only valid, but
optional, flag is
PAM_SILENT
.
As a return value,
PAM_SUCCESS
signals success and
PAM_SESSION_ERR
failure.
PAM_EXTERN int pam_sm_close_session(pam_handle_t *pamh, int flags, int
argc, const char **argv);
This function is called to terminate a session. The only valid, but
optional, flag is
PAM_SILENT
.
As a return value,
PAM_SUCCESS
signals success and
PAM_SESSION_ERR
failure.
3.5 Password management
To be correctly initialized,
PAM_SM_PASSWORD
must be
#define
'd prior to including
<security/pam_modules.h>
.
This will ensure that the prototype for a static module is properly
declared.
PAM_EXTERN int pam_sm_chauthtok(pam_handle_t *pamh, int flags, int
argc, const char **argv);
This function is used to (re-)set the authentication token of the
user. A valid flag, which may be logically OR'd with
PAM_SILENT
,
can be built from the following list,
PAM_CHANGE_EXPIRED_AUTHTOK
This argument indicates to the module that the users
authentication token (password) should only be changed if it has
expired. This flag is optional and
must
be combined with one of
the following two flags. Note, however, the following two options are
mutually exclusive
.
PAM_PRELIM_CHECK
This indicates that the modules are being probed as to their
ready status for altering the user's authentication token. If the
module requires access to another system over some network it should
attempt to verify it can connect to this system on receiving this
flag. If a module cannot establish it is ready to update the user's
authentication token it should return
PAM_TRY_AGAIN
, this
information will be passed back to the application.
PAM_UPDATE_AUTHTOK
This informs the module that this is the call it should change
the authorization tokens. If the flag is logically OR'd with
PAM_CHANGE_EXPIRED_AUTHTOK
, the token is only changed if it has
actually expired.
Note, the
Linux-PAM
library calls this function twice in
succession. The first time with
PAM_PRELIM_CHECK
and then, if the
module does not return
PAM_TRY_AGAIN
, subsequently with
PAM_UPDATE_AUTHTOK
. It is only on the second call that the
authorization token is (possibly) changed.
PAM_SUCCESS
is the only successful return value, valid
error-returns are:
PAM_AUTHTOK_ERR
The module was unable to obtain the new authentication token.
PAM_AUTHTOK_RECOVERY_ERR
The module was unable to obtain the old authentication token.
PAM_AUTHTOK_LOCK_BUSY
Cannot change the authentication token since it is currently
locked.
PAM_AUTHTOK_DISABLE_AGING
Authentication token aging has been disabled.
PAM_PERM_DENIED
Permission denied.
PAM_TRY_AGAIN
Preliminary check was unsuccessful. Signals an immediate return
to the application is desired.
PAM_USER_UNKNOWN
The user is not known to the authentication token changing
service.
pam_modules-4.html
Next
pam_modules-2.html
Previous
pam_modules.html#toc3
Contents
