GNOME/Keyring
GNOME Keyring is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."
It provides org.freedesktop.secrets, an API that allows client applications to store secrets securely using a service running in the user's login session.
Security
Protection against malicious application
There was a security issue (known as CVE-2018-19358) reported in the past regarding the behaviour of the GNOME/Keyring API. Any application can easily read any secret if the keyring is unlocked. And, if a user is logged in, then the login/default collection is unlocked. Available D-Bus protection mechanisms (involving the busconfig and policy XML elements) are not used by default and would be easy to bypass anyway.
The GNOME project disagrees with this vulnerability report because, according to their stated security model, untrusted applications must not be allowed to communicate with the secret service.
Applications sandboxed via Flatpak only have filtered access to the session bus.
Keyring is not locked when session is locked
When the session is locked, the keyring is not automatically locked.[1] This means that the passwords remain in memory which opens the system up to a DMA attack.
Installation
gnome-keyring is a member of the gnome group is thus usually present on systems running GNOME. The package can otherwise be installed on its own. libsecret should also be installed to grant other applications access to your keyrings. Although libgnome-keyring is deprecated (and superseded by libsecret), it may still be required by certain applications.
The gnome-keyring-daemon is automatically started via a systemd user service upon logging in. It can also be started upon request via a socket.
Extra utilities related to GNOME Keyring include:
- secret-tool — Access the GNOME Keyring (and any other service implementing the DBus Secret Service API) from the command line.
- lssecret — List all secret items using libsecret (e.g. GNOME Keyring).
Manage using GUI
You can manage the contents of GNOME Keyring using Seahorse; install the seahorse package.
Passwords for keyrings (e.g., the default keyring, "Login") can be changed and even removed. See Create a new keyring and Update the keyring password in GNOME Help for more information.
Using the keyring
The PAM module pam_gnome_keyring.so initialises GNOME Keyring partially, unlocking the login keyring in the process. The gnome-keyring-daemon is automatically started with a systemd user service.
PAM step
- To use automatic unlocking with automatic login, you can set a blank password for the keyring. Note that the contents of the keyring are stored unencrypted in this case.
- Alternatively, if using GDM and LUKS, GDM can unlock your keyring if it matches your LUKS password. For this to work, you need to use the systemd init in your mkinitcpio.conf as well as the appropriate kernel parameters. See [2] for more details.
- If you desire to skip the PAM step, the keyring must be unlocked manually or via another method. See #Using gnome-keyring-daemon outside desktop environments (KDE, GNOME, XFCE, ...) and the GnomeKeyring wiki.
When using a display manager, the keyring works out of the box for most cases. GDM, LightDM, LXDM, and SDDM already have the necessary PAM configuration. For a display manager that does not automatically unlock the keyring edit the appropriate file instead of /etc/pam.d/login
as mentioned below.
When using console-based login, edit /etc/pam.d/login
:
Add auth optional pam_gnome_keyring.so
at the end of the auth
section and session optional pam_gnome_keyring.so auto_start
at the end of the session
section.
/etc/pam.d/login
#%PAM-1.0 auth required pam_securetty.so auth requisite pam_nologin.so auth include system-local-login auth optional pam_gnome_keyring.so account include system-local-login session include system-local-login session optional pam_gnome_keyring.so auto_start
/etc/pam.d/greetd
, instead of /etc/pam.d/login
.SSH keys
GNOME Keyring can act as a wrapper around ssh-agent. In that mode, it will display a GUI password entry dialog each time you need to unlock an SSH key. The dialog includes a checkbox to remember the password you type, which, if selected, will allow fully passwordless use of that key in the future as long as your login keyring is unlocked.
The SSH functionality is disabled by default in gnome-keyring-daemon builds since version 1:46. It has been moved into /usr/lib/gcr-ssh-agent
, which is part of the gcr-4 package.
Setup gcr
All you need to do is:
- Enable the
gcr-ssh-agent.socket
systemd user unit. - Start once the
gcr-ssh-agent.socket
systemd user unit. This will create socket file$XDG_RUNTIME_DIR/gcr/ssh
. Once file is created, 1st step is sufficient to have socket unit started automatically. - Manual configuration of
SSH_AUTH_SOCK
environment variable shall not be necessary, ifgcr-ssh-agent.socket
unit is active. The value ofSSH_AUTH_SOCK
environment variable shall be set to$XDG_RUNTIME_DIR/gcr/ssh
after user logs out and logs in. This is known to work with GnomeConsole
application for user usingfish
as default shell.
There are many ways to set environment variables, and the one you use will depend on your specific setup and preferences.
Using
You can run
$ ssh-add -L
to list loaded SSH keys in the running agent. This can help ensure you started the appropriate service and set SSH_AUTH_SOCK
correctly.
To permanently save a passphrase in the keyring, use ssh-askpass from the seahorse package:
$ /usr/lib/seahorse/ssh-askpass my_key
To manually add an SSH key from another directory:
$ ssh-add ~/.private/id_rsa Enter passphrase for ~/.private/id_rsa:
~/.ssh/id_rsa.pub
in the example). Also, make sure that the public key is the file name of the private key plus .pub (for example, my_key.pub
).To disable all manually added keys:
$ ssh-add -D
Disabling
If you wish to run an alternative SSH agent (e.g. ssh-agent directly or gpg-agent), it is a good idea to disable GNOME Keyring's ssh-agent wrapper. Doing so is not strictly necessary, since each agent listens on a different socket and SSH_AUTH_SOCK
can be used to choose between them, but it can make debugging issues easier. Note that the GNOME implementation does not support many scripting features such BatchMode [3].
To disable gcr-ssh-agent, ensure gcr-ssh-agent.socket
and gcr-ssh-agent.service
are both disabled and stopped in systemd.
Tips and tricks
Integration with applications
Locking a keyring
$ dbus-send --session --dest=org.freedesktop.secrets \ --type=method_call \ /org/freedesktop/secrets \ org.freedesktop.Secret.Service.Lock \ array:objpath:/org/freedesktop/secrets/collection/login
This command performs a D-Bus method call to lock the login keyring. Alternatively, if you want to use a GUI, Seahorse can be used lock the keyring.
Flushing passphrases
$ gnome-keyring-daemon -r -d
This command starts gnome-keyring-daemon, shutting down previously running instances.
Git integration
The GNOME keyring is useful in conjunction with Git when you are pushing over HTTPS. The libsecret package needs to be installed for this functionality to be available.
Configure Git to use the libsecret helper:
$ git config --global credential.helper /usr/lib/git-core/git-credential-libsecret
The next time you run git push
, you will be asked to unlock your keyring if it is not already unlocked.
GnuPG integration
Several applications which use GnuPG require a pinentry-program
to be set. Set the following to use GNOME 3 pinentry for GNOME Keyring to manage passphrase prompts.
~/.gnupg/gpg-agent.conf
pinentry-program /usr/bin/pinentry-gnome3
Another option is to force loopback for GPG which should allow the passphrase to be entered in the application.
Renaming a keyring
The display name for a keyring (i.e., the name that appears in Seahorse and from file
) can be changed by changing the value of display-name in the unencrypted keyring file. Keyrings will usually be stored in ~/.local/share/keyrings/
with the .keyring file extension.
Automatically change keyring password with user password
Append password optional pam_gnome_keyring.so
to /etc/pam.d/passwd
:
/etc/pam.d/passwd
... password optional pam_gnome_keyring.so
Using gnome-keyring-daemon outside desktop environments (KDE, GNOME, XFCE, ...)
Launching
If you are using sway, i3, or any window manager that does not execute
/etc/xdg/autostart/gnome-keyring-*.desktop
/etc/X11/xinit/xinitrc.d/50-systemd-user.sh
your window manager needs to execute the following commands during window manager startup. The commands do not need to be executed in any specific order.
dbus-update-activation-environment DISPLAY XAUTHORITY WAYLAND_DISPLAY
or
dbus-update-activation-environment --all
This command passes environment variables from the window manager to session dbus. Without this, GUI prompts cannot be triggered over DBus. For example, this is required for seahorse password prompt.
This is required because session dbus is started before graphical environment is started. Thus, session dbus does not know about the graphical environment you are in. Someone or something has to teach session dbus about the graphical environment by passing environment variables describing the graphical environment to session dbus.
gnome-keyring-daemon --start --components=secrets
During login, PAM starts gnome-keyring-daemon --login
which is responsible for keeping gnome-keyring unlocked with login password. If gnome-keyring-daemon --login
is not connected to session dbus within a few minutes, gnome-keyring-daemon --login
dies. If gnome-keyring-daemon --start ...
is started against session dbus in a window manager, gnome-keyring-daemon --login
is connected to session dbus. If your login session does not start gnome-keyring-daemon --start ...
before gnome-keyring-daemon --login
quits, you can also use any program that uses gnome-keyring or secret service API before gnome-keyring-daemon --login
dies.
GNOME Keyring XDG Portal
GNOME Keyring exposes an XDG Portal backend (for use with applications sandboxed through flatpak for example). In order for it to work outside of GNOME, one must add their desktop environment to the /usr/share/xdg-desktop-portal/portals/gnome-keyring.portal
configuration file by modifying the UseIn
key. For instance, to add sway:
/usr/share/xdg-desktop-portal/portals/gnome-keyring.portal
[portal] DBusName=org.freedesktop.secrets Interfaces=org.freedesktop.impl.portal.Secret UseIn=gnome;sway
See XDG Desktop Portal#Backends for more information about XDG Desktop Portal backends.
Troubleshooting
Passwords are not remembered
If you are prompted for a password after logging in and you find that your passwords are not saved, then you may need to create/set a default keyring. To do this using Seahorse (a.k.a. Passwords and Keys), see Create a new keyring and Change the default keyring in GNOME Help.
Resetting the keyring
You will need to change your login keyring password if you receive the following error message: "The password you use to login to your computer no longer matches that of your login keyring".
Alternatively, you can remove the login.keyring
and user.keystore
files from ~/.local/share/keyrings/
. Be warned that this will permanently delete all saved keys. After removing the files, simply log out and log in again.
Unable to locate daemon control file
The following error may appear in the journal after logging in:
gkr-pam: unable to locate daemon control file
This message "can be safely ignored" if there are no other related issues [4].
No such secret collection at path: /
If you try to add a new keyring with Seahorse you may receive this error due to the following reasons:
- The
~/.local/share/keyrings/
directory does not exist. Create it if missing. - A custom
~/.xinitrc
is used. This may be solved by adding the following line [5]
~/.xinitrc
source /etc/X11/xinit/xinitrc.d/50-systemd-user.sh
Terminal gives the message "discover_other_daemon: 1"
This is caused by gnome-keyring-daemon being started for the second time. Since a systemd service is delivered together with the daemon, you do not need to start it another way. So make sure to remove the start command from your .zshenv
, .bash_profile
, .xinitrc
, config.fish
or similar. Alternatively you can disable the gnome-keyring-daemon.service
and gnome-keyring-daemon.socket
user units.
Improper initialization of the keyring
There are a few symptoms of this:
- Programs like SSH or Git hang while waiting for the keyring to provide a password, eventually timing out with errors such as "agent refused operation".
- Seahorse does not display any keyring, and manually creating a keyring named "login" does not appear to do anything.
- The following error message appears in seahorse's output:
couldn't load all secret collections: No such secret collection at path: /org/freedesktop/secrets/collection/login
To address this, do the following:
- Restart the
gnome-keyring-daemon.service
systemd user unit. This should properly initialize the login keyring. - Restart the
gcr-ssh-agent.service
systemd user unit if used. Other agents might also need restarting.
If this does not fix the issue, consider resetting the keyring.