GNOME/Keyring
GNOME Keyring is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."
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 default 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 default 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[broken link: invalid section]. See for more details.
- Skipping the PAM step works, because the next step[broken link: invalid section] will initialise the daemon when one is not running already; however, the default keyring is not unlocked in this case. More details are available at .
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 section and at the end of the section.
SSH keys
gnome-keyring-daemon with the ssh component will start an SSH agent and automatically load all the keys in ~/.ssh/ that have corresponding .pub files. There is no way to remove these keys from the agent.
To list all loaded keys:
$ ssh-add -L
When you connect to a server that uses a loaded key with a password, a dialog will popup asking you for the passphrase. It has an option to automatically unlock the key when you log in. If you check this, you will not need to enter your passphrase again!
To permanently save the 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:
To disable all manually added keys:
$ ssh-add -D
Enable the keyring ssh component
The default systemd user service shipped with the keyring does not include the ssh component. ssh must be added to the option of the command in the line of the unit file.
See Systemd#Editing provided units for how to edit the keyring's systemd unit file.
You must also enable the user unit and point an environment variable to the auth socket:
SSH_AUTH_SOCK=$XDG_RUNTIME_DIR/gcr/ssh
Tips and tricks
Integration with applications
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.
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 ) can be changed by changing the value of display-name in the unencrypted keyring file. Keyrings will usually be stored in with the .keyring file extension.
Automatically change keyring password with user password
Add to the end of .
Launching gnome-keyring-daemon outside desktop environments (KDE, GNOME, XFCE, ...)
If you are using sway, i3, or any window manager that does not execute
/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
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.
During login, PAM starts which is responsible for keeping gnome-keyring unlocked with login password. If is not connected to session dbus within a few minutes, dies. If is started against session dbus in a window manager, is connected to session dbus. If your login session does not start before quits, you can also use any program that uses gnome-keyring or secret service API before dies.
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 and files from . 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 .
No such secret collection at path: /
If you use a custom and receive this error when trying to create a new keyring with Seahorse, this may be solved by adding the following line
Terminal gives the message "discover_other_daemon: 1"
This is caused by gnome-keyring-deamon 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, , , or similar. Alternatively you can disable the gnome-keyring-daemon.service and user units.