# KeePass Migration Guide

Import KeePass or KeePassXC vaults into DVE using your **`.kdbx` database file** directly, or an **KeePass XML** export.

## Prerequisites

- KeePass 2.x, KeePassXC, or compatible `.kdbx` database
- **Master password** for the database (required for KDBX import in DVE)
- DVE **IT Admin** or **Super Admin** role
- Backup copy of your `.kdbx` file before migration

## Path A — KDBX import (recommended)

No export step is required — DVE reads the encrypted database file directly.

1. Locate your KeePass database file (`.kdbx`) on disk.
2. In DVE **Import**, choose source format **KeePass KDBX**.
3. Upload the `.kdbx` file.
4. Enter the **KeePass master password** when prompted (used only to decrypt entries for import — it is not stored by DVE).
5. Start the import job and wait for completion.

## Path B — KeePass XML export

Use XML when you cannot upload the KDBX file or need a plaintext interchange format.

1. Open **KeePass** or **KeePassXC**.
2. Unlock the database with your master password.
3. Go to **File → Export**.
4. Choose **KeePass XML (2.x)**.
5. Save the `.xml` file locally.

**Security warning:** KeePass XML is **unencrypted plaintext**. Delete the XML file immediately after a successful DVE import.

In DVE, choose source format **KeePass XML** and upload the file.

## Group and folder mapping

KeePass **groups** map to DVE **folders**. Nested groups become folder paths (for example, `Work/Cloud/AWS`).

| KeePass source | DVE field |
|----------------|-----------|
| Entry title | `name` |
| UserName field | `username` |
| Password field | `password` |
| URL field | `url` |
| Notes field | `notes` |
| Group path | `folder` |
| TOTP setup fields | `totp_secret` |
| Custom string fields | `custom_fields` |

## Recycle Bin handling

Entries in KeePass **Recycle Bin** / **Trash** groups are **skipped** during import. Empty the recycle bin before export if you want those entries excluded, or leave them in place to omit deleted items automatically.

## DVE field mapping

| KeePass element | DVE field | Notes |
|-----------------|-----------|-------|
| Title | `name` | Required |
| UserName | `username` | Standard login field |
| Password | `password` | Standard login field |
| URL | `url` | Primary URL |
| Notes | `notes` | Entry notes |
| Group hierarchy | `folder` | Nested path preserved |
| TimeOtp / OTP custom fields | `totp_secret` | Validated during import |
| Additional string fields | `custom_fields` | Non-standard keys preserved |
| Recycle Bin entries | — | Skipped intentionally |

## Known limitations and quirks

- **Attachments** inside KeePass entries are not imported.
- **Database key files** (`.key`) — you must unlock with master password for KDBX upload; key-file-only unlock may require exporting to XML from KeePass first.
- **Large KDBX files** may take longer to decrypt and parse — allow extra time.
- **XML exports are plaintext** — treat like any other password export.

## Import into DVE

1. Choose **KeePass KDBX** or **KeePass XML**.
2. Upload the file (and supply master password for KDBX).
3. Review import warnings for entries missing titles or invalid TOTP data.

## Post-import verification checklist

- [ ] Entry count matches active (non-recycle-bin) KeePass entries.
- [ ] Group/folder tree looks correct in DVE.
- [ ] Custom fields appear on entries that used KeePass string fields.
- [ ] TOTP entries imported or flagged in warnings.
- [ ] Delete any XML export and remove KDBX from unsecured download folders.
- [ ] Rotate KeePass master password if XML was stored on shared media.

## Related guides

- [Migration Overview](overview.md)
- [1Password Migration Guide](1password.md)
- [Generic CSV Migration Guide](generic-csv.md)