Hello Community,
Ever experienced the case, that your vault got corrupted and directories disappeared into the nirvana? Well, even if you were lucky (or your sync client works properly), it might not be a bad idea to know how you can repair your vault in such a case and recover your directories.
The vault health check introduced with Cryptomator 1.6.0 is your best friend here. It does detect such corruption and can fix it. Unfortunately, the GUI does not provide all the information to understand the matter, and hence, this post now exists.
This post shows you how to restore missing directories and why they disappeared. If you are not interested in the details, you can skip to the last section.
Most of the times, missing directories are caused by improper cloud synchronization. Hence, fixing this on one computer might lead to conflicts or data duplication on other devices.
“Missing” does not always mean lost
From a technical point of view, the term “missing” is misleading in most cases, but to understand how directores may seem “missing”, you need to know the internal structure of a vault.
Cryptomator does not only encrypt files, but also encrypts the directory structure. It is implemented by placing all cleartext directories next to each other on the encrypted storage side and retain their parent-child-relationship with link files named dir.c9r.
Example
You have the Cryptomator vault “myVault”. After unlock, you copy a directory named “foo” containing the file “bar.txt” to the top level of it (aka to the root directory). Then the unlocked “myVault” looks the following:
/ (root dir of myVault)
├─ ...
└─ foo
└─ bar.txt
On the storage location of “myVault”, the following directory structure is present:
/ (myVault)
├─ masterkey.cryptomator
├─ vault.cryptomator
└─ d
├─ BZ
│ └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA # root dir
│ ├─ ...
│ └─ FHTa55bH*sUfVDbEb0gTL9hZ8nho.c9r # directory foo
│ └─ dir.c9r # link file
└─ FC
└─ ZKZRLZUODUUYTYA4457CSBPZXB5A77 # contains contents of foo
└─ gLeOGMCN358*UBf2Qk9cWCQl.c9r # bar.txt
If a link file is getting lost or corrupted (e.g., due to incomplete synchronization), the linked child directory is not listed anymore since its actual content cannot be found. The data is still there, but unavailable from inside the unlocked vault because no other directory points with a link file to it. An (encrypted) directory without any link file pointing to it is called orphan.
In contrast, if the encrypted directory the link file is pointing to does not exist, the data inside is lost.
A user cannot differentiate between these two cases, but for Cryptomator it makes huge difference: In the first case, the data inside the directory can be recovered, in the second case not.
For further information about the internal structure of a vault, read our docs.
Adopting an orphan
Orphaned directories can be recovered using the vault health check within the Cryptomator app. If you start the health check and selected the “Directory Check”, you can get results with a description of “Orphan directory: …” and a “Fix” button next to it. Each such result means, that the health check found an orphan directory in the vault. To regain access to your data, you need to click the “Fix” button, which “adopts” the orphaned directory by creating a link file again.
But since the information, which directory was the original parent containing the link file is lost, Cryptomator needs a fixed place to make the orphans accessible again. To stay in the metaphor, an orphanage is needed. For every vault, this orphanage is a top-level folder called LOST+FOUND (formerly named as CRYPTOMATOR_RECOVERY), which is created during the first adoption and from which every adopted orphaned directory can be accessed.
Example (Cont’d)
On a different device, due to incomplete sync, the dir.c9r file is missing:
/ (myVault)
├─ masterkey.cryptomator
├─ vault.cryptomator
└─ d
├─ BZ
│ └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA # root dir
│ ├─ ...
│ └─ FHTa55bH*sUfVDbEb0gTL9hZ8nho.c9r # empty directory foo, no link file
└─ FC
└─ ZKZRLZUODUUYTYA4457CSBPZXB5A77 # contains contents of foo
└─ gLeOGMCN358*UBf2Qk9cWCQl.c9r # bar.txt
Unlocking your vault, directory “foo” is not displayed anymore, due to the missing link file.
After performing the vault health check and applying the fix, the directory structure of the vault storage location changed to:
/ (myVault)
├─ masterkey.cryptomator
├─ vault.cryptomator
└─ d
├─ BZ
│ └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA # root dir
│ ├─ ...
│ ├─ hquw6zNn*Opqwe5621cbSmQWhxOp.c9r # directory LOST+FOUND
│ │ └─ dir.c9r # link file
│ └─ FHTa55bH*sUfVDbEb0gTL9hZ8nho.c9r # leftover of directory foo
├─ FC
│ └─ ZKZRLZUODUUYTYA4457CSBPZXB5A77 # contains contents of foo
│ └─ gLeOGMCN358*UBf2Qk9cWCQl.c9r # bar.txt
└─ MK
└─ 18UH65JJ9LPV320BXZWWLKSIFD8AMX # contains contents of CRYPTOMATOR_RECOVERY
└─ gLeOGMCN358*UBf2Qk9cWCQl.c9r # directory "foo"
└─ dir.c9r
and looking into the unlocked vault
/ (root dir of myVault)
├─ ...
└─ LOST+FOUND
└─ directory1 # previously named foo
└─ file1 # previously named bar.txt
Unfortunately, the parent-child-relation is not the only lost information. Due to the tamper-proof encryption scheme, the name of the recovered directory and the names of all first-level resources are also lost. If the directory contains a backup file, the names can be recoverd, otherwise not. In the latter case all files are just named “fileX” and all folders “directoryX” where X is an increasing number.
To determine what such an anonymous file contains is the next task.
Next steps
All files are recovered, but since the file names and endings are lost, you very likely don’t know which file contains what data. And to determine the content of a file manually, you need to know the file ending to open it with the correct application.
To determine the file ending, third party applications must be used. We suggest two:
- TrID - For Linux and Windows with a GUI. (A short instruction how to use can be found on superuser)
file- built in POSIX application for Mac and Linux.
For the latter we wrote a short script using it, which sweeps through a given directory and tries to determine the filetype. You can find the script and how to use it here.
tl;dr
- Ensure that the vault is fully synced
- Start the health check
- For all results of severeness “warning” with the description “Orphan directory: …”, click on the fix button
- When all fixes are finished, close the health check
- Unlock the vault and reveal it in the file manager
- Navigate to the new directory
LOST+FOUND - For this directory, check if the filenames are of the pattern
file1_xxxx, file2_xxxx, directory1_xxxx. If so, follow the thread Sanitizer: Restore Missing File Extensions