NAME

pam_afs_session - AuriStorFS PAG and token PAM module

SYNOPSIS

  auth          optional        pam_afs_session.so
  session       required        pam_afs_session.so

CONTENTS

DESCRIPTION

The AuriStorFS session service module for PAM, typically installed at /lib/security/pam_afs_session.so, establishes new AuriStorFS sessions and obtains AuriStorFS 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 AuriStorFS. 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 AuriStorFS or kafs are running on the system. If not, it will log a message and exit successfully. If AuriStorFS is running, it will place the user's session in a new PAG (Process Authentication Group, implemented using Linux Keyrings, which limits user tokens to only processes in that PAG). It will then attempt to obtain tokens, by running an external aklog(1) program. If PAG creation fails, the module will fail; if obtaining 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, unless the nopag option is enabled.

pam_close_session

If and only if pam_open_session successfully obtained AuriStorFS tokens and AuriStorFS is still running on the system, pam_close_session will delete the tokens in the current PAG (equivalent to running unlog(1)). 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 authentication module. It does not itself do any user authentication; it cannot, for instance, be used to authenticate users to a Kerberos realm. While it is intended for use with an aklog(1) that uses Kerberos ticket caches to obtain tokens, it can be used with any aklog(1) implementation (always_aklog may have to be set if no Kerberos 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 AuriStorFS session PAM module supports the following configuration options, which may be set in the PAM configuration as arguments listed after pam_afs_session.so.

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 files of most PAM implementations.

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. They must be separated by commas in the PAM configuration.

This option is implemented by passing a -c flag with the cell as its argument for each listed cell to the external aklog(1) 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. The external aklog(1) program 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(1) 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.

The user's home directory is obtained via getpwnam() based on the username PAM says we are authenticating.

aklogprogram=path

The path to the aklog(1) program to run. Setting this option tells the AuriStorFS session PAM module to run an alternate external program to obtain tokens.

You may pass options to this program by separating them with commas (or spaces or tabs if the configuration syntax of your PAM configuration allows this). For example, the setting:

    aklogprogram=/usr/bin/aklog,-noprdb

will run /usr/bin/aklog -noprdb as the program to obtain tokens. The arguments are passed directly, not parsed by the shell.

If this option is not set, the default behavior is to use the default path to aklog(1) as provided by AuriStorFS.

always_aklog

Normally, the AuriStorFS 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 can be used if your environment doesn't correctly set KRB5CCNAME in the environment for some reason, or if your aklog(1) 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 AuriStorFS 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.

minimum_uid=uid

If this option is set, the AuriStorFS 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.

This is the default on Mac OS X, where PAGs are not supported.

notokens

If this option is set, the AuriStorFS 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 AuriStorFS session PAM module will also not attempt to delete tokens when the user's session ends.

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 AuriStorFS kernel module will automatically clean up tokens once every process in that PAG has terminated.

unlogprogram=path

The path to the unlog(1) program to run. Setting this option tells the AuriStorFS session PAM module to run an alternate external program to destroy tokens.

You may pass options to this program by separating them with commas (or spaces or tabs if the configuration syntax of your PAM configuration allows this). For example, the setting:

    unlogprogram=/usr/bin/unlog,-quiet

will run /usr/bin/unlog -quiet as the program to destroy tokens. The arguments are passed directly, not parsed by the shell.

If this option is not set, the default behavior is to use the default path to unlog(1) as provided by AuriStorFS.

ENVIRONMENT

KRB5CCNAME

This module looks for KRB5CCNAME in the PAM environment and by default does not run aklog(1) if it is not set.

The entire PAM environment is passed to aklog(1) 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.

While spawning an external aklog(1) program, the AuriStorFS session PAM module resets the SIGCHLD signal handler to the default handler while the program runs and then restores it afterward. This is done to avoid having aklog interfere with process handling in the calling application, but it means that there's a race condition that can cause children to be incorrectly handled if they exit while aklog is running.

Some PAM stack configurations include pam_keyinit in force mode, which will create a new session keyring. It is important that this happen before pam_afs_session is run, or session information may be lost. For sshd, the setcred function in the auth module will be run before the open function in the session module is, so configurations should either avoid the force option to pam_keyinit, or only include pam_afs_session as a session dependency. Since sshd does not include credential refreshing, no functionality is sacrificed with this configuration.

SEE ALSO

aklog(1), kafs(1), pam(7), syslog(3), unlog(1)

COPYRIGHT AND LICENSE

Copyright 2015 Russ Allbery <eagle@eyrie.org>

Copyright 2005, 2006, 2007, 2008, 2009, 2010, 2011 The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

ACKNOWLEDGEMENTS

"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.