PAM_GNOME_KEYRING(8)

NAME
pam_gnome_keyring - automatic unlocking of Gnome Keyring

SYNOPSIS

pam_gnome_keyring.so

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/.local/share/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.

SEE ALSO

pam.conf(5), pam.d(5), pam(8), auditctl(8), auditd(8)

AUTHOR

pam_gnome_keyring was written by Stef Walter <stef@thewalter.net>