From 1.5.x to 1.6.x - Migrating filenameLengthLimit

Knowledge Base Guides
1

With Cryptomator 1.6.0, the internal setting filenameLengthLimit is replaced by a similar but different setting.

This article explains why the change was necessary and, for users who manually changed the setting, contains a guide how you can safely update to 1.6.x without breaking your setup.

About filename lengths

Cloud storage providers may limit the length of a filename, i.e., if a file exceeds this limit, it cannot be uploaded into the cloud. This is of relevance for Cryptomator because the filename encryption increases the length of a filename by roughly 34% due to encryption and encoding. To keep compatibility with as many cloud storages as possible, Cryptomator can shorten the filename of encrypted files (since only those are actually stored) preserving the original name. The value, when the shortening is applied, is called shortening threshold.

The shortening threshold addresses issues on the (cloud) storage side of the encrypted files. But what if there is an issue with the integration of the aforementioned storage into the local system? As an example, for WebDAV mounted storages, the Windows Explorer can only display paths with a maximum of 260 characters. Hence, Cryptomator should ensure that no new vault content can exceed this path limit. Due to the special structure of a vault, this boils down to a second filename length limit, this time device-specific. And since the length of the decrypted name and the encrypted name of a file have a clear mathematical relationship, we can just talk about the more user-friendly decrypted name. Files with an exceeding decrypted name are either rejected when put into the vault or not displayed when already present (e.g., due to cloud synchronization).

So, overall there are two limits: While the shortening threshold circumvents problems on the (cloud) storage side, the maximum filename length limit mitigates problems on the device side (i.e., listing decrypted content).

Why does this matter?

With vault format 7, the shortening threshold was increased to 220 characters. But even with a long open test period, the change broke some setups and we needed to introduce a quick workaround. To move the workaround to a solid foundation and prepare to support more edge cases in the future, the following changes werde made in Cryptomator 1.6.x:

  • The installation and vault-specific setting filenameLengthLimit limiting the encrypted filename length is removed. Users who manually altered the value, need to perform a manual migration.
  • A new property named maxCleartextFilenameLength is created in the settings file to limit the cleartext filename length. The purpose of this property is clear by reading it and for users easier to handle, since normally one only deals with cleartext files.
  • Each vault get its own, fixed shortening threshold (see Vault Format 8 article). It will be set at vault creation or during migration to format 8 and cannot be changed afterwards.

Manual migration

âť—âť—âť—

If you never touched the `settings.json` file, then this section has no relevance for you, we even suggest to skip it. It is solely for the small part of Cryptomator users who needed to modify the file due to a restrictive cloud provider.

âť—âť—âť—

In the first step, you need to backup the current local settings file (called settings.json). Afterwards, install Cryptomator 1.6.0. Now, start Cryptomator create a new vault and quit Cryptomator again. You can remove this vault after finishing the guide. Ensure Cryptomator is not running (otherwise your changes will be lost), open the recent settings.json, and for each manually set filenameLengthLimit entry:

  1. Identify the vault you need to edit in your settings backup:
{
  "directories": [
    {
      "id": "wppGFkkAHKAf",
      "path": "P:\\ath\\to\\Vault",
      "displayName": "vaultToMigrate",
      // more properties before...
      "filenameLengthLimit": 220, // <-- oldValue, which was manually set
      // ... and after
    },
    // more vaults
  ],
}
  1. Compute the new value with the following function:
newValue = floor((oldValue - 4) / 4 ) * 3 - 16
  1. Use the new value for the maxCleartextFilenameLength property in the updated settings file:
{
  "directories": [
    {
      "id": "wppGFkkAHKAf",
      "path": "P:\\ath\\to\\Vault",
      "displayName": "vaultToMigrate",
      // more properties before ...
      "maxCleartextFilenameLength": 146,  // <-- newValue
      // ... and after
    },
    // more vaults
  ],
}

And you are done. You can delete the freshly created vault. It was only needed to force Cryptomator updating the settings file.

Even though this manual targets only a very small amount of Cryptomator users, we didn’t want to leave them on their own. We hope you enjoy the 1.6.x versions of Cryptomator!

2 Likes