Skip to content

Consolidate encrypted file name docs and add video walkthrough #138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mindmonk merged 6 commits into from
Apr 8, 2026
Merged

Consolidate encrypted file name docs and add video walkthrough #138

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
282e865
move Locate Encrypted File section to encrypted-file-names and add vi…
mindmonk Mar 30, 2026
8402029
align Decrypt File Name style and mention Locate Encrypted File per i…
mindmonk Mar 31, 2026
3aaad72
fix typo
mindmonk Apr 1, 2026
25c1932
adjust wording to be less awkward and more user accessible.
infeo Apr 1, 2026
2a82c9c
Restructure encrypted-file-names
infeo Apr 7, 2026
ec65adf
update screenshots
mindmonk Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 1 addition & 14 deletions docs/desktop/accessing-vaults.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,20 +58,7 @@ On Windows, you can choose the drive letter of the virtual drive for each vault

## Locate Encrypted File {#locate-encrypted-file}

The Locate Encrypted File feature helps users find the encrypted version of a specific file. This feature is particularly useful when vault files are versioned and the user wants to restore an older version of a file. As Cryptomator encrypts filenames and obfuscates directory structures, users first locate the encrypted file and then restore an older version of the encrypted file with the third party app.

1. Unlock the desired vault.
2. Click on the `Locate Encrypted File` button.
3. Select the file within the vault.

As an alternative for clicking the button, you can directly drag & drop a file onto the button.

A file manager window opens showing the encrypted folder and marking the encrypted file.

<video controls autoplay loop muted style={{width: '100%', maxWidth: '1280px', height: 'auto'}}>
<source src="/vid/locate-encrypted-file.mov" type="video/mp4" />
Your browser does not support the video tag.
</video>
See [Locate Encrypted File](/docs/desktop/encrypted-file-names.md#locate-encrypted-file) in the Encrypted File Names section.

## File System Case Sensitivity {#file-system-case-sensitivity}

Expand Down
85 changes: 58 additions & 27 deletions docs/desktop/encrypted-file-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,59 @@ sidebar_position: 7
# Encrypted File Names

:::info
Neither file name nor directory structure encryption can be disabled.
File name and directory structure encryption **cannot** be disabled.
:::

Cryptomator protects your files by not only encrypting their content, but also their names and the overall directory structure of the vault.
For example, if you have a directory structure inside your vault like this:
Cryptomator protects your files by not only encrypting their content, but also their names and the overall directory structure of the vault. As a result, encrypted files and folders inside the vault storage location do not reveal the original names or layout (for an example see [below](#technical-example)).

This matters whenever you need to match a cleartext file in your unlocked vault with its encrypted counterpart in the vault storage location, for example when restoring an older version from a cloud provider or backup tool.

The app offers two features to reveal the mapping between the cleartext and the encrypted files:
* `Locate Encrypted File`: You have the cleartext file in the unlocked vault and want to find its encrypted counterpart in the vault storage location.
* `Decrypt File Name`: You have an encrypted vault file and want to know its original cleartext name.

<Image src="/img/desktop/encrypted-file-names-vault-detail-unlocked.png" alt="Vault detail view in the unlocked state" width="495" height="381" />

## Locate Encrypted File {#locate-encrypted-file}

The Locate Encrypted File feature helps you find the encrypted counterpart of a file from inside the vault. This comes in handy when you want to restore an older version of a file. As Cryptomator encrypts file names and obfuscates directory structures, first locate the encrypted file and then restore an older version of the encrypted file with your third-party app.

1. Unlock the desired vault.
2. Click on the `Locate Encrypted File` button.
3. Select the file within the vault.

As an alternative for clicking the button, you can directly drag & drop a file onto the button.

A file manager window opens showing the encrypted folder and marking the encrypted file inside the vault storage location.

## Decrypt File Name {#decrypt-file-name}

The Decrypt File Name feature helps you resolve encrypted file names back to their original cleartext names.

1. Unlock the desired vault.
2. Click on the `Decrypt File Name` zone at the bottom of the unlocked view.
3. Select the encrypted file.

As an alternative for clicking the zone, you can directly drag & drop files onto it.

A modal window opens showing a two-column table with the encrypted names on the left and their decrypted, cleartext names on the right.

<Image src="/img/desktop/decrypt-file-names.png" alt="Decrypt file names window" width="311" height="385" />

The action bar at the top of the table provides two buttons:
* Clipboard button to copy the whole table as CSV into the system clipboard
* Trash button to clear the table

You can select single cells and copy their content with the OS-specific keyboard shortcut.

:::note
For technical reasons, Cryptomator can only decrypt the *file name* of a given encrypted file.
It cannot tell where that file is located in the unlocked vault.
:::

## Technical Example

If you have a directory structure inside your vault like this:

```
.
Expand Down Expand Up @@ -40,30 +88,13 @@ The actual directory structure of the vault on your hard drive/cloud will look l
└─ vault.cryptomator
```

While this increases security, it also makes it impossible to see the original file names and directory structure without decrypting them first.
When you need to know the original name of a file (e.g. to restore an older version), you can use the `Decrypt File Name` feature to decrypt the file name.

## Decrypting File Names {#decrypting-file-names}
This is why you cannot identify files in the vault storage location by name alone without decrypting them first. For more information about the vault encryption scheme read [the specification](/docs/security/vault.md).

:::note
Due to technical reasons, given only an encrypted file Cryptomator can only decrypt its name.
It cannot compute its cleartext path.
:::

You can access this feature from the unlocked view of a vault in the Cryptomator main window.
On the bottom of the unlocked view, drop files on the `Decrypt File Name` zone or click on it.
A modal window with the encrypted-decrypted-mapping opens.

<Image src="/img/desktop/vault-detail-unlocked.png" alt="Vault detail view in the unlocked state" width="495" height="381" />

The encrypted-decrypted-table has an action bar at the top with two buttons:
* Clipboard button to copy the whole table as a CSV into the system clipboard
* Trash button to clear the table

<Image src="/img/desktop/decrypt-file-names.png" alt="Decrypt file names window" width="311" height="385" />
## Video Walkthrough

Encrypted file names and their corresponding decrypted, original name are shown inside a two column table, with the encrypted names on the right.
If you have not dropped any files, the table is empty.
You can click inside the empty table to select files with a file picker dialog.
The following video demonstrates both features in action: first, **Locate Encrypted File** to find the encrypted counterpart of a file, and then **Decrypt File Name** to resolve an encrypted file name back to its original name.

Once the table has content, you can select single cells and copy their content with the OS specific keyboard copy shortcut.
<video controls autoplay loop muted style={{width: '100%', maxWidth: '1280px', height: 'auto'}}>
<source src="/vid/file-names.mov" type="video/mp4" />
Your browser does not support the video tag.
Comment on lines +97 to +99
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

For an HTML5 <video><source>, what MIME type should be used for a .mov file, and what are browser compatibility implications versus .mp4 (H.264/AAC)?

💡 Result:

The standard MIME type for a .mov file (QuickTime container) is video/quicktime. However, video/quicktime has very limited browser support in HTML5

Citations:

🏁 Script executed:

#!/bin/bash

# Search for the video file reference in the docs directory
echo "=== Searching for video file references ==="
rg "file-names\.mov" docs/ 2>/dev/null || echo "No direct .mov references found"

# Check if assets directory exists and what's in vid directory
echo -e "\n=== Checking for vid directory ==="
find . -type d -name "vid" 2>/dev/null | head -20

# Search for any video file references in the repository
echo -e "\n=== Searching for any video file references ==="
rg "\.mov|\.mp4" docs/ --type md | head -20

# Check the exact file that was changed
echo -e "\n=== Checking the documentation file ==="
if [ -f "docs/desktop/encrypted-file-names.md" ]; then
  sed -n '83,90p' docs/desktop/encrypted-file-names.md
fi

Repository: cryptomator/docs

Length of output: 1003

Fix media type mismatch: convert .mov to .mp4.

The video file is a .mov file but declared as type="video/mp4". While .mov files with H.264/AAC codecs may play in Safari and Firefox, they will fail silently in Chrome and Edge (which enforce strict MIME checking). Convert the file to .mp4 format and keep type="video/mp4" for universal browser support across all modern browsers.

Alternatively, use type="video/quicktime" for the .mov file, but this has very limited browser support and is not recommended for production documentation.

Recommended fix: convert to .mp4 
-  <source src="/vid/file-names.mov" type="video/mp4" />
+  <source src="/vid/file-names.mp4" type="video/mp4" />
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/desktop/encrypted-file-names.md` around lines 87 - 89, The <video> block
uses a .mov source but declares type="video/mp4"; convert the file
/vid/file-names.mov to an MP4 (H.264/AAC) and update the <source> element to
point to /vid/file-names.mp4 while keeping type="video/mp4" so browsers
(Chrome/Edge) correctly detect the MIME type; locate the <video> tag and its
<source> element in the doc and replace only the file extension/URI to .mp4.

</video>
Binary file modified static/img/desktop/decrypt-file-names.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/desktop/encrypted-file-names-vault-detail-unlocked.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/vid/file-names.mov
View file
Open in desktop
Binary file not shown.