Use the GNOME Keyring or KWallet

Every desktop Linux user eventually runs into a password prompt from GNOME Keyring or KWallet — usually at the worst possible time. These tools are secret storage daemons: they hold passwords, tokens, and private keys in an encrypted database on disk, unlocking it only after you authenticate. Understanding how they work stops the random unlock popups and lets you wire up SSH keys, browsers, and CLI tools cleanly.

What Stores Secrets and Where

GNOME Keyring (used on GNOME, XFCE, and many others) stores secrets in ~/.local/share/keyrings/. The default keyring is login.keyring, encrypted with your login password. KWallet (KDE Plasma) stores its wallets in ~/.local/share/kwalletd/ (KDE 5/6) or ~/.kde/share/apps/kwallet/ on older installs. Both daemons implement the Secret Service API (a D-Bus interface), so applications that use libsecret talk to whichever daemon is running.

You can inspect what is stored using GUI tools: Passwords and Keys (seahorse) for GNOME Keyring, and KWallet Manager for KWallet. Install them if missing:

# Debian/Ubuntu
sudo apt install seahorse

# Fedora
sudo dnf install seahorse

# Arch
sudo pacman -S seahorse

# KDE — KWallet Manager is usually pre-installed; if not:
# Debian/Ubuntu
sudo apt install kwalletmanager

# Fedora
sudo dnf install kwalletmanager

# Arch
sudo pacman -S kwalletmanager

Auto-Unlock at Login

The most common annoyance is the keyring unlocking after you have already logged in, showing a second password prompt. This happens when the keyring password differs from your login password, or when the PAM module is not wired up. Fix it by making them match and enabling the PAM module.

GNOME Keyring via PAM (Debian/Ubuntu and Fedora)

The gnome-keyring-daemon ships a PAM module that hooks into login. Check it is present:

ls /usr/lib/$(uname -m)-linux-gnu/security/pam_gnome_keyring.so 2>/dev/null || \
  ls /usr/lib64/security/pam_gnome_keyring.so 2>/dev/null

On GDM and most display managers the module is already configured. If you use a manual startx or a non-standard DM, add these lines to /etc/pam.d/login (at the end of the auth section and the session section respectively):

auth     optional  pam_gnome_keyring.so
session  optional  pam_gnome_keyring.so auto_start

Then make sure the keyring password matches your login password. Open Seahorse, right-click Login under Passwords, choose Change Password, and set it to your current login password. If you have forgotten the old keyring password entirely, delete the file and let it regenerate:

rm ~/.local/share/keyrings/login.keyring
# Log out and back in; a fresh keyring is created automatically.

KWallet Auto-Unlock

In KDE System Settings → KWallet, enable Automatically unlock wallet at login and ensure the wallet password equals your login password. KDE's SDDM display manager handles this automatically via the kwallet-pam package:

# Debian/Ubuntu
sudo apt install kwallet-pam

# Fedora
sudo dnf install kwallet-pam

# Arch
sudo pacman -S kwallet-pam

After installation, log out and back in. SDDM will pass your credentials to kwalletd and unlock the wallet before your desktop session starts.

Applications That Use libsecret

Applications using libsecret (the client library for the Secret Service API) will store and retrieve credentials transparently once the daemon is unlocked. This includes Chromium-based browsers, GNOME Online Accounts, NetworkManager, Evolution, and many CLI tools like git-credential-libsecret.

Wire Git to the Secret Service

Stop typing your Git tokens on every push by using the libsecret credential helper:

# Debian/Ubuntu — the helper needs to be compiled
sudo apt install libsecret-1-0 libsecret-1-dev git
cd /usr/share/doc/git/contrib/credential/libsecret
sudo make
git config --global credential.helper /usr/share/doc/git/contrib/credential/libsecret/git-credential-libsecret

# Fedora — pre-built
sudo dnf install git-credential-libsecret
git config --global credential.helper libsecret

# Arch
sudo pacman -S libsecret
git config --global credential.helper libsecret

The next time you authenticate to a remote, the token is saved to the keyring and retrieved silently afterwards.

SSH Agent Integration

GNOME Keyring includes a built-in SSH agent that loads keys from ~/.ssh/ and stores passphrases in the keyring. This is separate from ssh-agent and gpg-agent.

Verify the Agent Is Running

echo $SSH_AUTH_SOCK
# Should print a path like /run/user/1000/keyring/ssh

If the variable is empty, the daemon is not providing an SSH agent for your session. On a standard GNOME session it starts automatically via gnome-keyring-daemon --start --components=ssh, launched by the desktop session. Check systemd user units:

systemctl --user status gnome-keyring-daemon.service 2>/dev/null || \
  pgrep -a gnome-keyring

Add SSH Keys

ssh-add ~/.ssh/id_ed25519
# You will be prompted for the passphrase once; it is then stored in the keyring.

Seahorse also lists SSH keys under the OpenSSH keys section — you can add, remove, and view them there.

Prefer a Different SSH Agent

If you prefer ssh-agent (launched via systemd user socket) or gpg-agent's SSH support, disable GNOME Keyring's SSH component to avoid conflicts. Create an override file:

mkdir -p ~/.config/autostart
cp /etc/xdg/autostart/gnome-keyring-ssh.desktop ~/.config/autostart/
echo 'Hidden=true' >> ~/.config/autostart/gnome-keyring-ssh.desktop

Log out and back in. SSH_AUTH_SOCK will then point to your preferred agent instead.

Managing Secrets from the Command Line

The secret-tool utility (part of libsecret) lets you store and retrieve secrets in scripts without needing a GUI:

# Store a secret
secret-tool store --label="My API Token" service myapp username alice
# You will be prompted to type the secret value

# Retrieve it
secret-tool lookup service myapp username alice

# Delete it
secret-tool clear service myapp username alice

Verification

After setting everything up, confirm the end-to-end flow:

1. Log out and back in. You should not see a second unlock prompt if PAM is configured correctly.
2. Run secret-tool lookup service myapp username alice (using a test entry you stored) — it should return the value without prompting.
3. Run echo $SSH_AUTH_SOCK and verify it points to a socket, then ssh-add -l to list loaded keys.
4. Open Seahorse or KWallet Manager and confirm the keyring/wallet shows as Unlocked.

Troubleshooting

• Unlock prompt on every login (GNOME): The keyring password differs from your login password. Change it in Seahorse or delete ~/.local/share/keyrings/login.keyring and re-login.
• Chromium/VSCode says "Failed to unlock the secret storage": The daemon is not running. Start it manually with gnome-keyring-daemon --start and check that DBUS_SESSION_BUS_ADDRESS is set in your environment.
• SSH_AUTH_SOCK empty in a non-GNOME session: Add eval $(gnome-keyring-daemon --start --components=ssh,secrets) to your session startup script, or use a systemd user socket for ssh-agent instead.
• KWallet prompts on Wayland: Ensure kwallet-pam is installed and SDDM is used. Some third-party DMs do not call the PAM session stack correctly; switching to SDDM resolves it.
• Two agents fighting over SSH_AUTH_SOCK: Disable one as described in the SSH section above. Running both causes unpredictable behaviour.