KeePassDX Complete Guide: Android, Windows, Linux, Passkeys & TOTP

Managing dozens of online accounts securely is one of the most critical aspects of modern digital hygiene. Relying on identical or weak passwords across multiple platforms is a major security risk, while memorizing unique, complex strings for every service is practically impossible.

For years, users turned to commercial cloud-based password managers. However, frequent security breaches at major providers, mandatory subscription paywalls, and telemetry tracking have led privacy-conscious users to adopt decentralized, open-source alternatives.

Enter the KeePass ecosystem. Unlike cloud managers, KeePass relies on a local, highly encrypted .kdbx file database that you own and control completely. On Android, KeePassDX serves as the premier open-source client, pairing with KeePassXC on Windows and Linux.

In this comprehensive masterclass guide, we will explore how to configure and run KeePassDX, set up cross-platform desktop databases, implement browser extension handshakes, configure WebAuthn passkeys, manage RFC 6238 TOTP codes, and sync database files using Syncthing and Nextcloud.

1. Deconstructing the KeePass Database Architecture

To understand why KeePass is secure, you must understand the file format that powers it. The .kdbx file is a self-contained, encrypted database containing all your credentials.

KeePass Database Layer:
[ Credentials / Notes / TOTP Secrets / Attachments ]
                         │
                         ▼
        [ Encrypted XML / Binary Stream ]
                         │
                         ▼ (Argon2id KDF Key Derivation)
         [ Master Password + Optional Keyfile ]
                         │
                         ▼
        [ ChaCha20 / AES-256 Cipher Block ]
                         │
                         ▼
             [ Secure .kdbx File ]

Cryptographic Algorithms

The KeePass database format uses modern industry-standard cryptography to protect your data against brute-force attacks:

1. AES-256 vs. ChaCha20 Ciphers:
   • AES-256 (Advanced Encryption Standard): Operates as a symmetric block cipher, encrypting database blocks of 128 bits using a 256-bit key. It typically runs in Cipher Block Chaining (CBC) mode with PKCS#7 padding. This is the industry standard and benefits from hardware acceleration (AES-NI instructions) on desktop CPUs.
   • ChaCha20 Stream Cipher: Developed by Daniel J. Bernstein, ChaCha20 is a high-speed stream cipher that does not require hardware acceleration to prevent timing side-channel attacks. This makes it highly efficient and secure on budget Android devices or older ARM processors that lack native cryptographic instructions.
2. Argon2id Key Derivation Function (KDF): The KDF is the mathematical algorithm that transforms your master password into the actual decryption key.
   • Why Argon2id? Traditional KDFs like PBKDF2 can be cracked quickly by building GPU or ASIC arrays that run billions of hashes per second in parallel. Argon2id incorporates memory difficulty (requiring a configurable block of RAM to compute each hash), time difficulty (iterations), and parallelism (threads). This means attackers must dedicate real physical hardware memory to each guess, making massive GPU cracking arrays too expensive to run.
3. HMAC-SHA256 Encrypt-then-MAC Authentication: Under the .kdbx version 4 format, KeePass uses an Encrypt-then-MAC scheme. It calculates a Hash-Based Message Authentication Code (HMAC) of the encrypted file. When loading the file, the client checks the HMAC signature before attempting decryption. If an attacker has modified even a single bit of the file in transit, the signature check fails, protecting the client against padding oracle attacks.

Multifactor Database Authentication

Instead of relying solely on a password, KeePass allows you to combine authentication inputs to verify your identity:

• Master Password: A long, high-entropy passphrase known only to you. We recommend using a passphrase composed of 5 to 6 random words, which provides high entropy while remaining easy to remember.
• Key File (.key): A unique file containing 256 bits of cryptographically secure random bytes. To decrypt the database, you must supply both the password and this file.
  • Security Practice: Keep your key file stored locally on a separate physical device, such as a USB flash drive. Never upload the key file to the same cloud directory as your .kdbx file; doing so defeats its purpose if your cloud account is compromised.
• Hardware Security Key (YubiKey): KeePassXC on the desktop supports HMAC-SHA1 challenge-response authentication using physical hardware security keys. When you plug in the YubiKey and tap its button, it signs a challenge issued by KeePassXC, providing physical hardware-based multifactor authentication.

2. Setting Up KeePassDX on Android

KeePassDX is a native, lightweight, and modern password manager for Android that implements the Android Autofill framework.

Installation

You can install KeePassDX via two secure methods:

• F-Droid: The open-source repository for clean, telemetry-free Android applications.
• Google Play Store: The standard application channel.

Initial Database Creation

If you do not have an existing database:

1. Launch KeePassDX, tap Create a new database, and set a location on your local device.
2. Set your encryption settings. We recommend selecting Argon2id as the KDF.
3. Configure your parameters: Set memory to at least 64 MB, iterations to 10, and parallelism to 4 (adjust these based on your mobile device’s CPU speed; if the database takes more than 1–2 seconds to open, lower the memory configuration slightly).
4. Set a strong Master Password.

Database Unlock Settings:
[ Master Password ] + [ Android KeyStore Biometrics ] ──► [ Decrypts KDBX File ]

Biometric Quick Unlock Integration

Typing a long Master Password every time you unlock your phone is tedious. KeePassDX integrates with the Android BiometricPrompt API:

1. Open your database and go to Settings > Security.
2. Enable Biometric Unlock.
3. KeePassDX will encrypt your Master Password credentials and store them within the Android hardware-backed KeyStore (TEE / StrongBox HSM).
4. You can now unlock your database using your fingerprint or face recognition, while the master password remains securely cached in the system’s secure processor.

3. Mastering Android Autofill & Keyboards

Many users find copy-pasting usernames and passwords between applications inconvenient. KeePassDX provides two secure ways to input credentials automatically:

1. The Android Autofill Framework (8.0+)

This is the most seamless method, allowing Android to suggest credentials inside apps and browsers:

1. Go to Android System Settings > Languages & Input > Autofill service.
2. Select KeePassDX.
3. Inside KeePassDX, go to Settings > Form Filling and enable Autofill service.
4. When you tap on a login field in Chrome, Firefox, or an app, a pop-up window will prompt you to unlock KeePassDX and select the matching login entry.

2. The KeePassDX Secure Keyboard

Some applications block the system Autofill framework for security or due to poor design. To bypass this, KeePassDX includes a custom virtual keyboard:

1. Go to Android Settings > Languages & Input > On-screen keyboard > Manage keyboards.
2. Enable the KeePassDX Keyboard.
3. When logging in, switch your active keyboard to KeePassDX.
4. The keyboard will display buttons to insert the username, password, or TOTP code of the active entry with a single tap, preventing clipboard snooping.

Input Methods compared:
Autofill Service:  [ System Prompt ] ──► [ Target App Field ] (Fastest, OS Managed)
Secure Keyboard:   [ Keyboard Selection ] ──► [ Tap Username/Password ] (Bypasses app blocks)

4. Setting Up KeePassXC on Windows and Linux

To access your passwords on your desktop computer, use KeePassXC, a community-driven fork of KeePassX built using modern C++ libraries.

Installation

• Windows: Download the MSI installer or portable zip file from the official KeePassXC site.
• Linux (Ubuntu/Mint):

  sudo apt install keepassxc -y

• Linux (Fedora):

  sudo dnf install keepassxc -y

• Linux (Arch):

  sudo pacman -S keepassxc

Desktop Browser Integration

Instead of manual copy-pasting, KeePassXC can securely communicate with your browser using the KeePassXC-Browser extension (available for Firefox, Chrome, Brave, and Edge).

Browser Integration Handshake:
[ Web Browser Extension ] ◄── (Symmetric Encryption via NaCl) ──► [ KeePassXC Desktop Client ]
                                                                       │
                                                                       ▼
                                                             [ Decrypted Database ]

Under the Hood: The Browser Handshake Protocol

To prevent malware from accessing your database, the browser extension and KeePassXC communicate using a secure local loopback socket.

1. When you install the browser extension, it requests connection authorization from the desktop KeePassXC application.
2. They generate a public/private key pair and complete a handshake using the NaCl (libsodium) cryptographic library.
3. All messages sent between the browser and KeePassXC are symmetrically encrypted using unique session keys.
4. When you load a webpage, the extension queries KeePassXC for matching credentials. KeePassXC prompts you for permission to share the login information before filling the form.

5. WebAuthn Passkeys and TOTP Integration

Modern security goes beyond standard usernames and passwords. The KeePass ecosystem handles both Passkeys and Time-Based One-Time Passwords (TOTP) natively.

What is a Passkey?

Passkeys are built on the FIDO2/WebAuthn standard, replacing traditional passwords with public-key cryptography. During registration, your device generates a unique cryptographic key pair:

• The Public Key is uploaded to the service provider’s server.
• The Private Key remains inside your encrypted KeePass database. To log in, the server sends a challenge, which your private key signs. The server verifies this signature using the public key, logging you in without transmitting any sensitive password data.

Passkey Support in KeePassXC and KeePassDX

• KeePassXC (Desktop): The browser extension acts as a virtual hardware token. When a website requests a passkey creation or login, the extension routes the request to KeePassXC, which stores the key pair directly inside the database entry.
• KeePassDX (Android): Integrates with Android’s modern Credential Manager API. When an app prompts you to register or log in with a Passkey, KeePassDX can authenticate the request using your biometrics and execute the public key signature.

Native TOTP Code Generation

Instead of using secondary authenticator apps (like Google Authenticator or Authy), you can store your two-factor authentication (2FA) seeds directly inside KeePass:

1. When setting up 2FA on a website, copy the base32 secret code or scan the QR code.
2. Inside KeePassDX or KeePassXC, open the entry, select Set up TOTP, and paste the secret seed.
3. The client will generate the 6-digit code dynamically using the RFC 6238 time-based algorithm.
4. Strategic Advantage: Because your database is encrypted and stored locally, backing it up automatically backs up all your 2FA accounts, protecting you if you lose your phone.

6. Cross-Device Database Sync Architectures

Because KeePass does not run on central cloud servers, you must manage syncing your .kdbx file across your devices. Two secure methods stand out:

1. Peer-to-Peer Syncing (Syncthing)

Syncthing operates as a decentralized, peer-to-peer file synchronization system. It does not upload your files to any server; instead, it synchronizes files directly between your devices using block-level exchange.

Syncthing Connection Architecture:
[ Phone (KeePassDX) ] <─── TLS Session (Local Wi-Fi Discovery: 21027/UDP) ───> [ PC (KeePassXC) ]
         │                                                                             │
         └───────────── Relay Server (Encrypted TCP) ◄─── (NAT Traversal) ─────────────┘

Step-by-Step Setup:

1. Install Syncthing: Install Syncthing on your desktop computer and the official Syncthing client from F-Droid or Google Play on your Android device.
2. Pair Devices:
   • On your Android app, tap the Devices tab and select the + icon to add a device.
   • On your desktop interface, click Actions > Show ID to display your device’s QR code.
   • Scan the QR code with your phone. The devices will exchange cryptographic TLS certificates to establish a trusted connection.
3. Configure Local Discovery & Ports: Syncthing listens on port 22000/TCP for sync connections and broadcasts UDP packets on port 21027 to discover devices on your local network. Ensure your router allows multicast traffic.
4. Handle NAT Traversal & Relays: If your devices are on different networks, Syncthing uses global discovery servers and UPnP to establish direct connections. If direct connection fails, it routes traffic through encrypted relay servers, ensuring your database syncs even when you are away from home.
5. Share the Folder:
   • Create a dedicated directory on your PC (e.g., ~/KeePass/) and move your .kdbx file into it.
   • Add this folder in Syncthing, then select your Android device from the sharing list.
   • Accept the shared folder on your phone and choose a local directory.
6. Resolve Save Conflicts: If you make changes on your phone and PC at the same time, Syncthing will save one of the versions as a conflict file (e.g., database.sync-conflict-2026.kdbx). To resolve this, open KeePassXC on your PC, select Tools > Merge Database, and choose the conflict file. KeePassXC will merge the entries from both files.

2. Private Cloud Syncing (Nextcloud / WebDAV)

If you prefer a centralized storage configuration, you can host your .kdbx file on your private Nextcloud server and access it using WebDAV.

Step-by-Step Setup:

1. Retrieve WebDAV URL: Log into your Nextcloud web portal. Click the Files settings cog in the bottom-left corner and copy the WebDAV address: https://nextcloud.yourdomain.com/remote.php/dav/files/your_username/
2. Generate an App Password: For security, never store your master Nextcloud password in external apps. Go to Nextcloud Personal Settings > Security > Devices & clients, type “KeePassDX”, and click Create new app password. Copy the generated 16-character key.
3. Configure KeePassDX:
   • Open KeePassDX on your Android device.
   • Select Open Database and choose the WebDAV protocol option.
   • Paste the WebDAV URL, append the path to your database file (e.g., /remote.php/dav/files/your_username/Passwords/vault.kdbx), and enter your username and the app password.
4. Under the Hood (Caching & Merging): When you open a database via WebDAV, KeePassDX downloads a local copy to a secure sandbox directory. When you make changes, the app writes them locally first, then uploads the updated file to Nextcloud using an HTTP PUT request. If the server’s file is newer, KeePassDX will prompt you to merge the databases to prevent overwriting updates.

7. Troubleshooting and Diagnostic Recovery

Use this diagnostic matrix to resolve common issues in the KeePass ecosystem:

8. Password Manager Alternatives

The table below compares the KeePass ecosystem with other popular password managers:

9. Conclusion

The combination of KeePassDX on Android and KeePassXC on desktop provides a secure, private, and subscription-free password management solution. By storing your credentials in an encrypted local database and syncing it via Syncthing or Nextcloud, you maintain complete ownership of your digital security profile.

Ready to secure the rest of your self-hosted infrastructure? Read our step-by-step masterclass guides on deploying a secure Vaultwarden Password Manager Server or configuring a Nextcloud Storage System today!