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:
yum install gnome-keyring gnome-keyring-pam seahorse
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 acts as a comment character in these pam files, so finding:
-auth optional pam_gnome_keyring.so -session optional pam_gnome_keyring.so auto_start
means that these options are not active. You should remove the dashes if you want pam to start keyring.
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.
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.
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,gpg)
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. The do so using:
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.
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:
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.
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:
You can list available keys using:
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:
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.
Be aware that GnomeKeyring is incompatible with the latest SSH key types (ECDSA and Ed25519) when operating as an SSH agent. This is a known problem and does not look like it is going to be resolved anytime soon.
Keyring provides a GPG agent, meaning it will unlock and serve your private GPG keys to gpg so that you decrypt and sign files without needing to unlock the keys each time.
Keyring will look in your GPG directory (~/.gnupg) and automatically load and try to unlock any private keys it finds if there.
For this to work properly, the environment variable GPG_AGENT_INFO must be set by Keyring. In addition you should not also run gpg-agent. Doing so would start another gpg-agent that could override the one provided by Keyring. To check this, run:
It should print out something like: /home/ken/.cache/keyring-eAtOYG/gpg:0:1 (notice that ‘keyring’ is in the path to the socket). If GPG_AGENT_INFO 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 gpg-agent.
Recently Werner Koch, the author of GPG, has taken a disliking to Gnome Keyring. Apparently it does not play well with GPG when you use smart cards, which causes a lot of problems for him, so he has recently put a warning message in GPG that is printed when GPG determines you are using Keyring. It is a pretty scary message along the lines of “The GNOME keyring manager hijacked the GnuPG agent”. This is nothing to worry about and can be ignored. However, if you are using Keyring and it is not working correctly with GPG, I would suggest that you not bother Werner about it. If the warning bothers you, the only thing I can suggest is downloading the source for GPG and simply deleting the warning message.
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 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.
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:
Is PAM starting Keying? Run
grep keyring /etc/pam.d/*and see if keyring is properly configured in your desired module (dash acts as a comment character in these files, so make sure the keyring lines do not start with a dash).
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.
Are the appropriate environment variables set? Run:
echo $GNOME_KEYRING_CONTROL echo $SSH_AUTH_SOCK echo $GPG_AGENT_INFO
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.
As of early 2016 with Fedora 23, I have noticed the following changes.
GPG: The gpg-agent is no longer using the GPG_AGENT_INFO or –write-env-file to communicate information about the agent to gpg. Instead it is using a unix socket: $GPGHOME/S.gpg-agent.
Gnome Keyring: It appears that Werner Koch might have been successful in his fight against Gnome Keyring. It appears as if the GPG component is no longer available. Indeed, rather than fighting they may be cooperating. Even though I am using gpg-agent rather than gnome-keyring-daemon as my GPG agent, the pinentry dialog offers to store permanently save the passphrase the password manager.
Maybe there is hope for the middle east yet.