NAME

pam_gnome_keyring -- automatic unlocking of Gnome Keyring

SYNOPSIS

[service-name] module-type control-flag [path-to]pam_gnome_keyring.so [options]

DESCRIPTION

The Gnome Keyring service module for PAM provides functionality for three PAM categories: authentication, session management and password management. In terms of module-type parameter, they are auth, session and password.

Authentication Module

Gnome Keyring authentication module retrieves password obtained by previous module in PAM stack and stores it for later use. When no password was obtained this module does nothing and returns success. It will never prompt for password by itself. Unless otherwise noted, this module returns success.

The following options may be passed to authentication module:

auto_start
: Gnome Keyring daemon is started if not already running and login keyring unlocked using provided password. If any of this fail, this module returns error.
only_if=service
: Comma separated list of services (eg. gdm,xdm) this module will handle. If a service is not in this list, module returns success without doing anything.

Session Management Module

The Gnome Keyring session management module provides functions to initiate and terminate sessions. If Gnome Keyring daemon is not running or no password was stored by authentication module, this module returns success. Otherwise it will attempt to unlock login keyring. If unlocking fails, this module will return error. When session is terminated and daemon was started in either module, then that daemon will be terminated.

The following options may be passed to session management module:

auto_start
: Same as in authentication. Please note that either authentication or session management module must have option auto_start for Gnome Keyring daemon to be started.
only_if=service
: List of services to handle.

Password Management Module

The Gnome Keyring password module allows changing password for login keyring. If no old password was obtained by previous module in the stack, this module is ignored. On the other hand, when no new password was obtained, this module will prompt for one. Gnome Keyring daemon will be started if not already running and stopped after concluding operation if it was not running before.

The following options may be passed to password management module:

auto_start
: Keep daemon running even when started by this module
only_if=service
: List of services to handle
use_authtok
: Do not prompt for new password. If not provided return error.

FILES

$HOME/.gnome2/keyrings/login.keyring: Encrypted login keyring

EXAMPLES

The following example of file /etc/pam.d/gdm configures gdm service to use standard UNIX authentication, as well as start and unlock Gnome Keyring. Rest of configuration is inherited from login service configuration.

auth      required     pam_unix.so
auth      optional     pam_gnome_keyring.so
account   include      login
session   include      login
session   optional     pam_gnome_keyring.so auto_start
password  include      login

The following example of file /etc/pam.d/passwd configures passwd program to update keyring password along with user's system password:

password  required     pam_unix.so
password  optional     pam_gnome_keyring.so

NOTES

Gnome Keyring implements its own SSH agent, therefore you should not stack it with pam_ssh for session management.