pam_gnome_keyring -- automatic unlocking of Gnome Keyring
[service-name] module-type control-flag [path-to]pam_gnome_keyring.so [options]
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.
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:
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.
- 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:
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.
- 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:
- Keep daemon running even when started by this module
- List of services to handle
- Do not prompt for new password. If not provided return error.
- Encrypted login keyring
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
Gnome Keyring implements its own SSH agent, therefore you should not stack it with pam_ssh for session management.