KeePass Secure Share

[J-Jamet]

Please note that this is only a proposal and needs to be discussed with the other KeePass client teams to maximize adoption. This document is a draft and will be updated based on information from the discussions.

Context

While KeeShare is used to share large amounts of data by creating subdatabases, there is no easy way to share a small amount of data from the fields of a single entry.
The KeePass Secure Share (KSS) protocol is a proposal that provides a secure method to transport sensitive data from one entry.
Note : QR code generation is one of many ways to transfer data and will not be implemented directly in KeePassDX.

The sharing system will be available in two formats:

• Secure Envelope -> To ensure zero-knowledge transport when using third-party QR generators or system sharing sheets, the payload is encrypted using a defined sharing password/PIN.
• Ephemeral Link -> Provide a content provider that will expose the data in plain text for on-the-fly data retrieval. The exposed data will only be visible while the database is open, in the form of an expiring URI.

The protocol uses a standard URI structure to allow for precise Android Intent filtering and future extensibility.

A. Secure Envelope

The data is serialized into a JSON object, encrypted, and encoded into a URI fragment. Because the payload itself is encrypted, the URI does not require aggressive, immediate expiration.

This method will be used to share data or transfer it to other external applications that are not necessarily on the same device (QR Codes, sharing via messengers, and offline inter-device transport).

keepass://share/v1#<Base64_Payload>

• keepass: The generic scheme. Not specific to KeePassDX.
• //share (Authority): Explicitly defines the action. This ensures the URI is routed to the "Import/Retrieval" logic rather than being treated as a database path.
• # (Fragment): The encrypted payload is placed in the fragment to prevent it from being sent to servers if the URI is accidentally processed as a web link (standard security practice). Contains the protocol version (defines the JSON schema and the cryptographic suite used (AES-GCM)).

To keep the payload compact and consistent with the KeePass ecosystem, KSS uses the standardized characters from the KeePass Field References specification. https://keepass.info/help/base/fieldrefs.html

Example

val intent = Intent(Intent.ACTION_SEND).apply {
            type = "text/plain"
            putExtra(Intent.EXTRA_TEXT, uri.toString())
            addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
}

Fragment Cryptography

• KSS v1 uses a security envelope to protect the JSON payload.
  • Encryption: AES-256-GCM
  • Key Derivation: Argon2id
  • An autogenerated 8-character alphanumeric string one-time password "The code and the share link must be sent through different channels."
  • Payload Serialization: Base64(Version + Salt (16 bytes) + IV (12 bytes) + Ciphertext + Auth Tag (16 bytes))

Extensibility for V2

Potential for ECIES (Asymmetric) sharing where the Trusted App provides a Public Key to KeePassDX for automated encryption without a shared password.

Workflow

Device A

• Entry with a share button that allows the user to select which fields of the entry to export
• Share is behind User Verification (optional if the mode is disabled during the session)
• One-time password is generated automatically
• App generates the JSON, encrypts it, and constructs the keepassdx://share/v1#... string to be share by intent
• String is sent via Intent.ACTION_SEND to a third-party app (e.g., a QR code generator)

Device B

• Use a third-party app (QR-Code reader) to retrieve the intent string
• The intent filter in KeePassDX allows you to capture the string in the specified format
• The one-time password is required
• Save mode (registration) allows to save the decrypted content to the desired location

POC

#2593

B. Ephemeral Link

In order to sharing data with Trusted Applications on the same device (e.g., a dedicated Browser, OTP app, or QR generator).

KeePassDX acts as a ContentProvider and exposes standard content:// streams directly to target third-party applications. Instead of sending the actual data, it sends a temporary URI. The recipient app must call back to KeePassDX to retrieve the data.

This method will be used to seamlessly share data with other apps directly related to password management on the same device.

Format

The content provider will be used in two formats:

• Unique field : Share a single entry field using the entry's UUID and the name of the field. This allows a single action to be performed using a password, useful with an HID key to automatically type characters on a PC.
• Entry : Share a complete entry using his UUID. Allows to capture an entire entry for use by tools that manage a service session. Within KeePassDX, the entry will be captured by Magikeyboard so that each field of the entry is assigned to a button.
• Sub-Group : Share an entire group with another app capable of reading a KeePass node tree. This could serve as the basis for the KeeShare system, which would create a sub-database/sub-group to be shared. The advantage of using the content provider is that it allows direct access to the data without having to decrypt it again. The KeeShare system could then serve as an overlay for this KSS sub-group sharing and add the desired encryption to create a unique URI using a dedicated file provider.

Trusted App

Verification of the Android App Signature (SHA-256) of the requesting app. Access is only granted to "Trusted Apps" previously allow-listed by the user.

Invalidation

The URI is ephemeral. The provider is configured to invalidate the URI immediately after the first successful read or automatically expires if the database is closed.

Content Provider URI

Unique field

content://com.keepass.provider/[Entry_Id]/[Field_Name]

Entry

content://com.keepass.provider/[Entry_Id]

Sub-Group
Available only with v4 databases

content://com.keepass.provider/[Group_Id]

Example
The protocol is used to retrieve the password from a receiver app.

AndroidManifest.xml

<uses-permission android:name="com.kunzisoft.keepass.PERMISSION_READ_FIELD" />

<activity>
  <intent-filter>
    <action android:name="keepass.intent.action.READ_FIELD" />
    <category android:name="android.intent.category.DEFAULT" />
    <data android:mimeType="text/plain" />
    <data android:host="com.keepass.provider" />
  </intent-filter>
</activity>

Unique field
URI Retrieved : content://com.keepass.provider/6E43354164E7DAE41B62FB84E82A7B84/password

val uri: Uri? = intent.getParcelableExtra(Intent.EXTRA_STREAM)
val fieldName = uri.lastPathSegment
            context.contentResolver.query(uri, null, null, null, null)?.use { cursor ->
                if (cursor.moveToFirst()) {
                    val columnIndex = cursor.getColumnIndex(fieldName)
                    if (columnIndex != -1) {
                        value = cursor.getString(columnIndex)
                        // Use the sensitive data (e.g., fill a field, then clear from memory)
                    }
                }
            }

Sub-Group

URI Retrieved : content://com.keepass.provider/9D19BDA171B8C642B82F1FFF447577C4
// TODO

POC

#2584
https://gitlab.com/kunzisoft/android-hardware-key-driver/-/merge_requests/17

WiFi Share

TODO
keepassxreboot/keepassxc#10000

References

keepassxreboot/keepassxc#675
#266
#434
#729
#1033
#1432
#1443
#1977
#2186

[catsoo]

How about supporting the Credential Exchange Protocol (CXP) as this is getting more widespread support as a secure cross platform secure exchange protocol between password managers.

[J-Jamet]

https://fidoalliance.org/specs/cx/cxf-v1.0-ps-20250814.html
https://www.corbado.com/blog/credential-exchange-protocol-cxp-credential-exchange-format-cxf

Indeed, the Credential Exchange Protocol will be the final version of key import/export.
I'm not familiar with the protocol, so I'll have to look into it. Technically, it seems to be an improvement on the “A. Secure Envelop” proposal, using a key exchange system to establish a secure channel.

The problem is that setting up the secure channel is for now a cumbersome process. Currently, for Passkey, the Android system handles this and communicate with the app through the androidx.credentials library.
I wouldn't want us to remain dependent on systems that deliberately block credential providers at the OS level, as we saw with Passkey.
So to implement it, we would have to rebuild the entire transfer system to bring it into line with the new CXP protocol.
I would clearly be a good thing, especially if it improves interoperability, but would require too much work if I can't rely on an open-source library.