Gnome Keyring: Automatic Unlocking / PAM

As of version 2.19.6 GNOME keyring can automatically unlock the 'login' keyring when the user logs in. Other keyrings may have their unlock passwords stored in the 'login' keyring, and are then automatically unlocked when necessary.

How to Make it Work

To check if your distro or OS has support for this:

• # grep -rq pam_gnome_keyring.so /etc/pam.* && echo "Have PAM Support"

To see if a 'login' keyring exists (it's created automatically):

• # test -f ~/.gnome2/keyrings/login.keyring && echo "Have 'login' keyring"

Installing Gnome Keyring's PAM Support

You can ask your OS or distro maker to include this in their next release.

Beware that if you install configure this yourself, it's possible to lock yourself out of your machine. Make sure you know what you're doing, and how to fix any problems that arise.

These instructions are general, and may not work on your machine. You may be able to find more specific instructions on forums for your OS or distro.

First figure out where your PAM modules are located. Make note of the directory:

• dirname `locate pam_unix.so`

Build gnome-keyring with the PAM configure options. Use the PAM module directory as the argument for --with-pam-dir

• # tar -zxvf gnome-keyring-2.*.tar.gz
  # cd gnome-keyring-2.*
  # ./configure --prefix=/usr --sysconfdir=/etc --enable-pam --with-pam-dir=/lib/security
  # make
  # sudo make install

In /etc/pam.d/gdm, add lines like this at the end of the 'auth', 'session' blocks:

• auth    optional        pam_gnome_keyring.so
  session optional        pam_gnome_keyring.so  auto_start

In /etc/pam.d/gnome-screensaver, add a line like this to the 'auth' block:

• auth    optional        pam_gnome_keyring.so

In /etc/pam.d/passwd, add a line like this to the 'password' block:

• password        optional        pam_gnome_keyring.so

gnome-screensaver versions earlier than 2.20 do not work.

How it Works

• Upon authenticating the user, or logging into the session, the PAM module checks for the GNOME_KEYRING_SOCKET environment variable. If not present it assumes that gnome-keyring-daemon is not running for that session.

  • If the auto_start argument is present in in the PAM config, it then starts it as a daemon.

  • The gnome-session process does the same checks, which prevents it from starting twice.

• Upon authenticating the user, the PAM module tries to unlock the 'login' keyring with the password entered by the user.
  • If the 'login' keyring does not exist it is created with the user's password.
  • If the 'login' is the first and only keyring it will become the default keyring.

• When the PAM session is closed, if the PAM module started gnome-keyring-daemon it is killed.

• When the user changes their password, the PAM module changes the password of the 'login' keyring to match.

  • Again, here gnome-keyring-daemon is started if necessary.

  • If root changes the password, or /etc/shadow is directly edited then due to the lack of the old password, the 'login' keyring cannot be updated.
• If the 'login' keyring exists and is unlocked, then when the user is prompted to unlock any other keyring, a check box is presented: "Automatically unlock this on login"
  • This adds an item to the 'login' keyring with the password for the other keyring.
  • Before prompting the user to unlock a keyring, the 'login' keyring is checked to see if the user has stored a password there.