Skip to content

Split keyring unlock from the unlocked check and stop double prompts - #2627

Merged
m3nu merged 4 commits into
masterfrom
fix/2606-keyring-unlock-split
Nov 15, 2026
Merged

m3nu merged 4 commits into
masterfrom
fix/2606-keyring-unlock-split

Conversation

@m3nu

@m3nu m3nu commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Description

Separates "is the keyring unlocked" from "unlock the keyring", and uses that to stop repeated unlock prompts.

What was wrong

  • On KWallet and SecretStorage, is_unlocked unlocked the keyring as a side effect, and get_password went through it. BorgJob.prepare called get_password and then is_unlocked, so it made two unlock attempts. If the first one failed (for example the D-Bus reply timed out while the user was still typing the wallet password) and the second succeeded, the passphrase was None on an unlocked keyring and the job failed with "Your repo passphrase was stored in a password manager which is no longer available. Try unlinking and re-adding your repo." The next run worked.
  • prepare also prompted for repos without encryption.
  • The add-repo dialogs read the keyring on every change of the URL field, so a locked keyring was asked to unlock on every keystroke.

What changed

  • VortaKeyring.is_unlocked is now a pure check that must not prompt. A new try_unlock() unlocks if needed, may prompt, and returns whether the keyring is unlocked. The DB keyring uses the default (bool(self.is_unlocked)).
    • KWallet: is_unlocked returns True for an open handle, otherwise asks isOpen with the wallet name. It never calls open, never shows the "Create Wallet" dialog and never changes the handle. try_unlock() returns a bool on every path and reuses an open handle. get_password calls try_unlock().
    • SecretStorage: is_unlocked is not collection.is_locked(). try_unlock() calls collection.unlock() when locked and then re-reads is_locked(), because unlock() only reports whether a prompt was dismissed. get_password/set_password/delete_password call try_unlock().
    • macOS: try_unlock() calls SecKeychainUnlock without a password when the login keychain is locked. Before, a locked keychain was prompted for implicitly by the read; prepare now unlocks before it reads, so the prompt has to be explicit.
  • BorgJob.prepare calls try_unlock() once, before reading, and only for repos that need a passphrase. For unencrypted repos it reads the stored passphrase only if the keyring is already unlocked. The DB fallback and the "no longer available" check below it are unchanged.
  • BorgInfoRepoJob.prepare (add existing repo) calls try_unlock() once, whether or not a passphrase was entered, and fails with "Please unlock your password manager." only if a passphrase was entered and the keyring stays locked. The unconditional unlock is needed because process_result stores the passphrase when the repo turns out to be encrypted, and KWallet needs an open handle for that write.
  • The add-repo autofill (RepoWindow.keyring_password) only looks up URLs that look like a repo (.+:.+, as in validate(), or an absolute path) and only when is_unlocked is already True. It never prompts.

Related Issue

Part of #2606

This is the first of two changes for that issue. Deferred to the follow-up:

  • caching the backend instance in get_keyring() instead of building one per call (the per-connection authorization prompts with KeePassXC), including cache reset for tests, stale KWallet handle recovery and a provider that starts after Vorta;
  • moving keyring_lock into the keyring package and covering every backend call with it;
  • moving the system-to-DB fallback out of borg_job.py;
  • a defensive default when the use_system_keyring row is missing;
  • what happens to stored passphrases when use_system_keyring changes (needs a maintainer decision, see the issue).

keyring_lock and get_keyring() are untouched here.

Behaviour changes

"Locked" refers to a system keyring. With the DB keyring, and with an unlocked system keyring, the outcome of prepare is the same as before. A repo whose encryption is NULL still counts as encrypted.

Case Before Now
Encrypted repo, locked, first unlock attempt fails and the second succeeds "…no longer available", or the job proceeds on a DB-fallback passphrase "Please unlock your system password manager…"; DB fallback not consulted
Encrypted repo, locked, user unlocks up to 2 unlock attempts (KWallet: 2 open calls) 1 prompt, same result
Encrypted repo, locked, unlock fails or is dismissed 2 attempts, then "Please unlock…" 1 attempt, then "Please unlock…"
Unencrypted repo (also creating one), locked prompt, stored passphrase read no prompt, no keyring read (DB fallback still consulted, dummy BORG_PASSPHRASE if nothing is found)
Add existing repo, passphrase entered, locked prompt from the read in the base prepare, second attempt in info_repo.py 1 prompt in info_repo.py; same "Please unlock your password manager." if it stays locked
Add existing repo, no passphrase entered, locked prompt from the read in the base prepare; continues either way 1 prompt in info_repo.py; continues either way
macOS, encrypted repo, locked login keychain implicit prompt from the keychain read explicit SecKeychainUnlock
Add-repo dialogs, typing a URL, locked unlock attempt per keystroke no prompt, no lookup

Creating a repo with encryption and changing a passphrase behave as before apart from the single unlock attempt.

Known residual, not addressed here: on KWallet, if another application has the wallet open and Vorta is not yet authorised for it, is_unlocked is True and the read that follows can show kwalletd's per-application authorisation dialog, also from the autofill.

How Has This Been Tested?

All on macOS with Borg 1.4.3; tests/unit/test_keyring_darwin.py::test_keyring_non_ascii_repo deselected locally because it writes to the real login keychain.

  • New tests/unit/test_keyring.py: prepare unlocks once before reading and does not read when the unlock fails; unencrypted repos never unlock and only read from an unlocked keyring; BorgInfoRepoJob.prepare unlocks once with and without a passphrase and only fails for an entered passphrase; with a closed KWallet (mocked D-Bus) and an empty passphrase field, process_result writes with the handle from open, never with -1.
  • tests/unit/test_kwallet.py (mocked D-Bus): the six existing tests are unchanged; new tests for is_unlocked (no open, no dialog, handle unchanged, wallet opened elsewhere, open handle needs no D-Bus call) and for every return path of try_unlock().
  • New tests/unit/test_keyring_secretstorage.py (mocked collection; skipped when secretstorage is not installed): 5 passed with uv run --with secretstorage pytest tests/unit/test_keyring_secretstorage.py.
  • tests/unit/test_keyring_darwin.py: try_unlock() with SecKeychainUnlock and the keychain status mocked.
  • tests/unit/test_repo.py: no keyring read while typing with a locked keyring or for input that is not a repo URL; autofill in the existing-repo dialog. The last one was added because keyring_password had first been put on AddRepoWindow only, which made every URL change in the existing-repo dialog raise AttributeError; no test covered that dialog's autofill before.
  • The new behaviour tests fail against the source on master.
  • uv run nox -- tests/unit --deselect tests/unit/test_keyring_darwin.py::test_keyring_non_ascii_repo: 559 passed, 8 skipped when it completes. It does not always complete, see the next point.
  • Intermittent segfault in the full unit suite on macOS, also present on master. With these tests added, the full run aborts with a segmentation fault in tests/unit/test_scheduler.py::test_create_backup_records_a_running_job in a large share of local runs: 4 of 5 on an otherwise idle machine, against 0 of 4 runs of master interleaved with them. Removing either tests/unit/test_keyring.py or the three new test_repo.py tests from the run made it pass 4 of 4, and that test file alone, or together with the keyring and repo tests, never crashed. The crash is not in code this change touches: a native backtrace shows the main thread delivering a queued call to a bound signal's emit whose owning Python object has been freed and its memory reused (pyqtBoundSignal_emit -> sip_api_py_type_name on a pointer that decodes to JSON text), while a job worker thread is running. Unmodified master crashes in the same test with the same thread states once the cyclic garbage collector's timing is shifted: with gc.set_threshold(660, 10, 10) set from a pytest plugin, 2 of 3 full runs of master segfaulted there (thresholds 690, 710 and 740: 1 run each, no crash). So this looks like an existing use-after-free that depends on when a collection happens, and the extra tests move that moment; it is not fixed here. The only place that passes a signal's emit to a queued call is QTimer.singleShot(0, self.scheduler.jobs_changed.emit) in src/vorta/scheduler/state.py, but which object is freed was not established. Whether Linux CI is affected is unknown.
  • tests/integration/test_init.py (create repo, add existing repo): 2 passed.
  • make lint hooks (ruff, ruff-format) pass on the changed files.

Not tested. The KWallet and SecretStorage backends are covered by mocked tests only; nothing here ran against a real kwalletd, GNOME Keyring or KeePassXC. The macOS SecKeychainUnlock call has never been executed: it is only known to load with the given type encoding, and the test mocks it. If it shows no dialog on a locked login keychain, encrypted repos would get "Please unlock your system password manager…" without any prompt, where the read used to prompt before.

Manual checks required before merge

  • macOS, locked login keychain (security lock-keychain), then start a backup of an encrypted repo: exactly one system unlock dialog, then the backup runs. If no dialog appears, the Darwin try_unlock() needs rework before this is merged. Dismissing the dialog gives "Please unlock your system password manager…".
  • KDE, KWallet locked at start, then a backup of an encrypted repo: exactly one wallet prompt; success after unlocking or "Please unlock…" after cancelling, never "no longer available".
  • KDE, KWallet locked, typing in the URL field of both add-repo dialogs: no prompt.
  • KDE, KWallet locked, add an existing repo: one prompt; the passphrase is in the wallet afterwards and the next backup works.
  • GNOME Keyring and/or KeePassXC as Secret Service, collection locked: the same backup, add-existing-repo and autofill checks.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

  • I have read the CONTRIBUTING guide.
  • My code follows the code style of this project.
  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

I provide my contribution under the terms of the license of this repository and I affirm the Developer Certificate of Origin.

m3nu added 4 commits November 15, 2026 08:55
…mpts

`is_unlocked` used to unlock the keyring as a side effect on KWallet and
SecretStorage, so `BorgJob.prepare` could prompt twice (once via
`get_password`, once via `is_unlocked`). If the first prompt timed out and
the second succeeded, the job failed with the misleading "no longer
available" message. The add-repo dialog also read the keyring on every
keystroke in the URL field, prompting each time while the keyring was
locked.

- `is_unlocked` is now a pure check that never prompts. A new
  `try_unlock()` unlocks if needed (may prompt) and returns whether the
  keyring is unlocked. KWallet queries `isOpen` by wallet name; Darwin
  calls `SecKeychainUnlock` to show the system unlock dialog.
- `BorgJob.prepare` unlocks at most once, before reading. If that fails,
  it reports "Please unlock your system password manager…" without
  consulting the DB fallback. Unencrypted repos no longer prompt; the
  stored password is only read if the keyring is already unlocked.
- `BorgInfoRepoJob.prepare` uses `try_unlock()` when a password is given.
- Add-repo autofill only reads the keyring for URLs that look like a repo
  and only when the keyring is already unlocked.

Backend caching and the related locking changes follow separately.

Part of #2606
keyring_password() was defined on AddRepoWindow, so ExistingRepoWindow.set_password
raised AttributeError on every change of the URL field. Move it to RepoWindow and
cover the existing-repo autofill and BorgInfoRepoJob.prepare with tests.
With the wallet closed and an empty passphrase field, nothing opened KWallet any
more, so process_result() wrote the passphrase of an encrypted repo with an
invalid handle and it was silently lost. Unlock unconditionally in
BorgInfoRepoJob.prepare, as the base prepare did before, but still only fail on a
locked keyring when a passphrase was entered.

Also word the Darwin unlock comment as intent; the dialog is not verified yet.
@m3nu
m3nu merged commit 05296b3 into master Nov 15, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant