NAME
pam_afs_session - AFS PAG and token PAM module
SYNOPSIS
auth optional pam_afs_session.so
session required pam_afs_session.so
DESCRIPTION
The AFS session service module for PAM, typically installed at
/lib/security/pam_afs_session.so, establishes new AFS sessions and
obtains AFS tokens when a new session is opened for a user. It is a
shared object that is dynamically loaded by the PAM subsystem as
necessary, based on the system PAM configuration. PAM is a system for
plugging in external authentication and session management modules so
that each application doesn't have to know the best way to check user
authentication or create a user session on that system. For details on
how to configure PAM on your system, see the PAM man page, often
pam(7).
This module provides pam_setcred, pam_open_session, and
pam_close_session implementations for AFS. Because pam_setcred is part
of the auth PAM group, it also implements a dummy pam_authenticate that
always succeeds (otherwise, it can't provide a pam_setcred).
Make sure that this module is NEVER listed as "sufficient" or as the
only "required" module in the auth group. Doing so will potentially
allow users to log on without any password. There unfortunately isn't
a way to work around this and still provide pam_setcred without running
afoul of a bug in (at least) Linux PAM 0.99.7.1 and probably earlier
that causes authentication to fail when the final module in the auth
group returns PAM_IGNORE and "[default=done]" was given as the action.
Here are the actions of this module:
pam_open_session
When a new session is opened, this module will first check to see
if AFS is running on the system. If not, it will log a message and
exit successfully. If AFS is running, it will place the user's
session in a new PAG (Process Authentication Group, often
implemented as supplemental groups, which limits user tokens to
only processes in that PAG). It will then attempt to obtain
tokens, either directly if built with the Heimdal libkafs library
and Kerberos support or by running an external aklog program. If
PAG creation fails, the module will fail; if obtainint tokens
fails, the module will log a warning but still return success.
The module will only attempt to obtain tokens if the environment
variable KRB5CCNAME is set in the environment, unless otherwise
configured (see the always_aklog option). It will always create a
new PAG, however.
pam_close_session
If and only if pam_open_session successfully obtained AFS tokens
and AFS is still running on the system, pam_close_session will
delete the tokens in the current PAG (equivalent to running unlog).
To leave the tokens after session close, set the retain_after_close
option.
pam_setcred
When pam_setcred is called with the PAM_ESTABLISH_CRED flag, it
will do the same as if pam_open_session was called. When
pam_setcred is called with the PAM_DELETE_CRED flag, it will do the
same as if pam_close_session was called. When called with the
PAM_REINITIALIZE_CRED flag or the PAM_REFRESH_CRED flag, it won't
create a new PAG but instead will only attempt to get new tokens
(still skipping this unless KRB5CCNAME is set in the environment or
always_aklog is set).
This module is primarily intended for use with a Kerberos v5
authentication module. It does not itself do any user authentication;
it cannot, for instance, be used to authenticate users to a kaserver.
While it is intended for use with an aklog that uses Kerberos v5 ticket
caches to obtain tokens, it can be used with any aklog implementation
(always_aklog may have to be set if no Kerberos v5 ticket cache will be
present).
This module performs no authorization checks and does not hook into
password changes; it only implements the session functions and
pam_setcred.
CONFIGURATION
The AFS session PAM module supports the following configuration
options, which may be set in the PAM configuration as arguments listed
after "pam_afs_session.so" or in the system krb5.conf.
Some of them take arguments, in which case the argument will be given
after "=". The rest are boolean options. To set a boolean option in
the PAM configuration, just give the name of the option in the
arguments. To set an option that takes an argument, follow the option
name with an equal sign ("=") and the value, with no separating
whitespace. Whitespace in option arguments is not supported in the PAM
configuration.
To set an option for the PAM module in the system krb5.conf file, put
that option in the [appdefaults] section. The AFS session PAM module
will look for options either at the top level of the [appdefaults]
section or in a subsection named "pam-afs-session" (currently, realm-
specific configuration is not checked). For example, the following
fragment of a krb5.conf file would set aklog_homedir to true and
minimum_uid to 100.
[appdefaults]
aklog_homedir = true
pam-afs-session = {
minimum_uid = 100
}
There is no difference to the PAM module whether options are specified
at the top level or in a "pam-afs-session" section; the
"pam-afs-session" section is supported in case there are options that
should be set for the PAM module but not for other applications. For
more information on the syntax of krb5.conf, see krb5.conf(5).
If the same option is set in krb5.conf and in the PAM configuration,
the latter takes precedent. Note, however, that due to the
configuration syntax, there's no way to turn off a boolean option in
the PAM configuration that was turned on in krb5.conf.
afs_cells=cell[,cell...]
Obtain tokens for the listed cells instead of the default local
cell. If more than one cell is listed, try to obtain tokens for
each cell. If specified in krb5.conf, the cells can be separated
by any combination of spaces and commas; if specified in the PAM
configuration, they must be separated by commas.
If the AFS session PAM module is running an external program, this
option is implemented by passing a -c flag with the cell as its
argument for each listed cell to that program. If aklog_homedir is
also set, the -c flags and the -p flag will all be passed to the
external program.
aklog_homedir
Try to obtain the necessary tokens to access the user's home
directory. If the libkafs token-obtaining API is used, setting
this will cause the AFS session PAM module to pass the user's home
directory into that API and request that the appropriate tokens be
obtained. If running an external aklog program, aklog will be
called with -p home-directory where home-directory is the home
directory of the local user for which the session is being opened
or refreshed. This generally will tell aklog to check that path,
find all AFS cells involved in access to that path, and attempt to
obtain tokens for each one. Note that this means that if the
user's home directory is not in AFS, no tokens will be obtained.
In either case, the user's home directory is obtained via
getpwnam() based on the username PAM says we are authenticating.
always_aklog
Normally, the AFS session PAM module only tries to obtain tokens if
KRB5CCNAME is set in the PAM environment. If this option is set,
it will always attempt to obtain tokens. This is only useful if it
is configured to run an external aklog program.
This can be used if your environment doesn't correctly set
KRB5CCNAME in the environment for some reason, or if your aklog
doesn't rely on a Kerberos ticket cache to obtain tokens (or can
find the cache on its own via some other means).
debug
If this option is set, additional trace information will be logged
to syslog with priority LOG_DEBUG.
ignore_root
If this option is set, the AFS session PAM module won't take any
action (and will exit successfully) if the account for which the
session is being established is named "root".
kdestroy
If this option is set and the AFS session PAM module was built with
Kerberos support, the user's ticket cache will be destroyed after
tokens are obtained successfully. If tokens are not obtained
successfully, the ticket cache will be left intact. Please note
that this is not properly a security feature, since the ticket
cache will still be written to disk between the time the Kerberos
PAM module authenticates the user and the time the AFS session PAM
module is run. It can, however, be used to reduce the window
during which Kerberos ticket caches are lying about if the only use
one has for ticket caches is to obtain AFS tokens.
minimum_uid=uid
If this option is set, the AFS session PAM module won't take any
action (and will exit successfully) if the account for which the
session is being established has a UID lower than uid.
nopag
If this option is set, no PAG will be created. Be careful when
using this option, since it means that the user will inherit a PAG
from the process managing the login. If sshd, for instance, is
started in a PAG, every user who logs in via ssh will be put in the
same PAG and will share tokens if this option is used.
notokens
If this option is set, the AFS session PAM module will only create
a PAG and not attempt to obtain tokens. Setting this option
overrides all other settings related to acquiring tokens, including
always_aklog. If both nopag and notokens are set, the module
essentially does nothing.
Setting notokens also implies retain_after_close, meaning that the
AFS session PAM module will also not attempt to delete tokens when
the user's session ends.
program=path
The path to the aklog program to run. Setting this option tells
the AFS session PAM module to always run an external program to
obtain tokens and never use the libkafs interface, even if the
latter is available.
If this option is not set, the default behavior is to call the
libkafs function to obtain tokens, if available, and otherwise to
use a default path to aklog determined at compile time (the first
aklog found on the compiler's path by default). If no aklog could
be found at compile time and libkafs isn't used, this option must
be set.
retain_after_close
If this option is set, pam_close_session will do nothing
(successfully) rather than deleting tokens. This will allow
programs started in the user's PAG that are still running when the
log out to continue to use the user's tokens until they expire.
Normally, the AFS kernel module will automatically clean up tokens
once every process in that PAG has terminated.
ENVIRONMENT
KRB5CCNAME
This module looks for KRB5CCNAME in the PAM environment and by
default does not run aklog if it is not set.
The entire PAM environment is passed to aklog as its environment
(rather than the environment of the process running the PAM functions).
WARNINGS
As mentioned above, this module implements a dummy pam_authenticate
function so that it can provide a pam_setcred function. Never list
this module as "sufficient" or as the only "required" module or you may
allow users to log on without a password.
To detect whether AFS is running on the system, the AFS session PAM
module teporarily sets a SIGSYS handler before attempting an AFS system
call. That handler may also modify a static variable. Neither of
these should ideally be done in a PAM module, but there is no other
good way of checking for the non-existence of a system call that
doesn't crash the application on some operating systems. The PAM
module will attempt to restore the previous SIGSYS handler, if any,
after the test is done, and the static variable is used in such a way
that running it from multiple threads shouldn't be an issue, but be
aware that the PAM module is doing this behind the back of the
application and may interfere with unusual SIGSYS handlers or similar
application actions.
NOTES
When using the libkafs interface to obtain tokens, be sure that it is
configured properly for the type of AFS tokens expected at your site.
As of Heimdal 0.7, the default behavior is to contact the krb524
service to translate Kerberos v5 tickets into Kerberos v4 tickets to
use as tokens. AFS cells running current server software no longer
need this, and if your site doesn't run the krb524 service, this may
break token acquisition.
Sites running AFS servers that understand Kerberos-v5-derived tokens
should add configuration like:
libkafs = {
EXAMPLE.ORG = {
afs-use-524 = no
}
}
to the [appdefaults] section of their krb5.conf files to disable use of
the krb524 service. See the Heimdal kafs man page for more
information.
SEE ALSO
aklog(1), kafs(3), pam(7), syslog(3), unlog(1)