File Manager and Sync
The KeePassDX app uses your device's external file managers and the storage access framework connection capabilities of these third-party app to edit database files.
You should see KeePassDX as a file editor and not a file manager. Links in the list of recent databases are only quick references to access historic links provides by the external file app used to open your database file.
KeePassDX does not have an internal database file copy to synchronize data. This allows for greater scalability and configuration, no data is stored in the application when the database is closed.
With this system, a database file can be :
- stored and used locally to the device.
- stored on a medium external storage to the device (ie: OTG). If the device is lost, no data, even encrypted, can be recovered.
- provided by any remote file manager (cloud app).
The file can therefore be local or remote depending on your needs and the file manager used.
Native synchronization of KeePass files makes it possible to update the data of the same file opened and modified from two places at the same time.
Synchronization can therefore be seen as a two-step action:
- Data recovery from a predefined shared location. It is not up to KeePassDX to handle this step, because the architecture of the Android system is built in such a way that a dedicated application manages to send and receive the files and then propose them through a URI. Here, KeePassDX is only an editor and many people blame it when most of the file synchronization problems are caused by the cloud application used because it doesn't handle file conflicts or has caching problems. See the table below for more explanations. The creation of a new file app fully compatible with open protocols and cloud clients is under study. (Dedicated app sync project : https://github.com/Kunzisoft/FileSync)
- The merge of the updated data. When the URI provides new data, KeePassDX is able to merge the currently open data with this retrieved data. (from version 3.2.0)
For more information on data merge: #840
For more information on why not to integrate directly the Cloud APIs: #342
There are 3 commands in KeePassDX to manage the synchronization :
- Save data : As the name suggests, it allows you to save the local data of the open database in the open data stream from its URI. This is the conventional method used to update the data on the reference medium.
- Merge data : Retrieves the data from the URI and merges it with the local data. This command does not ask for a credential, if you change the main password, use Merge from.... Please note that this command does not automatically save the database even if the automatic database save setting is enabled. You will have to save the database manually after a merge if that is what you want.
- Reload data : Retrieves data from the URI and deletes local data. Use this method if you want to reset the data in your database with the data in the storage medium.
If external modifications are made to the data linked to the URI, a warning message will alert you. But it is possible that this warning message is not displayed because the event has not been correctly sent, in this case, you just have to make a merge or reload the data.
In addition to the commands described above, it is possible to use more advanced derived commands:
- Merge from... : Performs a merge with the same characteristics as the Merge data command but with a different URI file. The main credentials of the database to be merged will always be requested. It is possible to merge databases of different versions with this command. (For example: possible to merge a .kdb v1 database into a .kdbx v4 database)
- Save a copy to... : Saves current data to another specified file (URI). The data of the current URI are not modified.
In addition, there are applications that synchronize files on a continuous basis. This allows you to retrieve and send files transparently in the background when a file is updated. Very useful if your file manager does not have this feature.
| Sync app | Pros | Cons | Officially tested |
|---|---|---|---|
| Syncthing | Widely used open source application that allows decentralized synchronization. Warning: some users have noticed corruptions when Syncthing was synchronized at the same time as a data save because the URI stream is cuts by the sync. Please make sure that the two actions are not done at the same time, you can disable the automatic save and remember to make regular manual backups. Tutorial : https://peterbabic.dev/blog/sync-keepass-passwords-between-computer-phone/ | - | No |
KeePassDX communicates with a separate file manager, or cloud clients that can be online or offline, the goal is to encapsulate the components, in the philosophy of Open Source software with the best security possible.
Important note: in many third-party applications, you have to select your database files from the desired app and not from KeePassDX because does not offer integration with the pre-installed file manager. Ask the developer of your favorite cloud application if you want this feature.
In order to have the most complete visibility of the file services that work with KeePass, you can leave comments to indicate whether your file app or your cloud client is fully working or not.
| File manager / cloud client app | Works | Pros | Cons | Officially tested |
|---|---|---|---|---|
Files (DocumentsUI) |
Integrated by default with almost all systems (but is sometimes hidden to users). Note: Full integration applies to local files, and only to cloud files provided by compatible apps (i.e. GDrive, see below). content://com.android.externalstorage.documents/
|
Open source in AOSP code | - | Yes |
| Material Files | Yes content://me.zhanghai.android.files.file_provider/
|
Open source, connection to an FTP server, very well maintained | - | Yes |
| RCX | ? | Open source, easy to use, connections to a large amount of remote services (Clouds, HTTP, FTP, SFTP, WebDAV). | Contains proprietary APIs | No |
| Mixplorer | Does not provide the correct file date metadata, which displays the modification popup each time a database is opened. May lose the URI connection to the database file, in which case it must be reselected from MixPlorer app. content://com.mixplorer.file/
|
Easy to use, connections to a large amount of protocols and almost all cloud storage (Clouds, SAMBA, FTP, SFTP, WebDAV) | Closed source code, may prevent save depending on source | No |
| NextCloud | Yes if integrated with de default File app | Open source | More difficult to set up for a private server | No |
| OwnCloud | - | Open source | More difficult to set up for a private server | No |
| Google Drive | Partially if integrated with default File app. Data loss can happen when file is updated from somewhere else. The links expire after a time. In the case of a persistent or non-updating database, it is necessary to clear the cache of the Google Drive app. content://com.google.android.apps.docs.storage/content://com.google.android.apps.docs.storage.legacy/
|
Easy to use | Closed source code, proprietary license | No |
| Dropbox | Succinctly, read and write with Android 10, only read with Android 8 (stops the file stream). Not integrated. Breaks the file link systematically (issue). Can prevent file writing with read only mode. | - | Closed source code, proprietary license | Yes 194.2.4 |
| OneDrive | URIs appear to be reassigned to other files once revoked. This results in an attempt to open files that are not databases. Seems to delete data if the state of OneDrive is not correct. | - | Closed source code, proprietary license | No |
| PCloud | Does not allow save of the database file, integrated with default File app content://com.pcloud.pcloud.documents/
|
- | Closed source code, proprietary license | Yes (2.13.1) |
| Samsung "My Files" | Breaks the file link after a file modification | - | Closed source code, proprietary license | No |
| CX Explorer | Does not automatically recognize mime type ("Other" must be selected) | Allows connection to common clouds and protocols (FTP, SFTP, WebDAV) | Closed source code, proprietary license | Yes (1.4.6) |
It is not planned to integrate the cloud APIs directly in KeePassDX, because it would be necessary to integrate each client one-by-one (incidentally this could cause security breaches and is not necessarily compatible with the libre licensed code-base).
KeePassDX uses the storage access framework of your file manager and its content provider provides a URI that is represented by the displayed Path. The direct file tree will not be accessible to KeePassDX for security reasons. This mode of operation allows interoperability with all properly designed file providers, without using write permissions.
For a better understanding : it's like looking at a website, you have a URL that displays a page and you can only access the files on the page through that URL, you don't see the file tree on the server. Here it is the same with URIs, and the advantage is that the file manager can be a gateway to retrieve the database file with any protocol (WebDav, FTP, direct path, whatever..)
Unfortunately, several file managers offer links with a limited duration or with break conditions. In this case, the URI link can be broken , the URI delivered by the third app that accesses the file does not provide a stream anymore or changes the metadata of this URI, and KeePassDX shows the error Access to the file revoked by the file manager or Could not find file. Try reopening it from you file browser. You must therefore reselect the database file from it's location in your file manager app. (KeePassDX cannot change this internally, You can ask the developers of your file manager app to modify this behavior.)
For a better understanding : it is like if an URL internet address changed (because the server changed its configuration [here the file manager]), you may have a bookmark on your browser [here the history link in KeePassDX], if the address pointed to is no longer the same, the content is simply not accessible anymore.
If the link is broken, re-open the file manager first, then select the .kdbx file from it. KeePassDX will then launch automatically with the right configuration if the URI provided is the same. If the URI is not the same, the biometric recognition will have to be reconfigured, as it is linked to only one URI.
You can display the list of broken links by deactivating the setting : Settings -> App settings -> Hide broken database links
File managers content providers must keep the links active with the flag FLAG_GRANT_PERSISTABLE_URI_PERMISSION to be fully functional. These methods are standardized and provided in the official documentation of Android, so it is not the fault of KeePassDX if your preferred file manager does not use these method.
When using Storage Access Framework, write permissions are no longer required. But beware of the links provided, if you select your file from the list of recent files, the file may be read-only because several file managers ignore the file write request implicitly defined in the intent (flag FLAG_GRANT_WRITE_URI_PERMISSION) or the link is simply broken and is no longer provided by the content provider of your file manager.
By selecting your file from the file manager and not from the OPEN EXISTING DATABASE button of KeePassDX, the link will necessarily be of type ACTION_GET_CONTENT and it will not be possible to request a persistence of the link which will be easily broken. So go through the KeePassDX open button to request a persistent link with an ACTION_OPEN_DOCUMENT intent, this will open the default file manager "Files" of your device.
If your favorite file manager is not proposed with this method, the app you are using is not integrated with the base "Files" app and you must ask the developer of this app to implement it.
By making a simple click on the OPEN EXISTING DATABASE button, you make a request for an ACTION_OPEN_DOCUMENT intent.
By making a long click on the OPEN EXISTING DATABASE button, you are requesting an ACTION_GET_CONTENT intent.
Important : Since Android 11, third-party apps can no longer be the client for requests to open and create files, so only the default "Files" app is usable and the "Intent action" section with ACTION_OPEN_DOCUMENT and ACTION_CREATE_DOCUMENT is no longer relevant. You will have to either go through the third party app directly, or go through its implementation in "Files" already integrated in your device. https://developer.android.com/about/versions/11/privacy/storage
Important info for debloated or custom firmware devices: there's a higher chance that you may face with the message saying "A file manager that accepts the ACTION_CREATE_DOCUMENT and ACTION_OPEN_DOCUMENT intent action is required to create, open, and save database files". It means, you have the same issue as described above. Besides already given solutions, you may want to restore default "Files" application from Android system partition using path /system/priv-app/GoogleDocumentsUIPrebuilt/GoogleDocumentsUIPrebuilt.apk.