27

Passkeys

DigitallyRefined edited this page 2025-10-30 10:24:38 +00:00

Table of Contents

• What is Passkeys ?
• Why Passkeys ?
• Set-up
• Settings
• Close Database
• Privileged apps
• Auto Select
• Backup Eligibility
• Backup State
• Create a Passkey entry
• Passkey Entry
• Use a Passkey entry
• Local use
• Cross Device Authentication
• Errors
• No dialog appears
• Privileged Apps
• Signature Missing
• Server rejection
• Passkey created externally
• Bad signature
• Out of time

What is Passkeys ?

Passkeys are a passwordless sign-in method using cryptographic key pairs stored on your devices to log into websites and apps more securely and easily. KeePassDX allows you to create and use Passkeys since version 4.2.0, it allows you to use this authentication system securely completely offline.

Why Passkeys ?

This authentication method should be preferred against password filling because :

• It's more secure, Passkeys are bound to the website or app they were created for. You can't be tricked into using your passkey on a fake site, unlike passwords. The website/app only stores your public key. If their server is breached, attackers don't get your actual credential (the private key, which stays on your database). With passwords, a breached database often means stolen password hashes. Each passkey is cryptographically strong and unique per site, eliminating problems of weak or reused passwords.
• It offers a better user experience, logging in is typically as easy as opening your KeePass database and there is no problem with form recognition.

Set-up

The service that manages passkeys is only available on Android version 14 (API 34) and above, so make sure you have a device with a compatible ROM.

1. Activate KeePassDX Credential Provider / Autofill:

• Click on Settings → Form filling → Credential provider service

2. Select KeePassDX in the Passwords, Preferred service for passwords, passkeys & autofill menu on your device.

Once selected, the Credential provider service toggle is now on, it switches back to off if another Credential provider / Autofill service in the system is selected.

3. A dialog box may ask you if you are sure to trust the app:

KeePassDX is open source, so you just need to check the points that matter to you in the source code and validate if you agree.

4. Since you will be using Passkeys to log in to websites, you must choose a compatible web browser that you trust and configure it to use an external Passkey service. You will usually configure this behavior in your browser settings Browser : Settings → Autofill → Use other services.

5. For users using the Libre build of KeePassDX, you will need to select the browser from the list of privileged apps in Settings → Form filling → Passkeys settings → Privileged apps

Settings

Close Database

Allows the database to be closed automatically when a Passkey entry is selected manually or automatically for use.

Does not close the database when a Passkey entry is created.

Privileged apps

A list automatically created dynamically that allows you to select trusted browsers to use as the relying party Passkey link mapper.

A privileged application is an application that links an Android application to a website via its relying party. For example, Chrome or Firefox are privileged applications that validate each Passkey URL https://[relyingParty].

The privileged application also automatically links between an Android application package and its website by checking the file https://[relyingParty]/.well-known/assetlinks.json.

If an Android application is used to connect with a Passkey, KeePassDX needs to know its package name and signature for security reasons, which must be present in the corresponding entry. An entry created with KeePassDX will have its own parameters in custom fields (ie : AndroidApp and AndroidApp Signature), but this may not be the case if you created your Passkey with another KeePass client (see Error Signature Missing section).

An Android app used on its own, which does not have a website, does not need a privileged application, but these are rare cases for common services.

Note : A privileged application is added to the list when an application installed on the system is capable of handling an https URL link.

Auto Select

You can enable this option to fill in an entry more quickly only if the Passkey server allows it (for example, this option works with https://webauthn.io/ but not with https://www.passkeys.io/)

This allows you to skip the step of selecting the KeePassDX Credential Provider or validating the passkey if it is unique in the database.

Backup Eligibility

The Backup Eligibility (BE) parameter allows to tell the passkey protocol that the public key credential source is allowed to be backed up. This variable is used by default only when creating a Passkey entry and has no effect once the Passkey has been created.

This is an important variable because some servers return an error when you use a passkey created from another Passkey client (see Error server rejection).

Note: The corresponding value per entry should not be manually modified because it must remain consistent with the server value, which cannot be changed.

Backup State

The Backup State (BS) parameter allows to tell the passkey protocol that a passkey entry, created with Backup Eligibility activated, has been backed up externally. In the case of KeePass, this means that you are using a copy of the database on another Passkey client or on a different device.

This value is used by default when creating an entry but only takes effect if Backup Eligibility is enabled.

It is possible to dynamically change its value for a specific entry by changing the custom field “Passkey Backup State” to 0 or 1.

Create a Passkey entry

KeePassDX makes it easy to create Passkey credentials by saving them in an entry in your database. Of course, the service you want to connect to must offer Passkey creation and usage.

1. When the service prompts you to create a Passkey, for example with a dedicated button, a dialog box appears.

2. Click on the main button to start the creation. If an error message appears, refer to the Errors section.

3. KeePassDX launches in Registration Mode (Passkeys), open your database if it is not already open.

4. Click the + button and Add Entry to add a new passkey entry.

5. Verify that the title is correct and press the validate button. Note: It is not recommended to modify the other fields as they contain information that will enable the cryptographic passkey challenges to be performed correctly.

6. Press the confirmed button, your passkey for this service has been created.

Passkey Entry

A Passkey entry is an entry like any other in KeePass, but with customized fields that may differ slightly from other KeePass clients.

The custom fields used follow the KeePassXC nomenclature with names beginning with KPEX_PASSKEY_, but the display is labeled for better visibility by the user.

KeePassDX adds two additional fields if Passkeys are also used to authenticate to applications:

• AndroidApp which is also used by autofill to identify an Android application package
• AndroidApp Signature which contains the signature of the corresponding AndroidApp package name.

Use a Passkey entry

Local use

Local use is the easiest way and allows you to retrieve Passkeys from the service on the device where KeePassDX is installed.

1. Click the Passkey login button for your service.

• If your database is already open and there is only one passkey entry for this service, then the connection is established without any further action.
• If your database is already open and there are multiple passkeys entries for this service, one of the keys will be chosen at random in the main button. However, you can select the one you want by clicking Sign-in options.
• If your database is closed, clicking on the main button will allow you to open it.

2. Click on the main button to start the usage workflow. If an error message appears, refer to the Errors section.

3. KeePassDX launches in Selection Mode (Passkeys), open your database.

4. Select the entry corresponding to your service.

• If there is only one passkey entry in your database, the authentication is made automatically
• If there are multiple passkeys entries in your database, simply select the one you want to use manually.

Cross Device Authentication

You can also use your Passkeys from your phone to log in to a service from another device by bluetooth without going through the internet. This is very convenient for easily connecting to a web service on a PC, for example.

Please note: There are still limitations to this method, which depends on the Credential Provider API of your phone which uses Google Play Services and depends on the remote device. If the two are not compatible, the procedure will fail. Refer to the documentation for your second device for more information.

1. The KeePassDX Free build does not need to perform this operation, it validates the Play services package by default, but if you are using the KeePassDX Libre build, you must set Play services as a privileged app. If you agree to have your Passkeys transferred to this service, then verify the com.google.android.gms signature and set the package as a privileged application. The known signatures :

• 7C:E8:3C:1B:71:F3:D5:72:FE:D0:4C:8D:40:C5:CB:10:FF:75:E6:D8:7D:9D:F6:FB:D5:3F:04:68:C2:90:50:53
• D2:2C:C5:00:29:9F:B2:28:73:A0:1A:01:0D:E1:C8:2F:BE:4D:06:11:19:B9:48:14:DD:30:1D:AB:50:CB:76:78
• F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83
• 19:75:B2:F1:71:77:BC:89:A5:DF:F3:1F:9E:64:A6:CA:E2:81:A5:3D:C1:D1:D5:9B:1D:14:7F:E1:C8:2A:FA:00

2. On your other device (here on a Windows web browser), click the Passkey login button.

3. Choose Android device (the first option).
4. A dialog box will ask you to activate Bluetooth. Activate it if it is not already activated, and a QR code will be displayed.

5. Scan from your Android device containing KeePassDX with your QR code reader app.

6. Connect the devices (establish device trust) in the system dialog on the phone.

7. A link will redirect you to KeePassDX to select the Passkey entry to use. Voilà! The selected entry will allow you to connect to your second device.

8. After the device trust has been established, the phone will appear the next time you try to log in with a passkey. I.e. on https://webauthn.io use the option Authenticate.

Thanks @alensiljak, tested with Windows and Android 16 on a Samsung phone, using the passkeys.io website.

Errors

No dialog appears

If no passkey window appears, check that your Android ROM and web browser is compatible and up to date. Otherwise, try restarting the Credential Provider Service by disabling and re-enabling the toggle.

Privileged Apps

A dialog box displaying the message Origin is not being returned as the calling app did notmatch the privileged allowlist indicates that you are attempting to use an unrecognized browser in privileged applications. Therefore, it cannot provide a correct web origin.

This can happen if, for example, you try to use the Chrome browser, which is not open source, with KeePassDX Libre. If you trust the browser application to delegate Passkeys authentication tasks, then you can add it as a privileged custom application in Setting → Form filling → Passkeys settings → Privileged apps.

Signature Missing

A dialog box displaying the message Signature missing appears if the calling app is not recognized. This dialog box shows the package name and signature of the application attempting to use the key, this usually happens if a key has been registered in another program.

In order to meet minimum security requirements, KeePassDX verifies that a passkey is being requested for use by a recognized application.

• If it is a web browser that has not yet been used for this purpose, cancel the operation and manually select the browser you trust in Settings - Form filling - Passkeys settings - Privileged apps.
• If the package name and signature match an application that you want to trust to access the passkey, simply press OK. The app signature will be added to the Passkey entry (if the database is open for writing) and the passkey will be issued.

Server rejection

In some cases, the server will reject the Passkey you are trying to use for authentication. This can happen if you used another Passkey client to create your keys but the Backup Eligibility variable was disabled, or if you saved the browser package directly to the entry.

Passkey created externally

If the passkey has been saved by another client or on another device with BE disabled, there are two solutions:

• Simply create a new Passkey entry for this service. This is the recommended method.
• Add the unprotected custom field KPEX_PASSKEY_FLAG_BE with a value of 0 to the Passkey entry if the field label Passkey Backup Eligibility is not present. If that doesn't work try adding a KPEX_PASSKEY_FLAG_BS field with a value of 0 if the field label Passkey Backup State is not present. This solution is not recommended, as it manually changes a value on the assumption that the server will accept a backup (i.e., the use of a passkey on another client) simply because the variable has the same value but does not actually verify the client used.

Bad signature

If you have registered your browser signature in the entry:

• Enable the browser in the list of privileged apps
• Remove the AndroidApp and AndroidApp Signature fields in the entry

Out of time

Out of time simply indicates that the time for creating or using the Passkey has expired. You must therefore repeat the procedure by closing and reopening the dialog box.