Gnome Keyring

What is Gnome Keyring

Gnome Keyring is a program that largely hides in the background while holding your secrets (mainly your passwords and pass phrases). When needed, it securely communicates those to whatever program needs them. When it works, it is extremely convenient. And if you use the Gnome user environment, it generally just works. However, if you choose to roll your own environment, it can be difficult to make work. You see, Keyring is a Gnome project, and in general Gnome projects follow the “Don’t you worry your pretty little head about it Sweetheart” school of user interface design, which dictates that you make programs easy to use by eliminating the needless complexity that comes in the form of error messages, log files, user documentation, man pages, and even those pesky command line help summaries.

What follows is the information I have found through trial and error over many years on how to get Keyring to operate as expected. This experience comes from trying to use Keyring outside of Gnome, its normal environment. Instead, I use I3 (i3wm), a nifty tiling window manager.

The first thing that you need to know about Keyring is that it really is not intended for you to use it directly. There is a user interface, a program called Seahorse, that allows you to enter or examine your secrets, but it is an after thought that is not terribly useful. Instead, Keyring is designed to allow various programs on your system to automatically save and then later retrieve secrets. The most common users of Keyring are Network Manager (for saving your WiFi and VPN passwords), SSH and GPG (for saving the pass phrases for your private keys).

Finally, you should know that when the Gnome project moved to Gnome3 many users were unhappy (actually I so disliked Gnome3 that I moved to I3, and am much happier as a result). As a result, they forked the original Gnome2 and renamed it Mate. So your version of Keyring might be named mate-keyring. If it is, simply substitute mate-keyring everywhere I say gnome-keyring.

Installing Gnome Keyring

To install Gnome Keyring on Fedora, as root run:

dnf install gnome-keyring gnome-keyring-pam seahorse pinentry-gnome3

PAM

PAM stands for Pluggable Authentication Modules. It is used when Linux is trying to determine whether you should be allowed to log in. There are various ways you can login, and each is represented by a PAM module that is configured in /etc/pam.d.

For you to use Keyring, it should be started by PAM when you login. If it is started successfully, you should see a:

gnome-keyring-daemon --daemonize --login

process running after you log in. Look for it using:

ps aux | grep keyring

If it is not running it is because PAM has not been properly configured to start the Keyring daemon for the method you used to login. If you logged in using a GUI from the keyboard, then you are using a display manager such as Gnome, KDE, XFCE, LXDE, or slim. I happen to use lightdm, so I need to make sure lightdm is configured to run Keyring. To do so, edit /etc/pam.d/lightdm and assure that:

auth optional pam_gnome_keyring.so

is present at the end of the auth section and:

session optional pam_gnome_keyring.so auto_start

is present at the end of the session section. A leading dash indicates that the line should be skipped corresponding PAM library is not available.

Having PAM start Keyring for you is optional, but if you do it, it will automatically unlock your login keyring (assuming that your login password is the same as the password for your login keyring). This allows you access to passwords and pass phrases that you entered in previous login sessions. If you do not have PAM start Keyring for you, will not be given the option to automatically unlock a password every time you login.

Running Gnome Keyring

If you configured Keyring in PAM, it will start it automatically for you when you log in, but at this point it cannot do much. There are a few additional things that must be done before you can access it. In particular, you must:

Activate the components that you want
Pass information about Keyring to your environment so that other programs are aware of it
Provide the information needed by Keyring to allow it to connect to dbus, which is used by certain programs to access Keyring.

Dbus

Let’s start with #3 first. Dbus is a message-passing system used by applications to talk to one another. For example, Network Manager uses dbus to talk to Keyring. Normally it is started by your session manager when you log in. If it was, you should see the DBUS_SESSION_BUS_ADDRESS environment variable set:

printenv | grep DBUS

This environment variable must be set before running Keyring in order for Keyring to be accessible from dbus. If it is not, you should arrange for dbus to be started when you login. Generally this is done by your session manager by running dbus-launch. There is considerable amount of variability on how this is done. Here is my understanding as to generally how this process works:

If you are using a display manager then X11 is running before you login and xdm will give you a choice of possible sessions you can run when you login. The available sessions are described to xdm in /usr/share/xsessions. Part of this description is the command that will be run to set up your desktop after you login. This command is run from /etc/X11/xinit/Xsession. This command is generally a shell script that will eventually start your window manager. Somewhere along this path it must go through dbus-launch. In my case, I use a session I have named ‘xsession’ that basically just runs my ~/.xsession script. To do so, I configured /usr/share/xsessions/xsession.desktop to include:

[Desktop Entry]
Name=xsession
Comment=Run users ~/.xsession file
Exec=dbus-launch --exit-with-session ~/.xsession
Type=Application

Notice that this causes /etc/X11/xinit/Xsession to run dbus-launch, which in turn runs ~/.xsession. In this way, dbus-launch runs dbus and sets DBUS_SESSION_BUS_ADDRESS, which is passed into the environment for ~/.xsession, and so it is set in any processes spawned either directly or indirectly from ~/.xsession. In particular it will be available to Keyring when we start it, as it happens, from ~/.xsession.

Dbus should only be started once per user. It is a communication bus that allows various processes to talk to each other. If you somehow start it more than once, then you will have multiple busses running, and any process that attaches to one bus will not be able to communicate to processes attached to the other. This caused me a great deal of trouble once. I had blindly followed advice I found online to start nm-applet using:

dbus-launch nm-applet    # don't do this

As a result, I had two copies of dbus running, with Keyring attached to one and Network Manager to the other. Network Manager was isolated from Keyring and so authentication in Network Manager never worked right.

Another way to start dbus is to run if from your X start up file (typically ~/.xsession if using xdm, ~/.xinitrc if using startx, or ~/.config/openbox/environment if using openbox). When doing so, it is a good idea to test for the presence of DBUS_SESSION_BUS_ADDRESS and not start it again if it is already running. You can do that with (assuming you are using bash, at least for your start up script):

if test -z "$DBUS_SESSION_BUS_ADDRESS"; then
   eval $(dbus-launch --sh-syntax --exit-with-session)
fi

If you start dbus, or if it is started for you, but do not start Keyring, it is possible that dbus might well start it for you automatically. There are settings in /usr/share/dbus-1/services/org.gnome.keyring*.service that suggest this.

Keyring

To activate the desired Keyring components and pass information about Keyring to your environment (#1 and #2 from above) you would place the following in your X start up file (typically ~/.xsession if using xdm or ~/.xinitrc if using startx):

export $(gnome-keyring-daemon --start --components=pkcs11,secrets,ssh)

To do so, your start up script must be interpreted by bash (or another bash-like shell such as sh, ksh, or zsh (specifically it cannot be interpreted by either csh or tcsh)) because the output from gnome-keyring-daemon is only compatible with bash-like shells. This particular invocation explicitly starts all currently available Keyring components, though it is my understanding that leaving the –components option off does the same thing.

After running this command, you should find the following three environment variables set: GNOME_KEYRING_CONTROL, SSH_AUTH_SOCK, GPG_AGENT_INFO.

Be aware that this might not be necessary. Session managers will automatically activate your Keyring components. They do so using:

/etc/xdg/autostart/gnome-keyring-*.desktop

If your session manager is activating your Keyring components for you and you wish it wouldn’t, you might have to delete one or more of these files.

Logging

This is one aspect of Keyring that I do not completely understand. I have found that you can access logging information from Keyring using:

journalctl | grep -i gnome-keyring-daemon

This command can run very slowly because the journal can be quite large. An alternative is to run:

journalctl -f

which only outputs new journal entries as they become available (very much like ‘journalctl | tail -f’).

journalctl prints the systemd journal, which is apparently where a lot of these types of messages show up.

Applications

SSH

Keyring provides an SSH agent, meaning it will unlock and serve your private SSH keys to ssh, sftp, and scp so that you can run these programs without needing to unlock the keys each time.

Keyring will look in your SSH directory (~/.ssh) and automatically load and try to unlock any private keys it finds if there is also a corresponding public key. Meaning that if there is a private key in a file named foo, there should also be a public key in foo.pub.

You can also manually add private keys to the agent using:

ssh-add <private-key-file>

You can list available keys using:

ssh-add -L

For this to work properly, the environment variable SSH_AUTH_SOCK must be set by Keyring. In addition you should not also run ssh-agent. Doing so would start another ssh-agent that could override the one provided by Keyring. To check this, run:

echo $SSH_AUTH_SOCK

It should print out something like: /home/ken/.cache/keyring-eAtOYG/ssh (notice that ‘keyring’ is in the path to the socket). If SSH_AUTH_SOCK is not set, then it may be that Keyring is not running, it was not run in a parent shell of your current shell, or somehow the environment variable was unset. If it is set but does not contain ‘keyring’, then it was overwritten by a subsequent invocation of ssh-agent.

To get SSH working with Keyring, set the SSH_ASKPASS environment variable as follows:

export SSH_ASKPASS=/usr/libexec/seahorse/ssh-askpass

It used to be that Gnome Keyring did not support the latest styles of keys, such as the ed25519 keys. However, as of GNOME 3.28, Keyring now wraps OpenSSH’s ssh-agent, which gives it the same level of support as OpenSSH.

GPG

Keyring used to provide a GPG agent, but their implementation was incomplete and caused trouble for users of smart cards. Instead they now provide an alternate implementation of pinentry, the little menu application that requests passphrases from users. To use GPG with Keyring, you must install the pinentry-gnome3 package.

Then, to assure GPG uses the gnome3 pinentry program, edit ~/.gnupg/gpg-agent.conf and add:

pinentry-program /usr/bin/pinentry-gnome3

Network Manager

Network Manager will use Keyring to store WiFi and VPN passwords if they are not configured for use by all users. nm-applet is the program that puts the Network Manager icon in your system tray. It allows you to connect to a WiFi or VPN network. If you want Keyring to store your passwords, make sure that “All user may connect to this network” is not checked (right click on nm-applet, select “Edit Connections”, select the connection you want, click Edit, and select the General tab).

Network Manager will store passwords in plain text in /etc/sysconfig/network-scripts/keys-* if it does not use Keyring (though these files should only be readable by root). If it uses Keyring, the files still exist but should be empty.

Network Manager communicates with Keyring through dbus.

Seahorse

Seahorse is the GUI program that allows you to examine and modify the state of Keyring. It will allow you to see your passwords and pass phrases, so you should be very careful to restrict access to your desktop. In generally, only you should be allowed access to your desktop. If you feel the need to allow someone else to access your desktop, then you should first lock you keyrings (specifically your login keyring). To do so, run seahorse, select View and choose ‘By Keyring’ and then click on the lock icons until they are all closed.

Once Seahorse is open, you should see a Login keyring. If not, then something is wrong with your PAM setup and your keyring is not being unlocked as you login.

Security

When running Keyring your various passwords and private keys are available to you. So you need to be very careful that nobody else can access your desktop. Generally the best way to do this is to run a screenlock program and run it religiously whenever you step away from your machine.

It Is Not Working

Here are some things to check …

If Keyring is available, but by default your login keyring is not unlocked:

Are all the needed packages installed: gnome-keyring, gnome-keyring-pam, seahorse, and pinentry-gnome3?
Is PAM starting Keying? Run grep keyring /etc/pam.d/* and see if keyring is properly configured in your desired module.
Did you accidentally start another Keyring? Use ‘ps aux | grep keyring’ and look to see if you are running more keyring processes than you expect)

If SSH or GPG seem to be ignoring Keyring:

Is Keyring running? Use ‘ps aux | grep keyring’ and assure that there is a running keyring process owned by you.
Is pinentry-gnome3 installed?
Are the appropriate environment variables set? Run:
```
echo $GNOME_KEYRING_CONTROL
echo $SSH_AUTH_SOCK
```
and assure that each is set (if the corresponding component was requested) and set reasonably. If not, run “export $(gnome-keyring-daemon -s)” in your X11 start up file.

If Network Manager seems to be ignoring Keyring:

Were both gnome-keyring and nm-applet run after dbus was started? Was the DBUS_SESSION_BUS_ADDRESS environment variable properly set and picked up by both gnome-keyring and nm-applet?
Assure that only one dbus was run (consider running “echo $DBUS_SESSION_BUS_ADDRESS” just before running gnome-keyring and nm-applet and assure that you see the same address.

If, when keyring requests a passphrase, you are not offered the ability to unlock that passphrase when logging in, or if you are being asked for passphrases that you previously instructed should be unlocked when logging in, or if you open seahorse, select view by keyring, and notice that the “Login” keyring is locked without you explicitly locking it, then you have a PAM problem. Your login keyring is not being unlocked when you log in. This occurs because PAM is not correctly configured for keyring. Make sure you have gnome-keyring-pam installed, and that you have edited the file in /etc/pam.d that corresponds to you login manager. The entries are probably already in there but by default they are commented out. You will need to uncomment them by removing the dash at the beginning of the line. For example, I use lightdm as my login manager. My /etc/etc.d/lightdm config file contains the following lines that correspond to keyring:

auth       optional    pam_gnome_keyring.so
-auth       optional    pam_mate_keyring.so

session    optional    pam_gnome_keyring.so auto_start
-session    optional    pam_mate_keyring.so auto_start

Notice that I have removed the dashes from the lines that correspond to Gnome Keyring to activate it. Once you do this and re-login, you should be able to open seahorse and see that your login keyring is unlocked.

Finally, try examining /var/log/messages. Perhaps some clue can be found there. For security reasons, I was deleting the ~/.cache directory when shutting down my machine. Gnome Keyring uses ~/.cache to hold the unlocked keyrings, but will not create it if it does not exist. I was able to debug this when I found messages from keyring in /var/log/messages indicating that there were problems with ~/.cache. Simply recreating an empty ~/.cache directory after deleting the old one was a successful work around to this particular problem.