Add Pin Quick Unlock and Remember Quick Unlock for Win/Mac

[droidmonkey]

Closes #7020

Added ability to remember quick unlock across KeePassXC sessions and database open/close. This relies on the public UUID feature introduced earlier in the develop branch to store the encrypted database credentials into the Windows Credential Store or the macOS Key Store. Remembering quick unlock is not supported on Linux due to the lack of a unified/standardized key store across distros.

Also introduce pin unlock as a fallback option when OS Native security tools are not available for use. The pin is set on first unlock and must be between 4 and 8 digits. The pin hash is used in conjunction with a random IV to encrypt database credentials in memory.

Shifted security setting to be an enable/disable quick unlock by default setting. Now that quick unlock is always available (via Pin fallback) it makes more sense to allow the user to choose what to do at time of unlock. The remember quick unlock setting is hidden on Linux since it is not functional.

Screenshots

Testing strategy

Tested on Windows, will be testing on other platforms to ensure no regression

Type of change

• ✅ New feature (change that adds functionality)
• ✅ Refactor (significant modification to existing code)

[michaelk83]

Remembering quick unlock is not supported on Linux due to the lack of a unified/standardized key store across distros.

There is the kernel keyring, which I think the existing Linux Quick Unlock code is already using. Not sure if it can store things across sessions, though.
https://man7.org/linux/man-pages/man2/add_key.2.html
https://man7.org/linux/man-pages/man7/persistent-keyring.7.html

[codecov]

Codecov Report

Attention: Patch coverage is 28.94737% with 108 lines in your changes missing coverage. Please review.

Project coverage is 64.16%. Comparing base (7ec0f1f) to head (0cae805).
Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
src/quickunlock/PinUnlock.cpp	7.14%	78 Missing ⚠️
src/gui/DatabaseOpenWidget.cpp	63.89%	13 Missing ⚠️
src/quickunlock/Polkit.cpp	0.00%	11 Missing ⚠️
src/quickunlock/QuickUnlockInterface.cpp	66.67%	4 Missing ⚠️
src/gui/ApplicationSettingsWidget.cpp	66.67%	2 Missing ⚠️

❌ Your patch check has failed because the patch coverage (28.95%) is below the target coverage (50.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop   #11520      +/-   ##
===========================================
- Coverage    64.26%   64.16%   -0.10%     
===========================================
  Files          376      378       +2     
  Lines        39309    39395      +86     
===========================================
+ Hits         25259    25275      +16     
- Misses       14050    14120      +70     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[phoerious]

I think the unlock screen layout got screwed up. There's way too much padding above "I have a key file". I also don't like the checkbox placement next to the Unlock button (why do we need that anyway, what's wrong with the way it was before?)

[droidmonkey]

I did tweak the layout of the unlock dialog, extra padding was on purpose, I felt it was too tight before. We can debate it.

The checkbox is necessary now so you can decide when to use Quick Unlock before unlocking. This matters on Linux and Mac where the user isn't prompted prior to setting up quick unlock (and also potentially remembering it). On Windows or when using PIN this doesn't matter because you can always cancel the Windows Hello or PIN dialog.

I am also open to changing the "Unlock" button to include an alternative drop down option of "Unlock Once" or "No Quick Unlock" or similar.

[phoerious]

The previous layout was deliberate. With the extra padding you're messing with the proximity and common region principles. The visual cohesion of related elements gets lost entirely and the element grouping looks loose and confusing. I'm strongly in favour of reverting the change.

I don't see why we need a checkbox here. If users don't want quick unlock, they can disable it in the settings. If they don't want quick unlock just now (probably a niche use case), a hybrid button dropdown could be an option. On the other hand, you could also just lock the database and then one-click cancel quick unlock (that said: why not add that as an option to the lock button instead of the unlock button?).

[droidmonkey]

I changed the application setting from "Enable Quick Unlock" to "Use Quick Unlock by default". Enabling the new setting checks the box when you open a database, otherwise the box is unchecked. Disabling quick unlock at the application level doesn't really make sense anymore. Are you disabling the OS version of quick unlock, fallback? What if you want to use it from some databases but not others? Most users want to use quick unlock and want it to be remembered (based on issue reports and feature requests).

Perhaps a compromise would be moving this checkbox to the database settings page and store the desire in database custom data that can be queried right after the database is unlocked before quick unlock is established? Then we can also potentially use a selection box: "Enable Quick Unlock (default)", "Use PIN unlock", "Disable Quick Unlock"

Some people hate OS integration so explicitly allowing PIN unlock could be a neat feature for them.

[phoerious]

I believe in critical environments you definitely don't want to have quick unlock. So there should be an easily-accessible feature to turn it off. It may make sense to have that on database level, but I would assume that more often than not the desire to turn it off depends more on the environment than on the database (e.g. have it on at home, but not on the laptop).

[droidmonkey]

Quick mockup

[phoerious]

Not a fan of that. "Use PIN unlock" doesn't make any sense to me. You're not unlocking with a PIN here. Only the next unlock will use a PIN. "Disable quick unlock" sounds like a permenant setting, but isn't. I'd rather add an option to the "lock" button to cancel quick unlock immediately. Arguably, that would still store the key temporarily in the system key chain, but that's probably not the biggest deal.

[droidmonkey]

I dunno if I actually did change the padding, here is a comparison of develop against this branch (develop on left):

[phoerious]

Then it got messed up somewhere else, need to bisect that. I don't have a develop build handy right now, but this is what it's supposed to look like. The contrast needs improving (that is actually pretty terrible), the padding doesn't. You could add a few pixels if you really feel the urge to, but your screenshot has way too much of a gap. Should be the same distance to the password field as the label above.

[droidmonkey]

It was me, another commit though: ba0fc3b #11321

[phoerious]

Yes, I just checked a snapshot build. The padding was indeed increased there.

[jasperweiss]

Correct me if I'm wrong but encrypting the memory with a pin hash seems like security theater. Even with 8 digits and a slow hash function this can be brute forced so quickly it's hardly an obstacle for an attacker who is able to read the memory contents.

Hardware backed credential storage with Windows Hello or TouchID provide meaningful protection for the key material so they're a proper substitute for constantly filling in the passphrase, whereas the pin based feature is really just a UI level protection which can already be achieved by locking your device when leaving it unattended.

I would at the very least make it a completely separate option from the hardware backed options and make it very clear to the user that it's purely a UI level protection. But without hardware backed storage options, I don't see the point to be honest. The pin pretends to be a middle ground between having to type in the passphrase and having it unlocked while in reality it doesn't provide meaningful protection and leaving it unlocked is much more convenient.

[droidmonkey]

Even with 8 digits and a slow hash function this can be brute forced so quickly it's hardly an obstacle for an attacker who is able to read the memory contents.

@jasperweiss A few thoughts on this:

1. Pin unlock is a fallback in case hardware backed options don't exist
2. Quick unlock is an optional feature
3. Reading the memory contents, and finding the right thing in memory, is non-trivial. This is especially true on platforms that we protect memory from all but root access

So where pin quick unlock is not bullet proof, it is still considerably more secure than copy/pasting your master password around because you don't want to type it out. Yes, we have received requests with people admitting to doing that.

it's purely a UI level protection

This is completely false

[kbarnawi]

any update on progress? or any plan for implementation time Fream?
I was using an app from the wwindowsstore "pt.keepass" but sadly nowhere to be found? so there is no modern replacement currently so annoying as so many option on android and non on windows 😒
I will be happy to use a beta version 😁

[Copilot]

Pull Request Overview

This PR introduces a significant refactoring of the Quick Unlock feature in KeePassXC, modernizing its architecture and adding PIN-based unlock as a fallback mechanism. The changes transition from platform-specific implementations to a unified manager pattern with OS-specific secret storage.

• Refactored Quick Unlock to use a manager pattern (QuickUnlockManager) that dynamically selects between native (TouchID/WindowsHello/Polkit) and fallback (PIN) unlock methods
• Added PIN-based unlock as a cross-platform fallback mechanism with Argon2 key derivation
• Migrated secret storage to OS-specific credential stores (macOS Keychain, Windows PasswordVault, Linux keyring)

Reviewed Changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/quickunlock/QuickUnlockInterface.h/cpp	Introduces QuickUnlockManager singleton and moves error handling to base class
src/quickunlock/PinUnlock.h/cpp	New PIN-based unlock implementation with secure key derivation
src/quickunlock/TouchID.h/cpp/mm	Simplified macOS TouchID implementation delegating to OS secret storage
src/quickunlock/WindowsHello.h/cpp	Simplified Windows Hello implementation delegating to OS secret storage
src/quickunlock/Polkit.h/cpp	Enhanced Linux Polkit implementation with PIN integration and persistent keyring storage
src/gui/osutils/Utils.	Added unified secret storage APIs to OS utility classes
src/gui/DatabaseOpenWidget.*	Updated UI with Quick Unlock checkbox and improved button layout
src/gui/ApplicationSettingsWidget*	Added "Remember quick unlock" setting for TouchID/Windows Hello
src/core/Config.h/cpp	Added Security_QuickUnlockRemember configuration key
src/crypto/kdf/Argon2Kdf.cpp	Added buffer overlap validation

[Copilot]

The pointer comparison *raw != *result dereferences the pointers to compare the first byte values, not the buffer addresses. This should be raw.data() != result.data() to properly check if the buffers overlap.

Suggested change

	Q_ASSERT(*raw != *result);
	if (*raw == *result) {
	Q_ASSERT(raw.data() != result.data());
	if (raw.data() == result.data()) {