Skip to content

Device Unlocking

Jump to bottom Edit New page
Jérémy JAMET edited this page Nov 17, 2024 · 3 revisions

Device unlocking features allow unlocking your database in a number of ways, by connecting your password to the biometric system or by using your device credential.

Depending on the devices, it is possible to unlock with:

  • Device credential :
    • PIN
    • Password
    • Schema
  • Biometric :
    • Fingerprint
    • Face unlock
    • Other secure biometric locking systems compatible with your device

Warning: Device unlocking does not exempt you from remembering the master password of your database. This is only a convenient way to open your database.

How to set up device unlocking?

Device unlocking requires that you have a secure device, which implies that you have already set the lock of your device with a PIN, Password or Scheme (an internal secure keystore must also be configurable).

Without having secured your device with a device credential, it is not possible to use device unlocking.

For more information on device credential registration procedures, refer to your device manufacturer's manual.

Biometric unlocking

Biometric unlocking requires that you have a secure device, in order to activate dual identification directly with the device's tools.

Indeed, this allows you to use biometric unlocking only if your device has previously been unlocked by a credential only known by the device user (the principle of knowledge, possession and inheritance factors is therefore respected.)

With the biometric unlocking mode, user authentication is requested from the KeyStore and is therefore less permissive than the device credential unlocking.

This is the recommended unlocking method.

Remember to lock your device when you are done using it and set a device timeout adapted to your use.

Device credential unlocking

Device credential unlocking is based on the device credential previously configured and makes it easier and faster to unlock your KeePass database. This is especially useful if you have entered a strong password to your database which is long and tedious to enter at each opening.

This method is however less secure than the fingerprint because it only uses the credentials of the device (something you know copyable with a prying eye) and does not require user authentication in the KeyStore with certificate for older versions (7 and lower) of Android (https://github.com/Kunzisoft/KeePassDX/issues/1417#issuecomment-1277801072). It is recommended to use this method if you use a second factor to open your database (keyfile with OTG or unregistered location, hardware key, ...) to multiply the required keys and add extra security in case an attacker has access to your device unlocking method.

Note: Your device may also offer biometric unlocking if only device unlocking mode is enabled; your system simply offers this option in addition, but other systems do not. It is recommended to only use biometric unlock in this case, which requires user authentication from the KeyStore.

A. Configure biometrics in the device

If your fingerprint is already enrolled in your device, go directly to step B.

This procedure is based on version 10 of Android to register a fingerprint. If you want to register a facial print or if you have another version of Android, the procedure may be different, please refer to the manual of your device.

  1. Configure a fingerprint or other locking system in your device settings

  1. Choose a screen lock for your device if it is not already set (PIN, Schema, Password, etc...)

Note: KeePassDX will not be able to operate biometric recognition if a screen lock is not defined.

  1. Register your fingerprint

You should see the new fingerprint saved in your device

  1. Return to KeePassDX to link a database to the registered fingerprint

B. Link database credentials to device unlock recognition

  1. Go to the settings Settings → Device unlocking.

  2. Activate the desired type of device unlocking, it is recommended to use "Biometric unlocking" if it is compatible with your device.

  1. A window will tell you that this feature uses the KeyStore of the device. Click "OK" after checking the security conditions of your device and the operating system you use. (Some custom ROMs may not be certified and the Keystore may not work)*

  1. Return to the main credentials screen of your database. A new "Unavailable" button should have appeared on the unlocking screen.

  1. Insert the credentials of the database (password, key file, ...). The button text changes to Device unlock link telling you that it is possible to link these credentials to device unlocking. Note: you can currently only add device unlock to the password.

  1. Open the device unlock prompt by clicking the device unlock link button in the bottom left corner.

  1. Use your device unlock method to store your database lock password securely. The database should open and link the device unlocking if you have filled in the right credentials.

Note: the database must open by itself, if this is not the case, an error has occurred. Check if the credentials are correct and the error messages.

C. Use device unlock recognition to open the database

  1. If the device unlocking prompt does not open automatically, open it by clicking the device "Unlock" button (with fingerpritn icon) when a database is linked to a device unlock method (the credentials check boxes should not be checked). Settings → Device unlock → Auto-open prompt allows to activate the automatic opening of the prompt.

  1. Use your device unlock to unlock your database (e.g. by scanning your fingerprint).

Temporary encrypted key memory

A temporary memory can be used to store the encrypted content related to device unlocking. This allows device unlock content to be deleted after a specific period of time or after restarting the device.

Note: A notification will appear indicating the time remaining before the memory dump and to clear the memory manually. You can hide this notification in the settings of your device.

  • Settings → Device unlocking → Temp device unlocking to use the temporary memory
  • Settings → Device unlocking → device unlocking expiration to define the timeout

It is possible to delete the encrypted unlocking content of a database with the "Delete device unlock key" menu ("crossed out key" icon).

Warning : From version 4.1.0 onwards, the temp advanced unlocking timer is reset each time the database is opened.

Why not Quick Unlock?

Unlike Device Unlocking which can only be used if the database is closed and encrypted, the Quick Unlock feature of other KeePass applications and plugins leaves the database decrypted in RAM and reduces access to it by offering authentication with part of the master password.

This feature will not be implemented because some users think that the database is encrypted while the Quick Unlocking is active and never really close their database. Moreover it requires to check what are the last characters of the master password, which is not practical when a long master password is used and changed regularly.

To replace it, you can use the Temporarily Device Unlocking (with Temporary encrypted key memory.) if you don't want to bind your password to Device Unlock permanently.

And if you are still not satisfied with this method and absolutely want to reproduce the Quick Unlock behavior with KeePassDX, you can use an Android launcher that has the ability to authenticate an application with specific credentials and leaving your database open. This will allow quick access to already decrypted database content with overlay authentication. (CAUTION: this method is not recommended for a long period of time and if you are not using your device in a secure environment).

Study of the Quick Unlock feature : https://github.com/Kunzisoft/KeePassDX/issues/102#issuecomment-636650198

Errors

If the errror User changed or deleted their auth credentials or Invalid key blob (internal Keystore code -33) is displayed, try to delete keys in Settings → Device unlocking → Delete encryption keys.

If a keystore error is displayed or an error indicates Key user not authenticated, the keystore on your device may not accessible to store or retrieve a secure key. The problem can happen if:

  • You have just registered or modified a fingerprint and a device restart is required.
  • Your device does not have a security system turned on when it is unlocked after sleeping. (PIN / pattern / etc.)
  • The keystore operation failed. Your custom ROM or firmware may have disable key writing when authentication is needed. Check in your device settings or simply use device credential unlock. (There is a high probability that this is a ROM bug, describe the problem to your ROM developer to understand why the Keystore cannot be used if KeyGenParameterSpec.Builder.setUserAuthenticationRequired() is set to true)
  • The keystore has invalidates or corrupted keys. In this case, it may be necessary to delete the current keys from the app. (Settings → Device unlocking → Delete encryption keys) or delete the keystore file (/data/misc/keystore/user_0/)
  • Your device completely blocks access to its keystore. In this case, there is nothing to do, simply disable device unlock recognition.

If an error indicates Too many operations or the app freezes with device unlock enabled, your device has a non-standard behavior for the keys in its keystore. It is therefore recommended not to use device unlocking. Issue for more information : https://github.com/Kunzisoft/KeePassDX/issues/1269#issuecomment-1075449893

Add a custom footer
Add a custom sidebar
Clone this wiki locally