Skip to content

Commit 81ee9c1

Browse files
LcstyleLcstyle
committed
add KeeShare documentation
Implementation design doc, technical reference (keeshare-support.md), and end-user setup guide covering both desktop and Android sides.
1 parent 3a85ca8 commit 81ee9c1

File tree

3 files changed

+572
-0
lines changed

3 files changed

+572
-0
lines changed

‎docs/keeshare-end-user-guide.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# KeeShare End User Guide
2+
3+
How to set up and use KeeShare to sync password groups between KeePassXC
4+
(desktop) and KeePassDX (Android).
5+
6+
---
7+
8+
## What KeeShare Does
9+
10+
KeeShare lets you share specific groups of passwords between devices. Each
11+
shared group is exported to a small encrypted container file. A folder-sync
12+
tool (Syncthing, Nextcloud, etc.) carries these containers between devices.
13+
Each device merges incoming entries into its own database.
14+
15+
Key points:
16+
- Each device keeps its own full database
17+
- Only the shared groups' entries travel between devices
18+
- Each device writes its own container file (`{DEVICE_ID}.kdbx`) — no write
19+
conflicts between devices
20+
- Encryption password per shared group, separate from database master password
21+
22+
---
23+
24+
## Prerequisites
25+
26+
| What | Why |
27+
|------|-----|
28+
| KeePassXC (desktop) with per-device KeeShare support | Configure shared groups, export containers |
29+
| KeePassDX (Android) with KeeShare support | Import/export containers via SAF |
30+
| Folder-sync tool (Syncthing, Nextcloud, etc.) | Move container files between devices |
31+
| KDBX v4 database | KeeShare uses CustomData (not available in KDB format) |
32+
33+
---
34+
35+
## Setup: KeePassXC (Desktop)
36+
37+
### 1. Create a sync folder
38+
39+
Pick a folder that your sync tool will keep in sync between devices.
40+
Example: `~/Sync/KeeShare/`
41+
42+
### 2. Configure a shared group
43+
44+
1. Open your database in KeePassXC
45+
2. Right-click a group (or the root group to share everything)
46+
3. Select **Sharing settings**
47+
4. Set:
48+
- **Type**: Synchronize (bidirectional)
49+
- **Path**: Point to a subfolder inside your sync folder, e.g.
50+
`~/Sync/KeeShare/Passwords/`
51+
- **Password**: Strong password for the container (both devices need this)
52+
5. Click OK, then save the database (Ctrl+S)
53+
54+
KeePassXC immediately exports the group's entries to a container file in the
55+
sync folder, named after its device ID (e.g., `LAPTOP7.kdbx`).
56+
57+
### 3. What KeePassXC does on each save
58+
59+
- Exports the shared group to `{DEVICE_ID}.kdbx` in the sync folder
60+
- Imports from all other `.kdbx` files in the sync folder (other devices'
61+
containers)
62+
- Merges imported entries using timestamp-based conflict resolution
63+
64+
---
65+
66+
## Setup: KeePassDX (Android)
67+
68+
### 1. Get the database onto your phone
69+
70+
Sync or copy your `.kdbx` database file to your phone. KeePassDX needs to open
71+
the same database that has the KeeShare configuration set up in KeePassXC.
72+
73+
### 2. Make sure the sync folder is accessible
74+
75+
The sync folder (containing the container files) must be accessible on your
76+
phone. If using Syncthing, it syncs to a local folder on the device.
77+
78+
KeePassDX accesses sync folders through Android's Storage Access Framework
79+
(SAF) using `content://` URIs — it does not use filesystem paths directly.
80+
81+
### 3. Configure device ID (optional)
82+
83+
1. Open KeePassDX
84+
2. Go to **Settings > KeeShare**
85+
3. **Device ID**: Leave blank to auto-generate, or enter a custom short ID
86+
87+
The auto-generated ID is a random 7-character hex string, persisted in
88+
preferences.
89+
90+
### 4. Sync
91+
92+
1. Open your database in KeePassDX
93+
2. Tap the **overflow menu** (three dots) in any group view
94+
3. Select **"Sync KeeShare"**
95+
96+
KeePassDX will:
97+
- Import entries from all other devices' container files in the sync directory
98+
- Export your entries to your own container file (`{DEVICE_ID}.kdbx`)
99+
- Save the database
100+
- Show a toast: *"KeeShare: imported N entries, exported N entries"*
101+
102+
### 5. Auto-sync
103+
104+
While the database is open, KeePassDX checks for new container files every
105+
15 minutes and syncs automatically. It also exports after every database save.
106+
107+
No manual intervention needed for ongoing sync — just keep the database open
108+
and let the sync tool deliver container files.
109+
110+
---
111+
112+
## Day-to-Day Usage
113+
114+
### Adding a password on desktop
115+
116+
1. Add or edit an entry in a shared group in KeePassXC
117+
2. Save (Ctrl+S) — KeePassXC exports to its container
118+
3. Sync tool delivers the container to your phone
119+
4. KeePassDX picks it up on the next periodic check (or manual sync)
120+
5. Entry appears in the same group on your phone
121+
122+
### Adding a password on phone
123+
124+
1. Add or edit an entry in a shared group in KeePassDX
125+
2. Save — KeePassDX exports to its container (`PHONE01.kdbx`)
126+
3. Sync tool delivers the container to your desktop
127+
4. KeePassXC imports from the container on next save/sync cycle
128+
5. Entry appears in the same group on desktop
129+
130+
### Conflict resolution
131+
132+
If the same entry is edited on two devices between syncs, the newer
133+
modification timestamp wins. The "losing" version is preserved in the entry's
134+
history and can be restored.
135+
136+
---
137+
138+
## How the Sync Folder Looks
139+
140+
```
141+
~/Sync/KeeShare/
142+
├── Passwords/
143+
│ ├── LAPTOP7.kdbx ← KeePassXC's container
144+
│ ├── PHONE01.kdbx ← KeePassDX phone's container
145+
│ └── TABLET.kdbx ← KeePassDX tablet's container
146+
├── Work/
147+
│ ├── LAPTOP7.kdbx
148+
│ └── PHONE01.kdbx
149+
```
150+
151+
Each shared group gets its own subfolder. Each device writes only to its own
152+
file and reads from all others.
153+
154+
---
155+
156+
## Identifying Shared Groups
157+
158+
In KeePassDX, groups with KeeShare configuration display a small share icon
159+
in the group list. This indicates the group participates in sync.
160+
161+
---
162+
163+
## Troubleshooting
164+
165+
| Problem | Solution |
166+
|---------|----------|
167+
| "Sync KeeShare" menu missing | Database must be KDBX, non-read-only, in group view |
168+
| Imported 0 entries | Check: container files present in sync folder? Password match? Sync tool finished? |
169+
| Device ID changed | Set a manual ID in Settings > KeeShare. Old container auto-cleaned after 90 days |
170+
| Entries not appearing on desktop | Verify sync tool delivered `PHONE01.kdbx` to desktop. Re-save in KeePassXC to trigger import |
171+
| Entries not appearing on phone | Verify sync tool delivered desktop's container. Use manual "Sync KeeShare" for immediate check |
172+
173+
---
174+
175+
## FAQ
176+
177+
**Do I need Syncthing specifically?**
178+
No. Any folder-sync tool works — Syncthing, Nextcloud, Google Drive, Dropbox,
179+
or even manual USB copy. KeeShare just reads and writes files in a folder.
180+
181+
**Does KeeShare send passwords over the internet?**
182+
KeeShare itself never touches the network. It only reads/writes local files.
183+
Your sync tool determines whether data travels over a network. Container files
184+
are encrypted regardless.
185+
186+
**Can I share only specific groups, not the whole database?**
187+
Yes. Configure KeeShare on individual groups in KeePassXC. Only those groups'
188+
entries are synced.
189+
190+
**What happens to old device containers from retired devices?**
191+
Automatically deleted after 90 days of no modification. Configurable threshold.
192+
193+
**Does KeeShare work with KDB databases?**
194+
No. KDBX v4 required (uses CustomData for configuration).

0 commit comments

Comments
 (0)