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 automatically save the database since version 3.5.0 if the automatic database save setting is enabled but not in previous versions.
- 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.
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.
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.
-
Moving the database .kdbx file to a new location would cause a revocation, simply reselect the file from its new location.
-
If the link is broken for another reason, 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 -
Note: on certain devices, automatic shortcuts with the application icon but with the path of an inaccessible file as parameter cause this problem. You should launch the application from its original launcher or from its location and not from a device shortcut. If you want to make a shortcut to open a database more easily, simply click on the star in the list of files but open the application from its default launcher.
-
It is also possible that the file manager used does not have permanent access rights to the file. Try giving all files permission to the application called "external storage" with package name com.android.externalstorage. To do this :
- Open the settings
- Scroll down and press the "Apps" button
- Press the three dots located at the top right
- A few fields should pop up, press "special access"
- Press "All File Access". It should be at the top of the list
- Make sure you toggle blue the app called "External Storage". You may have to scroll down to find the app.
Instructions could be different in some devices but the app package name should be the same. (Tested on Samsung devices)
Many cloud file managers have an internal cache and the file may end up in error or out of sync, resulting in un-updated data. To solve the problem, you just need to clear cache the cloud application where the file is stored (for example Google Drive).
KeePassDX does not have a cache at this level and is not responsible if the data sent by the manager is not up to date, so there is no point in making a bug resolution request on KeePassDX. Keep in mind that the basic problem is not with KeePassDX and that it is up to the file managers apps to solve their caching and revocation issues.
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.
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. Tutorials : Peter Babič TroubleChute (video) |
- | No |
| 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). Keeps track of the last visited folder. 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 |
| Anemo | Yes | Open source, private local storage with time access, very well maintained | - | 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. Revokes the file while synchronized data is recovered. Pressing the back button and reselecting the database solves the issue. | 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, and does not work when the network connections are turned off. In the case of a persistent or non-updating database, it is necessary to clear the cache of the Google Drive app. Alternatively, the app DriveSync can be used to integrate GoogleDrive without caching errors. A bug does not allow to open the file in "wt" mode. 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. Using the "Make available offline" option on the Dropbox app allows to better manage synchronization and cache problems. https://help.dropbox.com/sync/access-files-offline | - | 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, corrupts data when the file is selected from OneDrive. In the case of a persistent or non-updating database, it is necessary to clear the cache of the OneDrive app.content://com.microsoft.skydrive.content.StorageAccessProvider/
|
- | 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..)
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.
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
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.