GNOME/Keyring: Difference between revisions

From ArchWiki
VisualWikitext
m (Fix path of gcr-ssh-agent in package gcr-4 /usr/lib/gcr-ssh-agent)
 
(147 intermediate revisions by 37 users not shown)
Line 1: Line 1:
[[Category:GNOME]]
[[Category:GNOME]]
[[Category:OpenPGP]]
[[es:GNOME (Español)/Keyring]]
[[es:GNOME (Español)/Keyring]]
[[ja:GNOME Keyring]]
[[ja:GNOME/Keyring]]
[[zh-hans:GNOME Keyring]]
[[zh-hans:GNOME/Keyring]]
 
{{Related articles start}}
{{Related|GnuPG}}
{{Related|OpenPGP}}
{{Related articles end}}
 
[https://wiki.gnome.org/Projects/GnomeKeyring GNOME Keyring] is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."
[https://wiki.gnome.org/Projects/GnomeKeyring GNOME Keyring] is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."
== Security model ==
There was a security issue (known as [https://nvd.nist.gov/vuln/detail/CVE-2018-19358 CVE-2018-19358]) reported in the past regarding the behaviour of the GNOME/Keyring API. Any application [https://github.com/sungjungk/keyring_crack 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 [https://gitlab.gnome.org/GNOME/gnome-keyring/-/issues/5#note_1876550 disagrees] with this vulnerability report because, according to the security model, untrusted applications must not be allowed to access the user's session bus socket.
Applications sandboxed via flatpak only have filtered access to the session bus.


== Installation ==
== Installation ==


When using GNOME, {{Pkg|gnome-keyring}} is installed automatically as a part of the {{grp|gnome}} group. Otherwise [[install]] the {{Pkg|gnome-keyring}} package. Install {{Pkg|libsecret}} to allow applications to use your keyrings. {{Pkg|libgnome-keyring}} is deprecated, however, some applications may require it.
{{Pkg|gnome-keyring}} is a member of the {{Grp|gnome}} group is thus usually present on systems running GNOME. The package can otherwise be [[install]]ed on its own. {{Pkg|libsecret}} should also be installed to grant other applications access to your keyrings. Although {{Pkg|libgnome-keyring}} is deprecated (and superseded by ''libsecret''), it may still be required by certain applications.


Extra utilities related to GNOME keyring include:
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.
* {{App|secret-tool|Access the GNOME keyring (and any other service implementing the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API]) from the command line.|https://wiki.gnome.org/Projects/Libsecret|{{Pkg|libsecret}}}}
* {{App|gnome-keyring-query|Provides a simple command-line tool for querying passwords from the password store of the GNOME Keyring. (uses the deprecated {{Pkg|libgnome-keyring}})||{{AUR|gnome-keyring-query}}}}
* {{App|gkeyring|Query passwords from the command line. (uses the deprecated {{Pkg|libgnome-keyring}})|https://github.com/kparal/gkeyring|{{AUR|gkeyring}}, {{AUR|gkeyring-git}}}}


== Manage using GUI ==
Extra utilities related to GNOME Keyring include:


You can manage the contents of GNOME Keyring using Seahorse. [[Install]] it with the package {{Pkg|seahorse}}.
* {{App|secret-tool|Access the GNOME Keyring (and any other service implementing the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API]) from the command line.|https://wiki.gnome.org/Projects/Libsecret|{{Pkg|libsecret}}}}
* {{App|lssecret|List all secret items using ''libsecret'' (e.g. GNOME Keyring).|https://gitlab.com/GrantMoyer/lssecret|{{AUR|lssecret-git}}}}


It is possible to leave the GNOME keyring password blank or change it. In seahorse, in the "View" drop-down menu, select "By Keyring". On the Passwords tab, right click on "Passwords: login" and pick "Change password." Enter the old password and leave empty the new password. You will be warned about using unencrypted storage; continue by pushing "Use Unsafe Storage."
== Manage using GUI ==


== Using the keyring outside GNOME ==
You can manage the contents of GNOME Keyring using Seahorse; [[install]] the {{Pkg|seahorse}} package.


=== Without a display manager ===
Passwords for keyrings (e.g., the default keyring, "Login") can be changed and even removed. See [https://help.gnome.org/users/seahorse/stable/keyring-create.html Create a new keyring] and [https://help.gnome.org/users/seahorse/stable/keyring-update-password.html Update the keyring password] in GNOME Help for more information.


==== Automatic login ====
== Using the keyring ==


If you are using automatic login, then you can disable the keyring manager by setting a blank password on the login 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.
{{Note| The passwords are stored unencrypted in this case.}}


==== Console login ====
=== PAM step ===


When using console-based login, the keyring daemon can be started by either [[PAM]] or [[xinitrc]]. PAM can also unlock the keyring automatically at login.
{{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 [[Mkinitcpio#Common hooks|systemd init in your mkinitcpio.conf]] as well as the [[Dm-crypt/System configuration#Using systemd-cryptsetup-generator|appropriate kernel parameters]]. See [https://reddit.com/r/Fedora/comments/jwnqq5/] for more details.
* If you desire to skip the PAM step, the default keyring must be unlocked manually or via another method. See [[#Using gnome-keyring-daemon outside desktop environments (KDE, GNOME, XFCE, ...)]] and the [https://wiki.gnome.org/Projects/GnomeKeyring/RunningDaemon GnomeKeyring wiki].
}}


===== PAM method =====
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 {{ic|/etc/pam.d/login}} as mentioned below.


Start the gnome-keyring-daemon from {{ic|/etc/pam.d/login}}:
When using console-based login, edit {{ic|/etc/pam.d/login}}:


Add {{ic|auth optional pam_gnome_keyring.so}} at the end of the {{ic|auth}} section and {{ic|session optional pam_gnome_keyring.so auto_start}} at the end of the {{ic|session}} section.
Add {{ic|auth optional pam_gnome_keyring.so}} at the end of the {{ic|auth}} section and {{ic|session optional pam_gnome_keyring.so auto_start}} at the end of the {{ic|session}} section.
Line 41: Line 58:
{{hc|/etc/pam.d/login|
{{hc|/etc/pam.d/login|
#%PAM-1.0
#%PAM-1.0
 
auth      required    pam_securetty.so
auth      required    pam_securetty.so
auth      requisite    pam_nologin.so
auth      requisite    pam_nologin.so
auth      include      system-local-login
auth      include      system-local-login
auth      optional    pam_gnome_keyring.so'''
'''auth      optional    pam_gnome_keyring.so'''
account    include      system-local-login
account    include      system-local-login
session    include      system-local-login
session    include      system-local-login
session    optional    pam_gnome_keyring.so auto_start'''}}
'''session    optional    pam_gnome_keyring.so auto_start'''
}}
 
{{Note|If using the [[greetd]] login manager, the file that needs to be modified is {{ic|/etc/pam.d/greetd}}, instead of {{ic|/etc/pam.d/login}}.}}
 
== SSH keys ==
 
GNOME Keyring can act as a wrapper around [[SSH keys#ssh-agent|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 [https://gitlab.gnome.org/GNOME/gnome-keyring/-/commit/25c5a1982467802fa12c6852b03c57924553ba73 1:46]. It has been [https://gitlab.gnome.org/GNOME/gcr/-/merge_requests/67 moved] into {{ic|/usr/lib/gcr-ssh-agent}}, which is part of the {{Pkg|gcr-4}} package. The [https://fedoraproject.org/wiki/Changes/ModularGnomeKeyring plan] is to completely remove the implementation in gnome-keyring-daemon.
 
=== Setup gcr ===
 
All you need to do is
# [[Enable]] the {{ic|gcr-ssh-agent.socket}} systemd [[user unit]].
# Run SSH commands with the {{ic|SSH_AUTH_SOCK}} environment variable set to {{ic|$XDG_RUNTIME_DIR/gcr/ssh}}. There are [[Environment variables#Defining variables|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 {{ic|SSH_AUTH_SOCK}} correctly.


For [[SDDM]], edit instead the configuration file {{ic|/etc/pam.d/sddm}}.
To permanently save a passphrase in the keyring, use ssh-askpass from the {{pkg|seahorse}} package:


Next, for [[GDM]], add {{ic|password optional pam_gnome_keyring.so}} to the end of {{ic|/etc/pam.d/passwd}}.
$ /usr/lib/seahorse/ssh-askpass ''my_key''
{{hc|/etc/pam.d/passwd|2=
#%PAM-1.0


#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3
To manually add an SSH key from another directory:
#password required pam_unix.so sha512 shadow use_authtok
password required pam_unix.so sha512 shadow nullok
password optional pam_gnome_keyring.so'''}}


{{Note|
$ ssh-add ~/.private/id_rsa
* To use automatic unlocking, the same password for the user account and the keyring have to be set.
Enter passphrase for ~/.private/id_rsa:
* You will still need the code in {{ic|~/.xinitrc}} below in order to export the environment variables required.}}


===== xinitrc method =====
{{Note|You have to have the corresponding ''.pub'' file in the same directory as the private key ({{ic|~/.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, {{ic|my_key.pub}}).}}


Start the gnome-keyring-daemon from [[xinitrc]]:
To disable all manually added keys:


{{hc|~/.xinitrc|<nowiki>
$ ssh-add -D
eval $(/usr/bin/gnome-keyring-daemon --start --components=pkcs11,secrets,ssh)
export SSH_AUTH_SOCK
</nowiki>}}


See [[Xfce#SSH agents]] for use in Xfce.
=== Disabling ===


=== With a display manager ===
If you wish to run an alternative SSH agent (e.g. [[SSH keys#ssh-agent|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 {{ic|SSH_AUTH_SOCK}} can be used to choose between them, but it can make debugging issues easier.


When using a display manager, the keyring works out of the box for most cases. The following display managers automatically unlock the keyring once you log in:
To disable gcr-ssh-agent, ensure {{ic|gcr-ssh-agent.socket}} and {{ic|gcr-ssh-agent.service}} are both disabled and stopped in systemd.
* [[GDM]]
* [[LightDM]]
* [[LXDM]]
* [[SDDM]]


For GDM and LightDM, note the keyring [https://wiki.gnome.org/Projects/GnomeKeyring/Pam must be] named ''login'' to be automatically unlocked.
== Tips and tricks ==


To enable the keyring for applications run through the terminal, such as SSH, add the following to your {{ic|~/.bash_profile}}, {{ic|~/.zshenv}}, or similar:
=== Integration with applications ===


{{hc|~/.bash_profile|<nowiki>
* [[Chromium#Force a password store|Chromium]]
if [ -n "$DESKTOP_SESSION" ];then
 
    eval $(gnome-keyring-daemon --start)
=== Flushing passphrases ===
    export SSH_AUTH_SOCK
fi</nowiki>}}


{{hc|~/.config/fish/config.fish|<nowiki>
$ gnome-keyring-daemon -r -d
if test -n "$DESKTOP_SESSION"
    set (gnome-keyring-daemon --start | string split "=")
end</nowiki>}}


== SSH keys ==
This command starts gnome-keyring-daemon, shutting down previously running instances.


To add your SSH key:
=== Git integration ===


$ ssh-add ~/.ssh/id_rsa
The GNOME keyring is useful in conjunction with [[Git]] when you are pushing over HTTPS. The {{Pkg|libsecret}} package [[#Installation|needs to be installed for this functionality to be available]].
Enter passphrase for /home/mith/.ssh/id_rsa:


To list automatically loaded keys:
Configure Git to use the ''libsecret'' helper:


  $ ssh-add -L
  $ git config --global credential.helper /usr/lib/git-core/git-credential-libsecret


To disable all keys:
The next time you run {{ic|git push}}, you will be asked to unlock your keyring if it is not already unlocked.


$ ssh-add -D
=== GnuPG integration ===


Now when you connect to a server, the key will be found and 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!
Several applications which use GnuPG require a {{ic|pinentry-program}} to be set. Set the following to use GNOME 3 pinentry for GNOME Keyring to manage passphrase prompts.


Alternatively, to permanently save the a passphrase in the keyring, use ssh-askpass from package {{pkg|seahorse}}:
{{hc|~/.gnupg/gpg-agent.conf|
pinentry-program /usr/bin/pinentry-gnome3
}}


/usr/lib/seahorse/ssh-askpass my_key
Another option is to [[GnuPG#Unattended passphrase|force loopback for GPG]] which should allow the passphrase to be entered in the application.


{{Note|You have to have the corresponding {{ic|.pub}} file in the same directory as the private key ({{ic|~/.ssh/id_rsa.pub}} in the example). Also, make sure that the public key is the file name of the private key plus {{ic|.pub}} (for example, {{ic|my_key.pub}}).}}
=== Renaming a keyring ===
=== Start SSH and Secrets components of keyring daemon ===


If you are starting Gnome Keyring with a display manager or the Pam method described above and you are NOT using Gnome, Unity or Mate as your desktop you may find that the SSH and Secrets components are not being started automatically.
The display name for a keyring (i.e., the name that appears in Seahorse and from {{ic|file}}) can be changed by [https://ttboj.wordpress.com/2013/01/27/renaming-a-gnome-keyring-for-seahorse-the-passwords-and-keyrings-application/ changing the value of display-name in the unencrypted keyring file]. Keyrings will usually be stored in {{ic|~/.local/share/keyrings/}} with the ''.keyring'' file extension.
You can fix this by copying the desktop files gnome-keyring-ssh.desktop and gnome-keyring-secrets.desktop from {{ic|/etc/xdg/autostart/}} to {{ic|~/.config/autostart/}} and deleting the OnlyShowIn line.


$ cp /etc/xdg/autostart/{gnome-keyring-secrets.desktop,gnome-keyring-ssh.desktop} ~/.config/autostart/
=== Automatically change keyring password with user password ===
$ sed -i '/^OnlyShowIn.*$/d' ~/.config/autostart/gnome-keyring-secrets.desktop
$ sed -i '/^OnlyShowIn.*$/d' ~/.config/autostart/gnome-keyring-ssh.desktop


=== Disable keyring daemon components ===
{{Note|This only affects the default keyring.}}


If you wish to run an alternative SSH agent (e.g. [[SSH keys#ssh-agent|ssh-agent]] or [[GnuPG#gpg-agent|gpg-agent]]), you need to disable the {{ic|ssh}} component of GNOME Keyring.
[[Append]] {{ic|password optional pam_gnome_keyring.so}} to {{ic|/etc/pam.d/passwd}}:
To do so in an account-local way, copy {{ic|/etc/xdg/autostart/gnome-keyring-ssh.desktop}} to {{ic|~/.config/autostart/}} and then append the line {{ic|1=Hidden=true}} to the copied file. Then log out.


{{Note|In case you use [[GNOME]] 3.24 or older on [[Wayland]], gnome-shell will overwrite {{ic|SSH_AUTH_SOCK}} to point to gnome-keyring regardless if it is running or not. To prevent this, you need to set the environment variable GSM_SKIP_SSH_AGENT_WORKAROUND before gnome-shell is started. One way to do this is to add the line {{ic|1=GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT=1}} to {{ic|~/.pam_environment}}.}}
{{hc|/etc/pam.d/passwd|2=
...
password optional pam_gnome_keyring.so
}}


== Tips and tricks ==
=== Using gnome-keyring-daemon outside desktop environments (KDE, GNOME, XFCE, ...) ===


=== Integration with applications ===
==== Launching ====


* [[Firefox#KDE.2FGNOME_integration|Firefox]]
{{Accuracy|At least [[xinit]] and [[SDDM]] execute all scripts from {{ic|/etc/X11/xinit/xinitrc.d/}} and [[sway]] provides {{ic|/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.|section=Launching gnome-keyring-daemon outside desktop environments (KDE,_GNOME,_XFCE,_...)}}


=== Flushing passphrases ===
If you are using sway, i3, or any window manager that does not execute


gnome-keyring-daemon -r -d
* {{ic|/etc/xdg/autostart/gnome-keyring-*.desktop}}
* {{ic|/etc/X11/xinit/xinitrc.d/50-systemd-user.sh}}


This command starts gnome-keyring-daemon, shutting down previously running instances.
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.


=== Git integration ===
{{bc|dbus-update-activation-environment DISPLAY XAUTHORITY WAYLAND_DISPLAY}}
or
{{bc|dbus-update-activation-environment --all}}


The GNOME keyring is useful in conjuction with [[Git]] when you are pushing over HTTPS.
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.


[[Install]] the {{Pkg|libsecret}} package.  
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.


Set Git up to use the helper:
{{bc|1=gnome-keyring-daemon --start --components=secrets}}
$ git config --global credential.helper /usr/lib/git-core/git-credential-libsecret


Next time you do a ''git push'', you are asked to unlock your keyring, if not unlocked already.
During login, PAM starts {{ic|gnome-keyring-daemon --login}} which is responsible for keeping gnome-keyring unlocked with login password. If {{ic|gnome-keyring-daemon --login}} is not connected to session dbus within a few minutes, {{ic|gnome-keyring-daemon --login}} dies. If {{ic|gnome-keyring-daemon --start ...}} is started against session dbus in a window manager, {{ic|gnome-keyring-daemon --login}} is connected to session dbus. If your login session does not start {{ic|gnome-keyring-daemon --start ...}} before {{ic|gnome-keyring-daemon --login}} quits, you can also use any program that uses gnome-keyring or secret service API before {{ic|gnome-keyring-daemon --login}} dies.


=== GnuPG integration ===
==== GNOME Keyring XDG Portal ====


Several applications which use GnuPG require a {{ic|pinentry-program}} to be set. Set the following to use Gnome 3 pinentry for Gnome Keyring to manage passphrase prompts.
{{Accuracy|Modifies package files in {{ic|/usr/share}}, will be undone on pacman upgrades}}
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 {{ic|/usr/share/xdg-desktop-portal/portals/gnome-keyring.portal}} configuration file by modifying the {{ic|UseIn}} key. For instance, to add [[sway]]:


{{hc|~/.gnupg/gpg-agent.conf|<nowiki>
{{hc|/usr/share/xdg-desktop-portal/portals/gnome-keyring.portal|
pinentry-program /usr/bin/pinentry-gnome3
[portal]
</nowiki>}}
DBusName{{=}}org.freedesktop.secrets
Interfaces{{=}}org.freedesktop.impl.portal.Secret
UseIn{{=}}gnome;sway
}}


Another option is to [[GnuPG#Unattended_passphrase|force loopback for GPG]] which should allow the passphrase to be entered in the application.
See [[XDG Desktop Portal#Backends]] for more information about XDG Desktop Portal backends.


== Troubleshooting ==
== Troubleshooting ==
Line 174: Line 201:
=== Passwords are not remembered ===
=== Passwords are not remembered ===


If you get a password prompt every time you login, and you find that passwords are not saved, you might need to create/set a default keyring.
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 [https://help.gnome.org/users/seahorse/stable/keyring-create.html Create a new keyring] and [https://help.gnome.org/users/seahorse/stable/keyring-change-default.html Change the default keyring] in GNOME Help.
 
=== Resetting the keyring ===
 
You will need to [[#Manage using GUI|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 {{ic|login.keyring}} and {{ic|user.keystore}} files from {{ic|~/.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


Ensure that the {{pkg|seahorse}} package is [[install]]ed, open it ("Passwords and Keys" in system settings) and select ''View'' > ''By Keyring''.
This message "can be safely ignored" if there are no other related issues [https://bbs.archlinux.org/viewtopic.php?pid=1940190#p1940190].
If there is no keyring in the left column (it will be marked with a lock icon), go to ''File'' > ''New'' > ''Password Keyring'' and give it a name. You will be asked to enter a password. If you do not give the keyring a password it will be unlocked automatically, even when using autologin, but passwords will not be stored securely. Finally, right-click on the keyring you just created and select "Set as default".


=== Resetting the keyring ===
=== No such secret collection at path: / ===
 
If you use a custom {{ic|~/.xinitrc}} and receive this error when trying to create a new keyring with Seahorse, this may be solved by adding the following line [https://bbs.archlinux.org/viewtopic.php?pid=1640822#p1640822]
 
{{hc|~/.xinitrc|
source /etc/X11/xinit/xinitrc.d/50-systemd-user.sh
}}


If you get the error "The password you use to login to your computer no longer matches that of your login keyring", you'll need to change the keyring password. You can do this using seahorse, by right-clicking on "default keyring", and selecting "Change Password".
=== Terminal gives the message "discover_other_daemon: 1" ===


Alternatively, you can remove "login.keyring" and "user.keystore" from ''/home/{username}/.local/share/keyrings/''. Be warned that this will permanently delete all saved keys. After removing the files, simply log out and log in again.
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 {{ic|.zshenv}}, {{ic|.bash_profile}}, {{ic|.xinitrc}}, {{ic|config.fish}} or similar. Alternatively you can [[disable]] the {{ic|gnome-keyring-daemon.service}} and {{ic|gnome-keyring-daemon.socket}} [[user unit]]s.


== See also ==
== See also ==
* [https://wiki.gnome.org/action/show/Projects/GnomeKeyring GNOME wiki]
 
* https://help.gnome.org/users/seahorse/stable/
* [https://wiki.gnome.org/action/show/Projects/GnomeKeyring GNOME Wiki page]

Latest revision as of 08:58, 13 March 2024


Related articles

GNOME Keyring is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."

Security model

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 the security model, untrusted applications must not be allowed to access the user's session bus socket.

Applications sandboxed via flatpak only have filtered access to the session bus.

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:

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
Note: If using the greetd login manager, the file that needs to be modified is /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. The plan is to completely remove the implementation in gnome-keyring-daemon.

Setup gcr

All you need to do is

  1. Enable the gcr-ssh-agent.socket systemd user unit.
  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.

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

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.

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

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.

GNOME Keyring XDG Portal

The factual accuracy of this article or section is disputed.

Reason: Modifies package files in /usr/share, will be undone on pacman upgrades (Discuss in Talk:GNOME/Keyring)

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

Retrieved from "https://wiki.archlinux.org/index.php?title=GNOME/Keyring&oldid=803101"