File Manager

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

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

Save, Merge and Reload

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.

Compatibility

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.

File access revocation

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.

Solution and workaround

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

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)

Database not updated

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.

Synchronization application

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.

File Manager application

Related issues : #342, #897

How it works

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..)

Why disparate compatibility?

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.