Jump to content
From ArchWiki
< GNOME

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.

  https://wiki.gnome.org/Projects/Libsecret || libsecret

- lssecret — List all secret items using libsecret (e.g. GNOME Keyring).

  https://gitlab.com/GrantMoyer/lssecret || lssecret-gitAUR

## 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

Note: To use automatic unlocking without automatic login, the password for the user account should be the same as the default keyring. See #Automatically change keyring password with user password.
Tip:

- 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. See [1] for more details.
- If you desire to skip the PAM step, the default keyring must be unlocked manually or via another method. See #Launching 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

## 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 an 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.

From GNOME 41 (released September 2021) until at least this writing (April 2023), the SSH functionality of gnome-keyring-daemon has been duplicated into `/usr/lib/gcr-ssh-agent`, which is part of gcr. The eventual plan is to remove the implementation in gnome-keyring-daemon, but that effort seems to have stalled. Until that happens, you should be aware of which implementation you're using, since each is set up and used in a different way:

### gcr-ssh-agent

The gcr-ssh-agent implementation is the more plug-and-play of the two. Since it will also eventually be the only implementation, you should use it unless you have good reason not to.

All you need to do to use this implementation is

1. Enable the `gcr-ssh-agent.socket` systemd user unit, e.g. by running `systemctl --user enable gcr-ssh-agent.socket`.
2. Run SSH commands with the `SSH_AUTH_SOCK` environment variable set to `$XDG_RUNTIME_DIR/gcr/ssh`. There are many ways to set environment variables, and the one you use will depend on your specific setup and preferences.

### gnome-keyring-daemon "ssh" component

If you do decide to use the older gnome-keyring-daemon implementation, you'll need to ensure `gnome-keyring-daemon` gets started with ssh in its `--components` argument. For desktop environments using XDG Autostart, that's done via `/etc/xdg/autostart/gnome-keyring-ssh.desktop` automatically. For others, you'll need to edit `ExecStart` of the `gnome-keyring-daemon.service` user unit, since it doesn't start the SSH component by default. See Systemd#Editing provided units for guidance.

Once you've ensured the component runs, set `SSH_AUTH_SOCK` to `$XDG_RUNTIME_DIR/keyring/ssh` in the same manner described above. Note that gcr-ssh-agent and gnome-keyring-daemon listen on different socket paths despite containing nearly-identical implementations.

### Using

Regardless of the implementation you choose, 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 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:

Note: You have to have the corresponding .pub file in the same directory as the private key (`~/.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's a good idea to disable GNOME Keyring's ssh-agent wrapper. Doing so isn't 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.

To disable the gcr-ssh-agent implementation, ensure `gcr-ssh-agent.socket` and `gcr-ssh-agent.service` are both disabled and stopped in systemd.

To disable the gnome-keyring-daemon implementation in an account-local way, copy `/etc/xdg/autostart/gnome-keyring-ssh.desktop` to `~/.config/autostart/` and then append the line `Hidden=true` to the copied file. Also undo any `gnome-keyring-daemon.service` edits you made as per the above instructions.

## Tips and tricks

### Integration with applications

- Chromium

### 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

Note: This only affects the default keyring.

Add `password optional pam_gnome_keyring.so` to the end of `/etc/pam.d/passwd`.

    /etc/pam.d/passwd

    #%PAM-1.0

    #password	required	pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3
    #password	required	pam_unix.so sha512 shadow use_authtok
    password	required	pam_unix.so sha512 shadow nullok
    password	optional	pam_gnome_keyring.so

### Launching gnome-keyring-daemon outside desktop environments (KDE, GNOME, XFCE, ...)

The factual accuracy of this article or section is disputed.

Reason: At least xinit and SDDM execute all scripts from `/etc/X11/xinit/xinitrc.d/` and sway provides `/etc/sway/config.d/50-systemd-user.conf` so the problem is not being "outside desktop environments". If gnome-keyring requires XDG Autostart, the installation/configuration section should say so. (Discuss in Talk:GNOME/Keyring#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/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.

## 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 [2].

### No such secret collection at path: /

If you use a custom `~/.xinitrc` and receive this error when trying to create a new keyring with Seahorse, this may be solved by adding the following line [3]

    ~/.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.

## See also

- https://help.gnome.org/users/seahorse/stable/
- GNOME Wiki page

Category:

- GNOME

Hidden category:

- Pages or sections flagged with Template:Accuracy