Documentation
Welcome to the technical documentation of iKeePass. Here you will find all information about usage and supported formats.
Documentation Overview
| Topic | Description |
|---|---|
| 📱 iOS App Features | All features of the iPhone & iPad App |
| 🖥️ macOS App Features | All features of the Mac App |
| AutoType | Automatically type login credentials (macOS) |
| AutoFill | Automatically fill passwords (iOS/iPadOS) |
| AutoFill Guide | Step-by-step: Setup, Testing, Multi-Provider |
| 🌐 Chrome Extension | AutoFill directly in the browser (macOS) |
| Cloud Storage | Store database in the cloud (iOS) |
| 📥 Import from Apple Passwords | Transfer via Credential Exchange — encrypted, no export file |
| 🤖 MCP Server | Drive iKeePass from Claude Code and other MCP clients (macOS) |
Supported Formats
KDBX 3.x - Fully Supported
| Component | Status |
|---|---|
| Encryption | AES-256-CBC |
| KDF | AES-KDF |
| Compression | GZIP |
| Password | Supported |
| Keyfile | Supported |
KDBX 4.x - Supported
| Component | Status |
|---|---|
| Encryption | AES-256-CBC, ChaCha20 |
| KDF | AES-KDF, Argon2d, Argon2id |
| Compression | GZIP |
| HMAC Authentication | Supported |
Security Architecture
Encryption Pipeline
Key Derivation Functions
AES-KDF
- Standard KDF for KDBX 3.x
- Configurable number of rounds
- Typical: 6,000 - 60,000 rounds
Argon2d
- Memory-hard KDF
- Resistant to GPU/ASIC attacks
- Parameters: Memory, Iterations, Parallelism
Argon2id
- Hybrid of Argon2d and Argon2i
- Best balance of security and performance
- Recommended for new databases
Cloud Storage (iOS)
iKeePass iOS uses the native iOS Files dialog to store your database in various cloud services:
| Cloud Service | Status |
|---|---|
| Apple iCloud Drive | Natively integrated |
| Nextcloud | Supported |
| Google Drive | Supported |
| Microsoft OneDrive | Supported |
| Dropbox | Supported |
How It Works
- Install the cloud app (e.g., Nextcloud, Google Drive)
- Enable the service in the iOS “Files” app
- Select the cloud location when saving/opening in iKeePass
Platform Specifics
macOS (iKeePass)
| Component | Technology |
|---|---|
| Language | Swift 6.0 |
| UI Framework | SwiftUI |
| Min. OS | macOS 14.0 (Sonoma) |
| State | @Observable |
| Layout | NavigationSplitView |
iOS (iKeePassIOS)
| Component | Technology |
|---|---|
| Language | Swift 5.9 |
| UI Framework | SwiftUI |
| Min. OS | iOS 17.0 |
| State | @Observable |
| Navigation | TabView + NavigationStack |
| Biometrics | LocalAuthentication |
KeePass Compatibility
iKeePass is fully compatible with:
- KeePass 2.x (Windows)
- KeePassXC (Cross-Platform)
- KeePassium (iOS/macOS)
- KeePass2Android (Android)
- MacPass (macOS)
Tested Databases
| Format | Version | Status |
|---|---|---|
| KDBX | 3.1 | Fully supported |
| KDBX | 4.0 | Fully supported |
| KDBX | 4.1 | Fully supported |
| KDB | 1.x | Planned |
Features in Detail
Security Dashboard
The integrated dashboard analyzes your passwords:
| Analysis | Description |
|---|---|
| Security Score | Overall rating 0-100% |
| Weak Passwords | Short, simple, no special characters |
| Duplicate Passwords | Same passwords used multiple times |
| Old Passwords | Not changed for >90 days |
⏱️ One-Time Passwords (OTP)
iKeePass generates one-time codes itself — no separate authenticator app needed. The code sits right next to the password it belongs to.
What is supported
| Property | Values |
|---|---|
| Schemes | TOTP (time based, RFC 6238) · HOTP (counter based, RFC 4226) |
| Algorithms | SHA1 (default) · SHA256 · SHA512 |
| Digits | 6 (default), 7 or 8 |
| Interval | 30 seconds (default), freely configurable |
| Input | otpauth:// address from the QR code, or the secret by hand |
SHA1 is not a careless default but the one Google Authenticator and most services expect — the HMAC construction used here is not affected by the known SHA1 weaknesses.
Where the data lives
The parameters are stored as custom fields inside the entry, not in a side file:
So the codes travel with the database — moving to a new device carries them over without re-enrolling, and a backup of the .kdbx backs them up too.
In the app
- A dedicated OTP area showing every code at a glance with its countdown ring
- Detail view behind the “…” button: issuer, type, digits, interval, algorithm — the secret only on an explicit tap
- One-click copy of the running code
{TOTP}placeholder in AutoType (macOS) so the code is typed along with the rest- Widget on the iPhone home screen — the app stores pre-calculated codes, no secret ever leaves it
🔐 The flip side: With password and second factor in the same file, the second factor no longer protects against someone who holds that file and your master password. It still protects against everything else — leaked passwords, phishing, reuse. If you need the separation, keep a second database just for OTP entries.
🔐 PassKeys
🚧 Under development. The data model is in place, but the dedicated PassKeys area is still hidden in released versions. This section describes the state of the implementation.
PassKeys (FIDO2/WebAuthn) replace the password with a key pair: the service only ever sees the public half, the private one stays with you. Phishing gets nowhere, because a passkey only works on the domain it was created for.
What iKeePass stores
| Field | Content |
|---|---|
| Credential ID | Identifier of the key (Base64-URL) |
| RP ID / RP Name | Domain and display name of the service, e.g. github.com / GitHub |
| User Name / Display Name | Your account at the service |
| Public Key | Public key in COSE format |
| Algorithm | ES256 (default), RS256, PS256 |
| Transports | internal, usb, nfc, ble |
| Sign Count | Counter for clone detection |
| AAGUID | Identifier of the authenticator |
| Backup Eligible / State | Whether the key can sync, and whether it already did |
As with OTP, everything lives in custom fields of the entry — passkeys travel with the .kdbx.
What already works
- Creating, searching and managing passkey entries
- Lookup by domain and by credential ID
- Duplicate detection via the credential ID
- Configuration validation for missing or inconsistent fields
- Statistics across all passkeys in the database
- Tracking the sign count for clone detection
What is still missing
Signing in with a passkey straight from iKeePass — acting as a full authenticator towards the browser. Until then the area stays hidden in release builds; in development builds it is visible.
ℹ️ OTP vs. PassKeys: An OTP code complements the password, a passkey replaces it. Both live side by side in iKeePass and do not exclude each other.
📥 Import from the Apple Passwords App
Existing data moves from the Apple Passwords app into iKeePass through Credential Exchange — the standard Apple and the FIDO Alliance (as FIDO CXP) built for exactly this.
⚠️ Requirement: iOS 26 or macOS 26 and newer. The interface does not exist on older systems.
Why this beats a CSV export
The usual route between password managers is a CSV or XML file: it sits unencrypted on disk, ends up in the trash, in backups, in the search index. Credential Exchange avoids all of that.
The receiving app gets nothing but an NSUserActivity carrying an access token. It uses that token to fetch the data from the system directly.
What is transferred
Not just passwords — every kind Apple hands over gets a matching entry type and icon in iKeePass:
| Kind | In iKeePass |
|---|---|
| 🔑 Passwords | Entry with title, user, password, URL |
| ⏱️ Verification codes | OTP fields in the entry — codes keep running right away |
| 🔐 Passkeys | Passkey fields in the entry |
| 📶 Wi-Fi | Its own entry with a Wi-Fi icon |
| 💳 Payment cards | Its own entry |
| 🖥️ SSH keys | Its own entry |
| 🔧 API keys | Its own entry |
| 🪪 Identities | Its own entry |
| 📝 Notes | Entry with note text |
| 📋 Extra fields | As custom fields |
How it runs
| Step | What happens |
|---|---|
| Preview | Every item is listed before anything is written |
| Duplicate check | Entries you already have are recognised and skipped (can be turned off) |
| Keep folders | Collections from the Passwords app become folders (can be turned off) |
| Target folder | Freely chosen; the import lands together in one place |
| Summary | Imported, skipped duplicates, unsupported items, folders created |
| Rollback | As long as you have not saved, the whole import can be undone |
Origin stays visible
Every imported entry gets a field iKeePass Import holding source and timestamp, and a 📥 appears in the list, the tile and the detail view. So it stays traceable which move an entry came from — and the duplicate check ignores this field when comparing.
Technically
| Building block | Implementation |
|---|---|
| Interface | ASCredentialImportManager (AuthenticationServices) |
| Trigger | NSUserActivity of type ASCredentialExchangeActivity |
| Handover | An access token instead of data; the app fetches it from the system |
| Format version | 1.0 |
| Requirement in the app | An AutoFill extension announcing SupportsCredentialExchange |
👉 Step-by-step guides for iPhone, iPad and Mac are in the FAQ.
🤖 MCP Server (AI Assistants)
The macOS app ships an MCP server: iKeePass can be driven from Claude Code and other clients that speak the Model Context Protocol. An assistant can search the database, run security analyses, create entries and — after explicit confirmation — fetch individual secrets.
🔐 Off by default. Access has to be switched on deliberately in the settings. And without an unlocked database nothing happens at all.
Why this is less alarming than it sounds
The central design idea: 20 of the 34 tools need no secret access whatsoever. A full security audit — weak passwords, duplicates, expiring entries, HIBP comparison — runs without a single confirmation dialog.
Five locks in front of every access
The connection runs over a local Unix socket, not the network. The peer on the other end is verified as well, so an arbitrary process cannot take over the connection.
Four grant levels
| Level | Scope | What it takes |
|---|---|---|
| S0 | Status, password generator, policies | nothing — no grant needed |
| S1 | Metadata, folders, statistics | Touch ID or master password |
| S2 | Secrets (password, field, TOTP code) | S1 and a confirmation dialog per call |
| S3 | Write operations | S1 and a confirmation dialog per operation |
The double budget
A grant is limited twice over — by time and by count. Whichever runs out first ends it:
| Setting | Default |
|---|---|
| Read grant: duration | 15 minutes |
| Read grant: accesses | 50 |
| Secret grant: duration | 5 minutes |
| Secret grant: accesses | 5 |
| Expiry when idle | 5 minutes |
| Writing allowed | ❌ off |
| Prefer biometrics | ✅ on |
All values can be changed in the settings. An ikeepass_lock is always possible without any question — the panic switch.
34 tools in seven groups
| Group | Topic | Examples |
|---|---|---|
| A | Status and session | ikeepass_status, ikeepass_lock, ikeepass_open_database |
| B | Navigation and metadata | ikeepass_search_entries, ikeepass_get_entry, ikeepass_list_tags |
| C | Secrets | ikeepass_get_password, ikeepass_get_totp, ikeepass_use_credential |
| D | Write operations | ikeepass_create_entry, ikeepass_update_entry, ikeepass_rotate_password |
| E | Analysis without exposing secrets | ikeepass_health_report, ikeepass_check_pwned, ikeepass_list_duplicates |
| F | No database access | ikeepass_generate_password, ikeepass_password_strength, ikeepass_parse_otp_uri |
| G | Audit and policies | ikeepass_audit_log, ikeepass_get_policy |
What is deliberately not offered
These limits are part of the security promise, not a gap in the feature set:
| Not available | Reason |
|---|---|
| 🔑 Master password | It never leaves the app, under any circumstances |
| 📤 Database export | One call would hand over the entire database |
| ⏱️ TOTP secrets | Only the running code is handed out, never the secret behind it |
| 🔐 Passkey private keys | Not readable, not even with a grant |
| 📎 Attachment contents | Files stay inside the database |
| 📚 Bulk queries | No “give me all passwords” |
| 🗑️ Permanent deletion | Entries move to the archive at most |
Opening a database follows the same idea: the agent may only pick from the recently opened list — a free path is rejected, and the password goes exclusively through the app’s own dialog.
Access history
Every access is logged: time, client (for example “Claude Code”), process id, tool and outcome. The history can be reviewed in the app — and through ikeepass_audit_log by the assistant itself, so it can account for what it did.
Typical uses
- 🩺 “Check my database for weak and duplicate passwords” — runs entirely without secret access
- 🔄 “Generate a new password for GitHub and store it” — one confirmation dialog for the write
- 📋 “How many entries expire next month?” — pure metadata
- ⏱️ “Create an OTP entry from this
otpauth://address” — secret masked in the dialog
ℹ️ macOS only. The iOS app has no MCP server; the iPhone offers no comparable interface for local processes.
Developer Information
Architecture
Dependencies
- CommonCrypto - AES encryption
- CryptoKit - SHA-256, HMAC
- zlib - GZIP compression
- Argon2 - Key Derivation (external)