# Cryptomator Documentation ## android - [Working with Vaults](/android/access-vault.md): This section shows you how to work with a vault like view its content, move files or access it with other applications. - [Cloud Management](/android/cloud-management.md): In "Cloud Services", you can create or edit the connection between the Cryptomator app and your storage provider accounts. - [Settings](/android/settings.md): You can configure Cryptomator to your needs. - [Setup](/android/setup.md): You can get Cryptomator for Android on: - [Vault Management](/android/vault-management.md): A vault is where your files are stored encrypted on your Android device or cloud storage. ## desktop - [Accessing Vaults](/desktop/accessing-vaults.md): You can only access decrypted files of a vault if you can unlock it. Unlocking a vault is just a two-step process as long as you know the password. - [Adding Vaults](/desktop/adding-vaults.md): You will be presented with three options when adding a vault: - [Admin Configuration](/desktop/admin-config.md): The admin configuration allows device or system administrators to define environment properties for Cryptomator so it runs in the desired context for all users on a device. - [Common Errors](/desktop/common-errors.md): This page collects errors users frequently run into and their known solutions. - [Encrypted File Names](/desktop/encrypted-file-names.md): File name and directory structure encryption cannot be disabled. - [Error Handling](/desktop/error-handling.md): If you encounter an unexpected error, Cryptomator gives you the option to look up a solution in our error database. It's possible that the error has already been reported and a solution has been suggested for you to follow. - [Files in Use](/desktop/files-in-use.md): This feature is only available for Cryptomator Hub vaults. - [Getting Started](/desktop/getting-started.md): You will be greeted with the following screen when you start Cryptomator for the first time. - [Network Settings](/desktop/network.md): In general, Cryptomator does not require a network connection to function. - [Password and Recovery Key](/desktop/password-and-recovery-key.md): This section explains how to change a password for a vault, show its recovery key, and reset a password. - [Setup](/desktop/setup.md): The Desktop version of Cryptomator is currently available for Windows, macOS, and Linux. - [Synchronization Conflicts](/desktop/sync-conflicts.md): Working on encrypted data from multiple locations is the same as working on unencrypted data from multiple locations. - [Troubleshooting](/desktop/troubleshooting.md): This page contains solutions for common issues you might encounter when using Cryptomator on desktop platforms. - [Events and Event View](/desktop/vault-events.md): Vault events provide information about your vault's status and activities during file operations. Cryptomator generates events to help you monitor vault health and troubleshoot issues like sync conflicts or file corruption. - [Vault Management](/desktop/vault-management.md): A vault is where your files are stored encrypted. - [Vault Recovery](/desktop/vault-recovery.md): If a vault cannot be added to Cryptomator or opened from inside the app anymore, you can use the Vault Recovery feature to unlock it again. - [Volume Types](/desktop/volume-type.md): Volume types play an important role when handling your files. ## hub - [Admin Guide](/hub/admin-guide.md): Everything you need as a Hub administrator — users and groups, identity provider, Emergency Access, audit logs, Web of Trust, and license. - [Audit Logs](/hub/admin-guide/audit-logs.md): The Audit Logs provide an overview of security-related events within Cryptomator Hub. - [Emergency Access](/hub/admin-guide/emergency-access.md): Visit cryptomator.org for more information about Enterprise features. - [Identity Provider](/hub/admin-guide/keycloak.md): Cryptomator Hub delegates authentication and user management to Keycloak, an open-source identity and access management solution. Hub ships with a preconfigured realm named cryptomator that contains the clients Hub needs and the realm roles user, create-vaults, and admin. - [License](/hub/admin-guide/license.md): Every Cryptomator Hub instance requires a license. - [Quick Start](/hub/admin-guide/quick-start.md): Your first day as a Hub administrator — add users and groups, connect your identity provider, enable Emergency Access, and keep an eye on audit logs and license seats. - [User & Group Management](/hub/admin-guide/user-group-management.md): Users and groups are managed directly in the Cryptomator Hub admin interface. As an administrator, you can create, edit, and delete users and groups, assign roles, and manage group memberships. - [Web of Trust](/hub/admin-guide/web-of-trust.md): The Web of Trust (WoT) feature in Cryptomator Hub helps users verify each other's identity by signing the User Key Pair with their private keys using ECDSA. - [Cryptomator Hub](/hub/introduction.md): Cryptomator Hub adds zero-knowledge key management for teams and organizations to Cryptomator, ensuring your confidential - [New Features](/hub/new-features.md): Cryptomator Hub 2.0.0 introduces the following new features: - [Self-Hosting Guide](/hub/self-hosting-guide.md): Everything you need to run Hub yourself — a local test instance, production deployment recipes, and maintenance tasks. - [Deployment Cookbook](/hub/self-hosting-guide/deployment.md): This section collects recipes for running Cryptomator Hub in production. If you just want to try Hub, start with the Quick Start instead. For an end-to-end walkthrough from deployment to backups, see Going to Production. - [Docker Compose](/hub/self-hosting-guide/deployment/compose.md): Run Hub on a single Docker host behind Traefik. - [Kubernetes](/hub/self-hosting-guide/deployment/kubernetes.md): Install the Helm chart with the Helm CLI. - [Rancher](/hub/self-hosting-guide/deployment/rancher.md): Install the Helm chart through the Rancher UI. - [Operations](/hub/self-hosting-guide/operations.md): All state of Cryptomator Hub lives in the PostgreSQL database: the hub database holds vaults, keys, and the audit log, the keycloak database holds users, groups, and credentials. Back up both, and always do so before upgrading. For an end-to-end walkthrough from deployment to backups, see Going to Production. - [Quick Start](/hub/self-hosting-guide/quick-start.md): Want to see Cryptomator Hub in action before rolling it out to your team? This guide gets a test instance running on your own machine in about 10 minutes. No domain, no TLS certificates, no reverse proxy. - [User Guide](/hub/user-guide.md): Everything you need as a Hub user — your account, your vaults, and how you open them with the Cryptomator apps. - [Working with Vaults](/hub/user-guide/access-vault.md): To encrypt your data securely with Cryptomator Hub vaults, you need the Cryptomator app for your OS. - [Quick Start](/hub/user-guide/quick-start.md): From your first login to an unlocked vault — set up your account, create a vault, invite teammates, and unlock it with Cryptomator. - [Vault Management](/hub/user-guide/vault-management.md): The central entities in Cryptomator Hub are vaults. - [Vault Recovery](/hub/user-guide/vault-recovery.md): This section contains instructions for recovering Cryptomator Hub vaults using the vault recovery key. - [Your Account](/hub/user-guide/your-account.md): To open vaults secured by a Cryptomator Hub instance, you need an account on the regarding Hub instance. ## ios - [Working with Vaults](/ios/access-vault.md): Cryptomator for iOS is fully integrated into the Files app of iOS. In order to access your encrypted data, you have to use the Files app. - [Cloud Management](/ios/cloud-management.md): WebDAV {/ #webdav /} - [Settings](/ios/settings.md): You can configure Cryptomator to your needs. Access the settings by tapping the gear icon in the top left corner. - [Setup](/ios/setup.md): You can get Cryptomator for iOS on the App Store. - [Shortcuts Guide](/ios/shortcuts-guide.md): The Shortcuts integration of Cryptomator allows you to build different automations in the Shortcuts app. With that, you can automate recurring tasks quickly and easily. - [Vault Management](/ios/vault-management.md): Unlock Duration {/ #unlock-duration /} ## misc - [Contribute](/misc/contribute.md): How Can You Help Us? {/ #how-can-you-help-us /} - [Glossary](/misc/glossary.md): Terms {/ #terms /} - [Manual Migration](/misc/manual-migration.md): Under some circumstances, Cryptomator refuses to automatically migrate a vault to a newer format. In this case, your vault will remain untouched, so you can continue using it with the previous version. - [Supported Cloud Services](/misc/supported-cloud-services.md): A standard use case for Cryptomator is storing your encrypted vaults in a Cloud Service of your choice for - [Vault Format History](/misc/vault-format-history.md): Cryptomator vaults need to adhere to a structure and format (as described in Security Architecture) that may change over time. ## security - [Security Architecture](/security/architecture.md): Virtual Filesystem {/ #virtual-filesystem /} - [Best Practices](/security/best-practices.md): Sharing of Vaults {/ #sharing-of-vaults /} - [Cryptomator Hub](/security/hub.md): Cryptomator Hub facilitates asymmetric encryption to allow sharing the key material used in Cryptomator vaults between multiple parties. - [Security Target](/security/security-target.md): Cryptomator was designed to solve privacy issues when saving files to cloud storages. - [Vault Cryptography](/security/vault.md): File Header Encryption {/ #file-header-encryption /} - [Verify Installer Signatures](/security/verify-installers.md): If you are not sure whether an alleged Cryptomator installer is legitimate, you can verify its authenticity and integrity. --- # Full Documentation Content # Working with Vaults This section shows you how to work with a vault like view its content, move files or access it with other applications. ## Unlock Vault[​](#unlock-vault "Direct link to Unlock Vault") If you want to access the data inside a vault, you have to unlock it by selecting it. ![How to unlock a vault with Android](/img/android/unlock-vault-0-select.png) In the next step, you have to unlock the vault using the password. If the device supports fingerprint authentication and you've activated it in the settings for this vault, you will be prompted to unlock using fingerprint. How to setup fingerprint authentication will be documented in a separate chapter. ![How to unlock a vault with Android](/img/android/unlock-vault-1-using-password.png)![How to unlock a vault with Android](/img/android/unlock-vault-2-using-fingerprint.png) After providing the credentials, the vault gets unlocked and opened. ![How to unlock a vault with Android](/img/android/unlock-vault-3-loading.png)![How to unlock a vault with Android](/img/android/unlock-vault-4-unlocked.png) You're now able to edit the content of the vault. ## Lock Vault[​](#lock-vault "Direct link to Lock Vault") To lock an unlocked vault, there are several ways to do this: * use the lock button in the vault list ① * use the lock button in the notification ② * use the lock button in the vault actions ③ and ④ ![How to lock a vault with Android](/img/android/lock-vault-0-lock.png)![How to lock a vault with Android](/img/android/lock-vault-1-notification.png)![How to lock a vault with Android](/img/android/lock-vault-2-lock-start.png)![How to lock a vault with Android](/img/android/lock-vault-3-select-lock.png) All of the possibilities will result in the locked vault. ![How to lock a vault with Android](/img/android/lock-vault-4-finish.png) note The auto-lock timeout specified in the settings will lock the vault if Cryptomator is in background. Furthermore if not changed in settings, the vault gets locked if the screen turns off. ## View and Edit File[​](#view-and-edit-file "Direct link to View and Edit File") Start the view and edit process by clicking on a file. Finish the editing or viewing using the back button of the device until you're back in Cryptomator. If the content has changed, the upload process starts. ![How to edit a file with Android](/img/android/edit-file.gif) ## Rename File or Folder[​](#rename-file-or-folder "Direct link to Rename File or Folder") To change the name of a specific file or folder in Cryptomator, you select the `V` ① next to the file or folder and choose *Rename* ②. ![How to rename a vault with Android](/img/android/rename-vault-0-start.png)![How to rename a vault with Android](/img/android/rename-vault-1-select-rename.png) Choose a new name and confirm using the `RENAME` button. ![How to rename a vault with Android](/img/android/rename-vault-3-renaming.png)![How to rename a vault with Android](/img/android/rename-vault-4-finish.png) ## Move File or Folder[​](#move-file-or-folder "Direct link to Move File or Folder") To move a file or a folder into another folder, you select the `V` next to the file or folder ① and choose *Move* ②. ![How to move a file or folder with Android](/img/android/move-file-0-start.png)![How to move a file or folder with Android](/img/android/move-file-1-select-move.png) Choose a new location by selecting a folder or by pressing the back button of your phone to navigate to the parent folder. ![How to move a file or folder with Android](/img/android/move-file-2-move-root.png)![How to move a file or folder with Android](/img/android/move-file-3-move-target.png) Confirm using the `MOVE` button. ![How to move a file or folder with Android](/img/android/move-file-3-moving.png)![How to move a file or folder with Android](/img/android/move-file-4-finish.png) While moving, you can use the ③ button to create a new folder in the current folder. ![How to move a file or folder with Android](/img/android/move-file-5-move-folder-hint.png) ## Delete File or Folder[​](#delete-file-or-folder "Direct link to Delete File or Folder") To delete a specific file or folder in Cryptomator, you select the `V` next to the file or folder ① and choose *Delete* ②. ![How delete a file or folder with Android](/img/android/delete-file-0-start.png)![How delete a file or folder with Android](/img/android/delete-file-1-select-delete.png) Confirm the deletion process using the `DELETE` button. ![How to delete a file or folder with Android](/img/android/delete-file-2-confirmation.png)![How to delete a file or folder with Android](/img/android/delete-file-3-deleting.png)![How to delete a file or folder with Android](/img/android/delete-file-4-finish.png) note By deleting a folder, all subfolders and files inside are deleted recursively. ## Export File or Folder[​](#export-file-or-folder "Direct link to Export File or Folder") To export a specific file or folder in Cryptomator, you select the `V` next to the file or folder ① and choose *Export* ②. ![How export a file or folder with Android](/img/android/export-file-0-start.png)![How export a file or folder with Android](/img/android/export-file-1-select-export.png) Choose the target location where the file or folder should be exported to. ![How to export a file or folder with Android](/img/android/export-file-2-choose-location.png)![How to export a file or folder with Android](/img/android/export-file-3-exporting.png)![How to export a file or folder with Android](/img/android/export-file-4-finish.png) ## Share File with Other App[​](#share-file-with-other-app "Direct link to Share File with Other App") To share a specific file or folder in Cryptomator with another app, you select the `V` next to the file or folder ① and choose Share ②. ![How share a file or folder with Android](/img/android/share-file-0-start.png)![How share a file or folder with Android](/img/android/share-file-1-select-share.png) Choose the target app in which you will use the file or folder. ![How to share a file or folder with Android](/img/android/share-file-2-select-app.png) tip By sharing a file or folder from Cryptomator with Cryptomator, you can copy content from one vault to another one. ## Share File with Cryptomator[​](#share-file-with-cryptomator "Direct link to Share File with Cryptomator") You can share files from another app with Cryptomator. We use as example the Files app from Android. You select the file(s) to share by long clicking on it ①. Press the share button ② to choose to share these file(s) and select *Cryptomator* ③. ![How share a file or folder with Android](/img/android/share-with-cm-0-start.png)![How share a file or folder with Android](/img/android/share-with-cm-1-choose-cm.png) Choose the vault ⑤ and optionally specify the target folder in the vault ④ (default is the root). ![How to share a file or folder with Android](/img/android/share-with-cm-2-select-vault.png) Then the encryption and upload starts. ![How to share a file or folder with Android](/img/android/share-with-cm-3-uploading.png)![How to share a file or folder with Android](/img/android/share-with-cm-4-finish.png) ## Search in Folder[​](#search-in-folder "Direct link to Search in Folder") Search for files or folders within the same folder using the magnifier ①. ![How to search in a vault with Android](/img/android/search-0-start.png) Now you can enter the pattern after which you want to search in this folder. ![How to search in a vault with Android](/img/android/search-1-searched.png) Using the `X` ② you can clear the pattern and after pressing it again, the filter mode is finished. ![How to search in a vault with Android](/img/android/search-2-finish.png) In the settings there are two options that influence the behavior of the search: * Live search (disabled by default) * Search using glob pattern matching (disabled by default) For more information, see the Settings chapter. ## Sort Folder by…[​](#sort-folder-by "Direct link to Sort Folder by…") ![How to sort the content of a folder with Android](/img/android/sort.gif) ## Fast Scroll[​](#fast-scroll "Direct link to Fast Scroll") ![How to scroll fast through the content of a folder with Android](/img/android/fast-scroll.gif) If the folder contents are sorted by file size, the preview will show the file sizes accordingly. The same applies to the modification date. --- # Cloud Management ![How to handle cloud services with Android](/img/android/setting-cloud-services.png) In "Cloud Services", you can create or edit the connection between the Cryptomator app and your storage provider accounts. Please enter the credentials for your provider account or in case of Google Drive choose your account. If your authentication was successful, some of the providers might ask you to grant Cryptomator access permission to your online files. Please allow this permission. In Google Drive, OneDrive and Dropbox you can only create one connection between your Cloud Service account and the Cryptomator app. You can't connect to (for example) two different *Dropbox* accounts. If the provider requested permission to access your online files you can remove Cryptomator permissions from your online storage account at any time. Please keep in mind that Cryptomator then cannot connect to your vault anymore. ## Login Dropbox[​](#login-dropbox "Direct link to Login Dropbox") ![How to handle cloud services with Android](/img/android/add-dropbox-login-provider-0.png)![How to handle cloud services with Android](/img/android/add-dropbox-login-provider-1.png) ## Login Google Drive[​](#login-google-drive "Direct link to Login Google Drive") ![How to handle cloud services with Android](/img/android/add-googledrive-login-provider.png) ## Login OneDrive[​](#login-onedrive "Direct link to Login OneDrive") ![How to handle cloud services with Android](/img/android/add-onedrive-login-provider-0.png)![How to handle cloud services with Android](/img/android/add-onedrive-login-provider-1.png) ## Login WebDAV[​](#login-webdav "Direct link to Login WebDAV") Please see [Cloud Services With WebDAV Support](/misc/supported-cloud-services/.md#cloud-services-with-webdav-support) for a non-exhaustive list of Cloud Services and information about accessing them with WebDAV. ![How to handle cloud services with Android](/img/android/add-webdav-login-provider-0.png)![How to handle cloud services with Android](/img/android/add-webdav-login-provider-1.png)![How to handle cloud services with Android](/img/android/add-webdav-login-provider-2.png) note While creating the WebDAV connection, please make sure to add the root of the accessible storage and don't navigate directly into the vault. ## Login S3[​](#login-s3 "Direct link to Login S3") Generate a key that has permissions "Allow List All Bucket Names". (AWS root users have this by default and [this permission may not be necessary in the future](https://github.com/cryptomator/android/issues/339).) "endpoint" refers to how the S3 API for your bucket can be reached. In the case of [official S3](https://docs.aws.amazon.com/general/latest/gr/s3.html), it would be `s3..amazonaws.com`, for e.g. [Backblaze B2](https://www.backblaze.com/apidocs/introduction-to-the-s3-compatible-api) `s3..backblazeb2.com`. ![Android S3 connection form](/img/android/add-s3-login-provider.png) ## Login Local Storage[​](#login-local-storage "Direct link to Login Local Storage") The following pictures describes how to setup a location to access vaults stored on the internal storage of the device (the same applies for vaults located e.g. on a SD card): ![How to handle cloud services with Android](/img/android/add-localstorage-login-provider-0.png)![How to handle cloud services with Android](/img/android/add-localstorage-login-provider-1.png)![How to handle cloud services with Android](/img/android/add-localstorage-login-provider-2.png)![How to handle cloud services with Android](/img/android/add-localstorage-login-provider-3.png)![How to handle cloud services with Android](/img/android/add-localstorage-login-provider-4.png) After creating the location, you can access it by clicking on the name of the location to add a vault or create a new vault. note If you use a custom location please make sure to add the root folder of the storage like described in the pictures and don't navigate directly into the vault. --- # Settings You can configure Cryptomator to your needs. This section provides an overview of the different settings. ## General Settings[​](#general-settings "Direct link to General Settings") After pressing the three dots ① and clicking on `Settings`, you will find options to customize Cryptomator. ![How to launch settings with Android](/img/android/launch-settings.png)![How to launch settings with Android](/img/android/settings.png) ### Cloud Services[​](#cloud-services "Direct link to Cloud Services") This setting lists all Cloud Services. When pressing on a service, the authentication starts or if you're already authenticated, you will be logged out. ![How to handle cloud services with Android](/img/android/setting-cloud-services.png) ### Fingerprint[​](#fingerprint "Direct link to Fingerprint") note This setting is only available if your device supports the fingerprint authentication. With the toggle button in the right upper corner ①, the fingerprint will be generally enabled/disabled. Using the toggle button next to the vault, it will be enabled/disabled for this vault ②. ![How to use fingerprint with Android](/img/android/setting-fingerprint-0-setup.png)![How to use fingerprint with Android](/img/android/setting-fingerprint-1-enter-pw.png) After enabling, you have to unlock the vault using the password. ![How to use fingerprint with Android](/img/android/setting-fingerprint-2-authenticate.png)![How to use fingerprint with Android](/img/android/setting-fingerprint-3-finish.png) To have access to the key stored in the keystore, you have to authenticate against the system using the fingerprint. ### Block App When Obscured[​](#block-app-when-obscured "Direct link to Block App When Obscured") Under certain circumstances, Cryptomator for Android may not respond to touches. This is most often caused by apps which apply a color filter to the device. Examples are the apps Twilight or Blue Light Filter. When disabling or uninstalling such apps, Cryptomator will work again. The reason for Cryptomator not working is that the user interface of Cryptomator is obscured. Whenever another app obscures Cryptomator, it could intercept the input done to Cryptomator or display a false UI tricking the user into doing stuff he does not want to do. For security reasons, Cryptomator is disabled by default when obscured. The Android documentation contains [some more details](https://developer.android.com/reference/android/view/View.html#Security). Starting from version 1.3.0, this protection can be disabled in the settings. We rather recommend to use the app without a blue light filter because this is more secure. If you want to disable protection, the blue light filter or any app obscuring Cryptomator has to be disabled one time. Afterwards, the settings can be opened and the option "Disable app when obscured" can be disabled. And then the relevant apps can be re-enabled again. To identify apps which could cause this, open the Android settings and navigate to **Settings - Apps - Advanced (gear icon) - Draw over other apps**. This will list the installed Apps and will show you which ones are allowed to draw over other apps. You can disable this for most apps (but not for system apps like the keyboard but this should not cause any problems). If you see this dialog, some app is able to draw over Cryptomator: ![How to enable obscured app with Android](/img/android/setting-app-obscured.png) ### Screen Security[​](#screen-security "Direct link to Screen Security") Android provides the possibility to prevent the system and other apps from doing screenshots, screen recordings etc. while Cryptomator is active. This feature is very important because it prevents other apps from reading data across the screen. This feature is enabled for all our views. For some devices, e.g. a Chromebook with a second display or to create a screenshot and disable it again, we made this option since the 1.3.9 configurable. Read more: [FLAG\*SECURE](https://developer.android.com/reference/android/view/Display.html#FLAG*SECURE) ### Style[​](#style "Direct link to Style") You can choose between the following three styles: * Automatic (follow system): Follows the system specified in the Android settings * Light: App shows in light mode * Dark: App shows in dark mode ![How to change style with Android](/img/android/settings.png)![How to change style with Android](/img/android/setting-style-dark.png) ## Search[​](#search "Direct link to Search") You can use the magnifier inside the cloud node list to search for specific nodes. Thereby there are two settings: * Live search (disabled by default) * Search using glob pattern matching (disabled by default) both are described in the following chapters. ### Live Search[​](#live-search "Direct link to Live Search") If this setting is enabled, the search mode is `live`. That means, the search starts immediately after entering the search pattern. ![How to use live search with Android](/img/android/search.gif) If it is disabled, you have to use the magnifier or the enter button in your keyboard to start the search. ### Search using glob pattern matching[​](#search-using-glob-pattern-matching "Direct link to Search using glob pattern matching") If this setting is enabled, you have to enter a glob pattern into the search bar. ![How to use live search with Android](/img/android/search-glob-pattern.gif) If it is disabled, the beginning of the cloud node names must match the entered text. Upper and lower case is not relevant in this option. ## Automatic Locking[​](#automatic-locking "Direct link to Automatic Locking") If a vault is unlocked and Cryptomator isn't active, the automatic locking timeout is counting down. After the timeout expires, all vaults get locked. You can choose between: * 1 minute * 2 minutes * 5 minutes * 10 minutes * Never `When screen is disabled` can be deactivated so that the vaults don't get locked when the screen locks. ## Automatic Photo Upload[​](#automatic-photo-upload "Direct link to Automatic Photo Upload") If the `Automatic photo upload` is enabled, all photos taken will be marked for upload and after the specified vault gets unlocked again, the upload starts. Under the setting `Choose vault for upload`, you can specify the target vault and folder in the vault where the images will be placed. Which pictures will be tracked, depends on the Android version on your phone: * Nougat (API level 24 or 7.x) and later: All images which Android adds to the gallery will be uploaded to the vault * Pre-Nougat: Only the images created with the camera will be uploaded to the vault ## Cache[​](#cache "Direct link to Cache") Introduced in version 1.5.0, if enabled, all downloaded files will be cached (encrypted) on the file system. Further downloads will only verify with the server, that the cached file is still the latest version. If so it will not be downloaded again but directly retrieved from the file system. The cache is implemented using a least recently used mechanism, that means, the oldest entry will be overwritten if the max cache size is reached. ### Cache Size Per Cloud[​](#cache-size-per-cloud "Direct link to Cache Size Per Cloud") Using this setting, you can specify the total max cache size per Cloud Service. You can choose between the following options: * 50 MB * 100 MB * 250 MB * 500 MB * 1 GB * 5 GB note The more memory is given to caching, the greater the convenience factor. However, this memory can be used up to the maximum on the system and is then no longer available. ### Clear Cache[​](#clear-cache "Direct link to Clear Cache") This setting will flush all cached files. ## Support[​](#support "Direct link to Support") If you have problems with the app you can enable the `Debug mode`. After reproducing the problem, you can disable the `Debug mode` again and `Send log file`. ## Advanced Settings[​](#advanced-settings "Direct link to Advanced Settings") ### Workaround Opening Microsoft Files[​](#workaround-opening-microsoft-files "Direct link to Workaround Opening Microsoft Files") With this setting enabled, files are opened in Microsoft applications with write permission. Due to a bug in Microsoft apps, the file to be edited must be shared with these apps in a public media folder on the device. After Cryptomator is resumed, the publicly accessible file is deleted again but Cryptomator cannot influence what has happened to this file in the meantime. Make sure that you are aware of this behavior when activating this option. This will only apply to Microsoft file types. ### Keep Unlocked[​](#keep-unlocked "Direct link to Keep Unlocked") With this setting enabled, all vaults remain unlocked when a file is opened by a third-party application, which can be useful in combination with the "Workaround Opening Microsoft Files". ### Accelerate Unlock[​](#accelerate-unlock "Direct link to Accelerate Unlock") Download files to unlock the vault in the background while prompted to enter the password or biometric authentication. Keep it activated unless unlocking the vault does not work. ## Version[​](#version "Direct link to Version") This setting displays the current version of this app. The following sub settings are only available, if you're using the APK-Store variant of Cryptomator and not the Google Play Store one. ### Update Check Interval[​](#update-check-interval "Direct link to Update Check Interval") Using the specified interval below, the app checks if the latest version is installed. You can choose between the following options: * Once a day * Once a week * Once a month * Never ### Check For Updates[​](#check-for-updates "Direct link to Check For Updates") This setting displays the timestamp of the latest update check. You can click on this setting to trigger a update check. --- # Setup You can get Cryptomator for Android on: * [Google Play Store](https://play.google.com/store/apps/details?id=org.cryptomator) * [APK Store](https://cryptomator.org/android/) * [Cryptomator F-Droid repository](https://static.cryptomator.org/android/fdroid/repo?fingerprint=F7C3EC3B0D588D3CB52983E9EB1A7421C93D4339A286398E71D7B651E8D8ECDD) * [Main F-Droid repository](https://f-droid.org/en/packages/org.cryptomator.lite) * [Accrescent](https://accrescent.app/app/org.cryptomator) No matter which variant of the app you choose: The key functionality of Cryptomator stays the same. The variants only differ in terms of the [supported Cloud Services](/misc/supported-cloud-services/.md), the way they are downloaded and the way a license is acquired. If you have access to the *Google Play Store* on your device, **we recommend using the [Google Play Store variant](#google-play-store) of Cryptomator.** Otherwise, please keep reading. ## Differences Between Variants and How to Choose[​](#differences-between-variants-and-how-to-choose "Direct link to Differences Between Variants and How to Choose") While all variants of the Cryptomator for Android app have the same key functionality, you should make sure to pick the perfect variant for you: Most users will want to use the [Google Play Store](#google-play-store) or the [APK Store](#apk-store) as installation type. Both variants have access to all [supported Cloud Services](/misc/supported-cloud-services/.md) and allow for maximum flexibility. While the *Google Play Store variant* can be purchased and downloaded via its *Google Play Store* page, the *APK Store variant* and the accompanying license must be obtained via our website. The [Cryptomator F-Droid repo variant](#cryptomator-f-droid-repository) and [Main F-Droid repo variant](#main-f-droid-repository) both **don't** support Google Drive as Cloud Service because Google Drive requires proprietary dependencies which doesn’t fit the spirit of F-Droid. Additionally the *Main F-Droid repo variant* **doesn’t** support **any** Cloud Services that require an API key. Both can be downloaded from their corresponding F-Droid repository and require a license which can be obtained via [our website](https://cryptomator.org/android/). The *APK Store*, *F-Droid variants* and *Accrescent* of Cryptomator were created to serve users who do not have the *Google Play Store* installed on their Android device or do not want their purchases to go through Google. tip If you have access to the *Google Play Store* on your device, **we recommend using the [Google Play Store variant](#google-play-store) of Cryptomator** for the best user experience and maximum flexibility. To learn more about the supported Cloud Services, please see [Supported Cloud Services](/misc/supported-cloud-services/.md). ## Google Play Store[​](#google-play-store "Direct link to Google Play Store") note You can buy and download the *Google Play Store variant* of Cryptomator here: [Google Play Store](https://play.google.com/store/apps/details?id=org.cryptomator\&hl=en) If you have installed Cryptomator via the *Google Play Store,* you will receive updates as usual via the *Google Play Store.* After buying the app using the *Google Play Store,* it can be used with any number of devices that you have linked to the google account from your purchase. Furthermore it supports the "Google Play Family Library" function which means that the app can be used by up to 5 people in a family without having to buy it again. The conditions and how to create a “Google Play Family” can be found here: [Google Play Family Library](https://support.google.com/googleplay/answer/7007852?hl=en) Sometimes the *Google Play Store* has problems to recognize that the app was already bought and asks you to buy again the app, see this topic to recover from this problem: [On how many devices can the app be installed using Google Play Store?](https://community.cryptomator.org/t/on-how-many-devices-can-the-app-be-installed-using-google-play-store/6129) ## APK Store[​](#apk-store "Direct link to APK Store") note You can buy a license for the app and download the *APK Store variant* of Cryptomator here: [APK Store](https://cryptomator.org/android/) The *APK store variant* can be installed from the [APK Store](https://cryptomator.org/android/) on our website. Please verify the `SHA256 Signature` after downloading the APK before installing. The download is a so-called `APK` (Android application package), which is an installation archive. Install the app by simply clicking on the APK. It is possible that the app in which you clicked on the APK is asking for "Install from Unknown Sources" permission, this is normal and must be activated for a short time (it is recommended to remove the permission afterwards). This variant does include an automatic updater that periodically checks if there is a newer version of this app, and if so, it can be downloaded and installed directly from within the app. Using the [Update Check Interval](/android/settings/.md#update-check-interval) in the Cryptomator settings, you can specify how often the update check is executed. As this variant is not bought using the *Google Play Store* you need to buy a license key from the [APK Store](https://cryptomator.org/android/) on our website. After Cryptomator is installed, you have to enter this key. This can be done by copying and pasting the license into the field when asked for it or by clicking on the link starting with `cryptomator://license/YOUR_LICENSE_KEY`. ## Cryptomator F-Droid Repository[​](#cryptomator-f-droid-repository "Direct link to Cryptomator F-Droid Repository") note You can buy a license for the *Cryptomator F-Droid repository variant* of Cryptomator here: [APK Store](https://cryptomator.org/android/) note You can download the *Cryptomator F-Droid repository variant* of Cryptomator from F-Droid after adding our F-Droid repository to the F-Droid app by opening this link on the device or by scanning the following QR-Code: [Cryptomator F-Droid repository](https://static.cryptomator.org/android/fdroid/repo?fingerprint=F7C3EC3B0D588D3CB52983E9EB1A7421C93D4339A286398E71D7B651E8D8ECDD) ![F-Droid QR Code](/img/android/fdroid-qr-code.svg) As with the *APK Store variant,* since this app variant is not purchased via the *Google Play Store,* you need to buy a license key from the [APK Store](https://cryptomator.org/android/) on our website. After Cryptomator is installed, you have to enter this key. This can be done by copying and pasting the license into the field when asked for it or by clicking on the link starting with `cryptomator://license/YOUR_LICENSE_KEY`. ## Main F-Droid Repository[​](#main-f-droid-repository "Direct link to Main F-Droid Repository") note You can buy a license for the *Main F-Droid repository variant* of Cryptomator here: [APK Store](https://cryptomator.org/android/) note You can download the *Main F-Droid repository variant* of Cryptomator here: [Main F-Droid repository](https://f-droid.org/en/packages/org.cryptomator.lite) The *Main F-Droid repository variant* can be installed directly from the [Main F-Droid repository](https://f-droid.org/en/packages/org.cryptomator.lite). Regarding the license key, the same applies as with the [Cryptomator F-Droid repository variant](#cryptomator-f-droid-repository). Unlike all other variants of Cryptomator for Android, this variant has its own package name: `org.cryptomator.lite`. It means that you cannot, intentionally or unintentionally, simply switch between this and the other variants. It requires to setup the app again. The reason we decided to do this is that other Cryptomator variants already exist in some popular F-Droid repositories, and if we hadn’t decided to do this, there could have been an unwanted variant switch. ## Accrescent[​](#accrescent "Direct link to Accrescent") note You can buy a license for the *Accrescent* variant of Cryptomator here: [APK Store](https://cryptomator.org/android/) note You can download the *Accrescent* variant of Cryptomator here: [Accrescent](https://accrescent.app/app/org.cryptomator) As this variant is not bought using the *Google Play Store* you need to buy a license key from the [APK Store](https://cryptomator.org/android/) on our website. After Cryptomator is installed, you have to enter this key. This can be done by copying and pasting the license into the field when asked for it or by clicking on the link starting with `cryptomator://license/YOUR_LICENSE_KEY`. ## Requirements[​](#requirements "Direct link to Requirements") Requires Android 8.0 or later. ## Update Rollout[​](#update-rollout "Direct link to Update Rollout") The timing of the update depends on your installed variant: * *Google Play Store:* Updates are reviewed by Google, so it may take a few days before the update is available. * *APK Store:* Updates are available as they are released. * *Cryptomator F-Droid Repo:* Updates are available as they are released. * *Main F-Droid Repo:* Updates are available as soon as the F-Droid maintainers have built the application, which can take a few days. * *Accrescent:* Updates are reviewed by the Accrescent team, updates are available as soon as the review is complete. --- # Vault Management A *vault* is where your files are stored encrypted on your Android device or cloud storage. When you create or access a vault through Cryptomator for Android, your files are automatically encrypted and decrypted in real-time. Only Cryptomator can decrypt the vault's contents when you unlock it using your password. Cryptomator for Android supports various storage locations including local device storage, Dropbox, Google Drive, OneDrive, and any cloud service that offers WebDAV access. This allows you to securely access your encrypted files from anywhere while maintaining full control over your data. ## Create a New Vault[​](#create-a-new-vault "Direct link to Create a New Vault") To create a new vault, click on the plus sign ① and choose *Create new vault* ② in the next screen. ![How to create a new vault with Android](/img/android/create-new-vault-0-start.png)![How to create a new vault with Android](/img/android/create-new-vault-1-select-new-existing.png) note If you already have a vault created with the desktop app and just want to add this vault to your mobile app, please go to chapter [Add Existing Vaults](#add-existing-vaults). You will now be prompted to select the Cloud Service where you want to store your vault. Choose between *Dropbox*, *Google Drive*, *OneDrive* (works also with *OneDrive for Business*) or *Local storage* (which means your local device with all attached devices). If your desired provider is not listed and offers WebDAV access, please select *WebDAV* as the storage location of your vault. Please see [Cloud Services With WebDAV Support](/misc/supported-cloud-services/.md#cloud-services-with-webdav-support) for a non-exhaustive list of Cloud Services and information about accessing them with WebDAV. ![How to create a new vault with Android](/img/android/create-new-vault-2-select-provider.png) If not already done, you have to create the connection between the Cryptomator app and your storage provider account. Please follow the instructions in the [Cloud Management](/android/cloud-management/.md) chapter and continue later here. Now that you've established a connection, you'll add the existing vault. In the first step, please enter a name for your new vault. This name will also be the folder name of your vault files in your online storage. ![How to create a new vault with Android](/img/android/create-new-vault-5-name-vault.png) Then choose the location on your Cloud Service where you want to have your encrypted vault files stored. ![How to create a new vault with Android](/img/android/create-new-vault-6-select-path.png) And last but not least, create a **secure** password for your vault. Basically, you have the whole Unicode for choosing a password including non-printable characters. ![How to create a new vault with Android](/img/android/create-new-vault-7-set-password.png) warning You have to remember this password at all times because there is **no way to access your data if you forget your password**. Choose a [good password](/security/best-practices/.md#good-passwords) to make your data secure. After you have confirmed your password, the vault is created. You will find it now on the start page of your Cryptomator app, where you can open your vault and optionally change settings. ![How to create a new vault with Android](/img/android/create-new-vault-8-creating-vault.png)![How to create a new vault with Android](/img/android/create-new-vault-9-finish.png) ## Add Existing Vaults[​](#add-existing-vaults "Direct link to Add Existing Vaults") To add an existing vault, click on the plus sign ① and choose *Add existing vault* ② in the next screen. ![How to add a vault with Android](/img/android/add-existing-vault-0-start.png)![How to add a vault with Android](/img/android/add-existing-vault-1-select-add-existing-vault.png) You will now be prompted to select the Cloud Service where the vault is located. Choose between *Dropbox*, *Google Drive*, *OneDrive* (works also with *OneDrive for Business*) or *Local storage* (which means your local device with all attached devices). If your desired provider is not listed and offers WebDAV access, please select *WebDAV* as the storage location of your vault. Please see [Cloud Services With WebDAV Support](/misc/supported-cloud-services/.md#cloud-services-with-webdav-support) for a non-exhaustive list of Cloud Services and information about accessing them with WebDAV. ![How to add a vault with Android](/img/android/add-existing-vault-2-select-provider.png) If not already done, you have to create the connection between the Cryptomator app and your storage provider account. Please follow the instructions in the [Cloud Management](/android/cloud-management/.md) chapter and continue later here. Now that you've established a connection, you'll add the existing vault. In the first step, please choose the folder in which the vault is located. This folder name is the same as the vault name (in this example, our vault name is *test vault* so we select this folder). ![How to add a vault with Android](/img/android/add-existing-vault-5-choose-folder.png) Then choose the `masterkey.cryptomator` file. ![How to add a vault with Android](/img/android/add-existing-vault-6-choose-file.png) Now the vault is added to the list of vaults. You will find it now on the start page of your Cryptomator app, where you can open your vault and optionally change settings. ![How to add a vault with Android](/img/android/add-existing-vault-8-finish.png) ## Remove Vaults[​](#remove-vaults "Direct link to Remove Vaults") If you want a specific vault to stop being displayed in Cryptomator, you select the `V` next to the vault ① and choose *Remove* ②. ![How remove a vault with Android](/img/android/remove-vault-0-start.png)![How remove a vault with Android](/img/android/remove-vault-1-select-remove-vault.png) Confirm the deletion process using the `Delete` button. ![How remove a vault with Android](/img/android/remove-vault-2-confirmation.png)![How remove a vault with Android](/img/android/remove-vault-3-finish.png) note By removing a vault, it is only removed from the list but not deleted in the cloud. You can re-add the vault afterwards. ## Change Vault Password[​](#change-vault-password "Direct link to Change Vault Password") If you want change the password of a specific vault in Cryptomator, you select the `V` next to the vault ① and choose *Change password* ②. ![How to change a vault password with Android](/img/android/change-password-vault-0-start.png)![How to change a vault password with Android](/img/android/change-password-vault-1-select-change-pw.png) Enter the old password and choose a **secure** new one. Basically, you have the whole Unicode for choosing a password including non-printable characters. ![How to change a vault password with Android](/img/android/change-password-vault-2-change-password.png) warning You have to remember this password at all times because there is **no way to access your data if you forget your password**. Choose a [good password](/security/best-practices/.md#good-passwords) to make your data secure. Start the process using the `CHANGE PASSWORD` button. ![How to change a vault password with Android](/img/android/change-password-vault-3-changing-pw.png)![How to change a vault password with Android](/img/android/change-password-vault-4-finish.png) info The password is used to derive a [KEK](https://en.wikipedia.org/wiki/Glossary_of_cryptographic_keys), which is then used to encrypt futher keys. The KEK changes, but the keys encrypted with the KEK will stay the same. The actual files will not get re-encrypted, meaning you can not upgrade a weak passphrase to a stronger one once the data has been synced to a service that allows recovery of older versions of the masterkey file. If you like to encrypt your vault files with a new, stronger password, you need to create a new vault and copy the data from the old to the new one. Make sure to wipe all backups of the old vault afterwards. ## Rename Vault[​](#rename-vault "Direct link to Rename Vault") If you want to change the name of a specific vault in Cryptomator, you select the `V` next to the vault ① and choose *Rename* ②. ![How to rename a vault with Android](/img/android/rename-vault-0-start.png)![How to rename a vault with Android](/img/android/rename-vault-1-select-rename.png) Choose a new name and confirm using the `RENAME` button. ![How to rename a vault with Android](/img/android/rename-vault-3-renaming.png)![How to rename a vault with Android](/img/android/rename-vault-4-finish.png) ## Change Vault Position[​](#change-vault-position "Direct link to Change Vault Position") If you want to change the position of a specific vault in the vault list in Cryptomator, long-press on the vault and drag it to the desired position in the pressed state: ![How to change position of a vault with Android](/img/android/change-vault-position.gif) --- # Accessing Vaults You can only access decrypted files of a vault if you can unlock it. Unlocking a vault is just a two-step process as long as you know the password. ![Cryptomator window showing a locked vault](/img/desktop/vault-detail-locked.png) ## Unlocking a Vault[​](#unlocking-a-vault "Direct link to Unlocking a Vault") 1. Select the vault you wish to unlock in the vault list. 2. Click on the large `Unlock` button in the vault detail view of the Cryptomator window. 3. Enter your vault's password. 4. Click the `Unlock` button. ![Vault unlock dialog](/img/desktop/unlock-prompt.png) note You can store the password in your operating system's keychain by checking the "Remember password" checkbox. With a saved password, you can unlock your vaults without typing a password on every unlock. For more information, see the [Storing Passwords](/desktop/password-and-recovery-key/.md#storing-passwords) section. warning Only store your password in the system's keychain on trusted devices. Anyone with access to these devices will be able to unlock your vault, and in some cases, even read your stored password. If your password is correct, a success message will be displayed, and the vault will be unlocked. You can close the success window by clicking `Done`, or click `Reveal Vault` to show the unlocked vault in your file manager. ![Vault unlock success dialog](/img/desktop/unlock-success.png) ## Locking a Vault[​](#locking-a-vault "Direct link to Locking a Vault") To lock a vault, simply click `Lock` and the virtual drive will disappear or render empty. Your files remain encrypted at the vault's location. ## Manage Files and Folders in Your Vault[​](#manage-files-and-folders-in-your-vault "Direct link to Manage Files and Folders in Your Vault") By default, a vault's content will be accessible via an attached virtual drive on your PC. So, you can manage files and folders in your unlocked vault just like you do on any other hard drive or USB drive. Alternatively, a vault's content can be accessed via a directory or a WebDAV server by changing its [volume type](/desktop/volume-type/.md). Click on `Reveal Drive` in the Cryptomator window to open the mount location using the default file manager (Windows Explorer, Finder, …). note Even though your files are shown unencrypted in the virtual drive, they are not stored unencrypted on the hard drive but only in [volatile memory](https://en.wikipedia.org/wiki/Volatile_memory). ![Cryptomator window showing an unlocked vault](/img/desktop/vault-detail-unlocked-simple.png) note On Windows, you can choose the drive letter of the virtual drive for each vault using advanced vault options. ## Locate Encrypted File[​](#locate-encrypted-file "Direct link to Locate Encrypted File") See [Locate Encrypted File](/desktop/encrypted-file-names/.md#locate-encrypted-file) in the Encrypted File Names section. ## File System Case Sensitivity[​](#file-system-case-sensitivity "Direct link to File System Case Sensitivity") warning Cryptomator virtual drives are always case-sensitive. This means `Document.txt` and `document.txt` are treated as two different files, regardless of your operating system. This behavior is required for Cryptomator's deterministic [filename encryption](/security/vault/.md#filename-encryption) to work correctly across all platforms. While Linux users are accustomed to case-sensitive file systems, this can cause unexpected behavior on Windows and macOS where the default file systems are case-insensitive. On Windows and macOS, this difference means: 1. Attempting to open `Test.dat` when the file is named `test.dat` will result in a "file not found" error 2. You can create both `README.md` and `readme.md` in the same directory, which would normally conflict 3. Some applications may fail when they expect case-insensitive file access Our recommendation is to avoid creating files with names that differ only in case. Make sure to test applications like backup tools or any other software that will access files in your vault to ensure they handle case-sensitive file systems correctly. --- # Adding Vaults You will be presented with three options when adding a vault: 1. [`Create New Vault…`](#create-a-new-vault) - Choose this if you wish to create a new vault. 2. [`Open Existing Vault…`](#open-an-existing-vault) - Choose this if you already have a vault and wish to open it. 3. [`Recover Existing Vault…`](/desktop/vault-recovery/.md#add-recover-vault) - Choose this if you have a vault with missing configuration files that hasn’t yet been added and you want to restore it. ![Create a new or open an existing vault](/img/desktop/create-or-open-vault.png) ## Create a New Vault[​](#create-a-new-vault "Direct link to Create a New Vault") If you chose to create a new vault, the wizard will guide you through a simple 6-step vault creation process. ### 1. Choose a Name[​](#choose-a-name "Direct link to 1. Choose a Name") Start by choosing a name for your vault. ![Choosing "My first Vault" as a vault name](/img/desktop/add-vault-1.png) ### 2. Choose a Storage Location[​](#choose-a-storage-location "Direct link to 2. Choose a Storage Location") Next, you need to choose a directory on your PC where your vault's encrypted data will be stored. If you wish to sync the encrypted data to your cloud storage, then choose a cloud-synced directory. Cryptomator is not a sync tool. You need to install the sync software of your cloud storage provider to sync your encrypted data. note Cryptomator tries to detect locations of well-known cloud sync software (see screenshot below). The screenshot below shows multiple cloud storage locations, because we have multiple sync software installed on our device. You might not see the same options, depending on which cloud services are installed on your PC, but you can always choose `Custom Location` and navigate to your cloud-synced directory manually. ![Choosing Dropbox as a storage location for my vault](/img/desktop/add-vault-2.png) ### 3. Expert Settings[​](#expert-settings "Direct link to 3. Expert Settings") The **Expert Settings** screen provides advanced configuration options for your vault. These settings are intended for users who require greater control over how their data is encrypted and stored. note Expert Settings are optional and should only be adjusted if you understand their implications. **Enable Expert Settings** To access expert settings, toggle the **Enable Expert Settings** switch. Once enabled, additional configuration options will be available. **Maximum Length of Encrypted File Names** One of the primary expert settings allows you to configure the maximum length of encrypted file names. This setting controls the degree of *name shortening* applied to file names during encryption, which is critical for compatibility with filesystems that have strict length limits. * **Default Behavior**: Cryptomator automatically shortens file names to comply with filesystem constraints. * **Custom Configuration**: If specific requirements must be met, you can manually set the maximum allowed length for encrypted file names. Refer to [Name Shortening](/security/vault/.md#name-shortening) for additional details. ![Expert settings](/img/desktop/add-vault-3.png) warning Adjusting the maximum length of encrypted file names may affect compatibility with certain filesystems. Ensure you thoroughly test these settings before enabling them for critical data. ### 4. Choose a Password[​](#choose-a-password "Direct link to 4. Choose a Password") Now it is time to choose a [strong password](/security/best-practices/.md#good-passwords) for your vault. Cryptomator requires at least 8 characters, but we recommend you to use longer phrases such as pass-sentences. The bar below the password field will help you estimate the strength of your password. tip Always choose a password that's unique across your vaults and accounts. This is especially important if you plan to share a vault with someone. Additionally, we recommend sharing passwords only over a secure channel, like PGP encypted emails, or end-to-end encrypted chat apps. info Be mindful of your keyboard layout when creating passwords. Special characters and dead keys can behave differently across keyboard layouts (e.g., Dutch vs. English). This may cause password entry issues if you switch keyboard layouts later. For more information, see [Keyboard Layouts and Special Characters](/security/best-practices/.md#keyboard-layouts-and-special-characters). ![Choose a strong password for your Cryptomator vault](/img/desktop/add-vault-4.png) warning Nobody except you knows this password, and we also cannot "reset" it for you. Without a valid password, your files can't be decrypted and will become inaccessible. So, store your password in a secure password manager or just don't forget it. However, you can reset a vault's password by yourself if you have its *recovery key*. ### 5. Show Recovery Key (Optional Step)[​](#show-recovery-key "Direct link to 5. Show Recovery Key (Optional Step)") A recovery key allows you to reset your password if you ever forget it. If you chose to create a recovery key in the previous step, it will now be displayed. Make sure not to lose it and ideally make a hard copy of it. ![Showing the recovery key](/img/desktop/add-vault-5.png) warning Remember, a recovery key is just like your password, its purpose is to gain access to your vault! Keep it as safe as your password. For more details, take a look at [how a recovery key works](/desktop/password-and-recovery-key/.md#reset-password). ### 6. Done[​](#done "Direct link to 6. Done") That's it. You have successfully created a new vault. You can now unlock this vault using your password and start adding files into it. ![Showing the recovery key](/img/desktop/add-vault-6.png) ## Open an Existing Vault[​](#open-an-existing-vault "Direct link to Open an Existing Vault") To open an existing vault, you need to locate the `masterkey.cryptomator` file of the vault you wish to open. note If you created the vault on another device and cannot find it or its masterkey file, make sure that the directory containing the vault is properly synchronized and fully accessible on your device. --- # Admin Configuration The admin configuration allows device or system administrators to define environment properties for Cryptomator so it runs in the desired context for all users on a device. It is a system-level key-value file that persists across updates. ## Location of the Admin Configuration[​](#location-of-admin-configuration "Direct link to Location of the Admin Configuration") note Editing the *admin configuration* may require elevated privileges (i.e. admin or root permissions). The storage location of the admin configuration file `config.properties` depends on the OS. The following table shows the storage path for each OS: | OS | Default Path | | ------- | ------------------------------------------------------------ | | Windows | `C:\ProgramData\Cryptomator\config.properties` | | macOS | `/Library/Application Support/Cryptomator/config.properties` | | Linux | `/etc/cryptomator/config.properties` | ## Editing the Admin Configuration[​](#editing-the-admin-configuration "Direct link to Editing the Admin Configuration") The admin configuration is a simple, UTF-8 encoded key-value file. Entries are of the form `property-key=property-value`. info Backward slashes `\` in property values must be escaped with another `\`. For example, setting a value of `C:\Logs\Cryptomator` has to be entered as `C:\\Logs\\Cryptomator`. **Example:** To allow loading of external plugins, you have to set `cryptomator.pluginDir` to a directory of your choice. If you want to set it to `~/cryptomator/plugins`, the line in the admin file looks like this: ``` cryptomator.pluginDir=@{userhome}/cryptomator/plugins ``` warning After creating/editing the file, ensure correct file access permissions! We recommend read access for all users, **write access only for system/device admins**. ## Configurable Properties[​](#configurable-properties "Direct link to Configurable Properties") The following property keys are supported. | Property Key | Description | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cryptomator.logDir=[DirPath]` | The directory where Cryptomator stores its log files (e.g. application log, migration log). | | `cryptomator.pluginDir=[DirPath]` | The directory where Cryptomator discovers plugins. | | `cryptomator.p12Path=[FilePath]` | The path to the device key. | | `cryptomator.mountPointsDir=[DirPath]` | The directory where Cryptomator mounts vaults if no per-vault location has been set. | | `cryptomator.disableUpdateCheck=[Boolean]` | Whether to disable automatic update checks (`true`) or allow them (`false`). Defaults to false. | | `cryptomator.hub.allowedHosts=[UrlList]` | List of hosts that Cryptomator is allowed to connect to during Hub unlock. List entries are comma separated and each host url consists of `scheme:host:port` (`port` is optional). For example `https://hub1.example.com,https://hub2.example.com:4432` | | `cryptomator.hub.enableTrustOnFirstUse=[Boolean]` | Whether Cryptomator shall ask the user to trust unknown Hub hosts (`true`) or disallow connection attempts (`false`). A Hub host is considered unknown unless it is well-known (`*.cryptomator.cloud`), listed in `cryptomator.hub.allowedHosts`, or has already been allowed by the user. Defaults to true | ## Substitutions[​](#substitutions "Direct link to Substitutions") Substitutions are used to dynamically resolve the content of some properties depending on the environment Cryptomator is started in, e.g. by inserting the path to the user's home folder. They may **only** be used in properties that start with `cryptomator.` (mind the dot) like `cryptomator.logDir`. All occurrences of the following substitution keys – in supported properties – are replaced by their respective variable values: | Substitution Key | Variable Value | | ----------------- | --------------------------------------- | | `@{appdir}` | The application installation directory. | | `@{appdata}` | `%APPDATA%` (Windows only). | | `@{localappdata}` | `%LOCALAPPDATA%` (Windows only). | | `@{userhome}` | The user's home directory. | Unknown substitution keys remain unchanged; a key without a value is replaced with an empty string. --- # Common Errors This page collects errors users frequently run into and their known solutions. For general diagnostic steps such as collecting log files or enabling debug mode, see [Troubleshooting](/desktop/troubleshooting/.md). ## Vault Appears Read-Only on Windows[​](#read-only-vault-windows "Direct link to Vault Appears Read-Only on Windows") **Symptoms:** On Windows with a [WinFsp](/desktop/volume-type/.md#winfsp) volume type, an unlocked vault behaves as if it were read-only. Copying or pasting files fails with "Permission denied", and new files or folders cannot be created or modified inside the vault. **Cause:** This occurs on Windows systems where multiple Active Directory or Microsoft Entra accounts are signed in simultaneously. WinFsp cannot map the current Windows user to the owner of the mounted vault, so the operating system rejects all write operations. See [winfsp/winfsp#387](https://github.com/winfsp/winfsp/issues/387#issuecomment-1130260210) for technical background. **Solution:** 1. Update Cryptomator to the [latest version](https://cryptomator.org/downloads/) 2. In `Preferences` → `Virtual Drive`, make sure `WinFsp (Local Drive)` is selected. In the affected vault's `Vault Options` → `Mounting`, set the volume type to `default`. 3. If the problem persists, apply custom mount options: 1. Run the following in Windows PowerShell to determine your domain and user name: ``` "$env:USERDOMAIN+$env:USERNAME".ToUpper() ``` The output has the form `DOMAIN+USERNAME` (e.g., `MYCOMPANY+JDOE`). 2. Lock the vault, open `Vault Options` → `Mounting`, enable custom mount options, and enter the following, replacing `DOMAIN+USERNAME` with the value from the previous step: ``` -ouid=1005 -ogid=1005 -ouidmap=1005:DOMAIN+USERNAME ``` 3. Unlock the vault. It should now be writable. The mount options must be configured per vault, so repeat this step for every affected vault. --- # Encrypted File Names info 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. 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. ![Vault detail view in the unlocked state](/img/desktop/encrypted-file-names-vault-detail-unlocked.png) ## Locate Encrypted File[​](#locate-encrypted-file "Direct link to 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 "Direct link to 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. ![Decrypt file names window](/img/desktop/decrypt-file-names.png) 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[​](#technical-example "Direct link to Technical Example") If you have a directory structure inside your vault like this: ``` . ├─ myProject.pptx ├─ Images for Project │ └─ ImageOfBees.jpg └─ ... ``` The actual directory structure of the vault on your hard drive/cloud will look like this: ``` . ├─ d │ ├─ BZ │ │ └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA │ │ ├─ dirId.c9r # internal vault file │ │ ├─ 5TyvCyF255sRtfrIv**83ucADQ==.c9r # myProject.pptx │ │ └─ FHTa55bH*sUfVDbEb0gTL9hZ8nho.c9r # Linking entry for directory "Images for Project" │ │ └─ dir.c9r # contains information for the link │ └─ FC │ └─ ZKZRLZUODUUYTYA4457CSBPZXB5A77 # content of the directory "Images for Project" │ └─ 4lmrQYfE_5ETusEkVJlTJrcFzjwxNBymig==.c9r # ImageOfBees.jpg ├─ masterkey.cryptomator ├─ masterkey.cryptomator.DFD9B248.bkup └─ vault.cryptomator ``` 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](/security/vault/.md). ## Video Walkthrough[​](#video-walkthrough "Direct link to Video Walkthrough") 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. Your browser does not support the video tag. --- # Error Handling If you encounter an unexpected error, Cryptomator gives you the option to look up a solution in our error database. It's possible that the error has already been reported and a solution has been suggested for you to follow. Simply click the `Look up Solution` button. ![Error dialog with options to dismiss or look up solution](/img/desktop/error-dialog-1.png) We will cross-reference your current error with the database and provide a solution link if one is available. ![Error dialog with look up the solution link to matching error](/img/desktop/error-dialog-2.png) If no results are found, you have the option to initiate your own search by selecting `Look up this error`, or create a ticket by selecting `Report this error`. ![Error dialog with options to look up or report the error](/img/desktop/error-dialog-3.png) Your privacy is important to us. We assure you that all requests are handled with your explicit consent and are directed exclusively to our server. This feature operates solely on an opt-in basis to protect your privacy. For further information, please visit our [privacy policy](https://cryptomator.org/privacy/#812-cross-reference-with-error-database). --- # Files in Use info This feature is only available for [Cryptomator Hub](/hub/introduction/.md) vaults. When multiple people work in a shared vault, two users might try to edit the same file at the same time. The **Files in Use** feature helps prevent accidental overwrites in this situation. ## When This Feature Applies[​](#when-this-feature-applies "Direct link to When This Feature Applies") You can run into concurrent edits when a vault is shared across multiple devices or the vault is accessed over a network share. If another user is currently editing a file, Cryptomator can block opening that file for writing on your side. note The app tracks who's using each file by storing usage information in small files. Depending on your setup, it might take a short time (\~10 seconds) until such an info file is synced to other devices. ## What You Will See[​](#what-you-will-see "Direct link to What You Will See") In your sync client/on the server you will see files with a `.c9u` file extension. Each `.c9u`-file contains the usage information for a single encrypted file. If a file is currently in use by someone else, Cryptomator shows a notification in the app. This means another device or user has an active edit session for that file. ![Cryptomator notification for a file currently in use](/img/desktop/files-in-use-notification.png) ## What You Can Do[​](#what-you-can-do "Direct link to What You Can Do") In most cases, the best action is to wait until the other person finishes editing and then try again. You can also choose to ignore the use status and continue. Use this only if you are sure it is safe, because forcing access can overwrite someone else's newer changes. We recommend the following sequence when receiving a "File is in use" notification: 1. Ask the person shown in the notification whether they are still editing the file. 2. If they already closed the file but it is still shown as "in use", use "Ignore Use Status". 3. Only open a file marked as in use without checking with teammates in exceptional situations. 4. In that case, create a backup copy first to avoid losing edits. ## Stale Use Status[​](#stale-use-status "Direct link to Stale Use Status") The use status is cleared after some time without file updates (around 10 min). If this happens, access is possible again. This helps in cases such as device sleep, crashes, or interrupted sessions. ## Related Topics[​](#related-topics "Direct link to Related Topics") * [Synchronization Conflicts](/desktop/sync-conflicts/.md) --- # Getting Started You will be greeted with the following screen when you start Cryptomator for the first time. You can create new vaults (or add existing ones) using the [`+`](/desktop/adding-vaults/.md) button located at the lower left corner. ![Empty vault list](/img/desktop/empty-vault-list.png) --- # Network Settings In general, Cryptomator does not require a network connection to function. If the network connection is present, it is used for optional features, i.e. update checks and searching the error database for solutions. The only exception is when unlocking [Cryptomator Hub](/hub/introduction/.md) vaults, then a network connection to the hub server is required. All network connections to the internet are using HTTPS with at least TLS 1.2. ## Trust Certificate Management[​](#trust-certificate-management "Direct link to Trust Certificate Management") Depending on the OS, the required trusted root certificates are loaded from different locations. | OS | Trust Store | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Linux | PKCS#12 file `/etc/cryptomator/certs.p12`; If the file does not exist, the JDK default trust store is used. [1](#user-content-fn-1) | | macOS | System keychain | | Windows | Certificate store "Trusted Root Certification Authorities", with registry path `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates\ROOT\`. Additionally, the JDK default trust store is used. [1](#user-content-fn-1) | ## Proxy Server[​](#proxy-server "Direct link to Proxy Server") The default proxy server differs depending on the operating system: | OS | Default Proxy Setting | | ------- | --------------------- | | Linux | No proxy | | macOS | Use system proxy | | Windows | Use system proxy | To change the proxy server, you need to edit `Cryptomator.cfg` located in the installation/app directory. Open the file in a text editor, search for the line: ``` java-options=-Djava.net.useSystemProxies=true ``` and *if it exists*, replace `true` with `false`. In the second step, add the following lines to the end of the file: ``` java-options=-Dhttp.proxyHost=[1] java-options=-Dhttp.proxyPort=[2] java-options=-Dhttps.proxyHost=[1] java-options=-Dhttps.proxyPort=[2] java-options=-Dhttp.nonProxyHosts=localhost|127.0.0.1|cryptomator-vault|[3] ``` and replace `[1]` with the host address of the proxy server, `[2]` with the port used on the proxy server and `[3]` with the list of host addresses, which should not use the proxy server, separated by '|'. ## Footnotes[​](#footnote-label "Direct link to Footnotes") 1. For more information about the location and contained certificates, see [JEP 319](https://openjdk.org/jeps/319). [↩](#user-content-fnref-1) [↩2](#user-content-fnref-1-2) --- # Password and Recovery Key This section explains how to change a password for a vault, show its recovery key, and reset a password. But, before that, let's understand how Cryptomator encrypts a vault using a password and what a recovery key is. The security of your vault is only as good as its password because Cryptomator encrypts your vault using a key derived from your password. So, [choosing a strong password](/security/best-practices/.md#good-passwords) is very important. Additionally, a unique *recovery key* can be derived for each vault while creating its password or later. A *recovery key* allows you to create a new password if you forget the original one. Do note that the *recovery key* feature does not break encryption in any way. It is a human-readable form of your decrypted [masterkey](/security/architecture/.md#masterkey) and therefore independent of the current vault password and highly confidential. Keep it as safe as your password. All actions can be carried out using the `Password` tab under vault options. You can access it by selecting a vault, lock it if necessary, and click on `Vault Options`. ![Vault options allowing you to enter a recovery key](/img/desktop/vault-options-password.png) ## Change Password[​](#change-password "Direct link to Change Password") To change the password of an existing vault, you need to know its current one or have a recovery key (see reset password section). Navigate to the `Vault Options` → `Password` tab, and click on `Change Password`. In the opened window, you will be asked for: 1. The vault's current password. 2. A new password. We suggest following our guide on choosing a [strong password](/security/best-practices/.md#good-passwords). 3. Enter the new password again. info Be mindful of your keyboard layout when changing passwords. Special characters and dead keys can behave differently across keyboard layouts (e.g., Dutch vs. English). This may cause password entry issues if you switch keyboard layouts later. For more information, see [Keyboard Layouts and Special Characters](/security/best-practices/.md#keyboard-layouts-and-special-characters). In order to proceed, you must confirm that you understand your action by selecting a checkbox. Finally, click on the `Change` button to change the password. note The `Change` button is activated only if the new password fields match and the checkbox is selected. ![After entering your current password, enter your new one and confirm it](/img/desktop/change-password-prompt.png) info The password is used to derive a [KEK](https://en.wikipedia.org/wiki/Glossary_of_cryptographic_keys), which is then used to encrypt further keys. The KEK changes, but the keys encrypted with the KEK will stay the same. The actual files will not get re-encrypted, meaning you can not upgrade a weak passphrase to a stronger one once the data has been synced to a service that allows recovery of older versions of the masterkey file. If you like to encrypt your vault files with a new, stronger password, you need to create a new vault and drag the data from the old to the new one. Make sure to wipe all backups of the old vault afterwards. ## Storing Passwords[​](#storing-passwords "Direct link to Storing Passwords") info Storing passwords in a keychain can be convenient, but it also poses a security risk if your device is compromised. Ensure that your device is secure and that you trust the used keychain. By default, Cryptomator does not store your vault's password on your hard drive. It is only used to unlock the vault and is destroyed afterward. However, you can enable the option to store the password in the system keychain. This is useful if you want to avoid entering the password every time you unlock the vault. To enable this option: 1. Navigate to the `General` tab in the preferences. 2. Check the box `Store passwords with …` and select your preferred keychain (e.g., macOS Keychain, Windows Hello, or GNOME Keyring). note Not all keychains are supported on all platforms. For example, macOS Keychain is only available on macOS, and Windows Hello is only available on Windows. To store a password for a vault: 1. Start the unlocking process by selecting the vault and clicking on `Unlock` in the main window. 2. Tick the box `Remember password` in the unlock dialog. 3. Enter the vault's password and click on `Unlock`. The password will be stored in the selected keychain, allowing you to unlock the vault without entering the password again. Some keychains may require you to authenticate (e.g., using your system password or biometric authentication) before storing/accessing the password. The stored password can be removed at any time by opening the `Vault Options` → `Password` tab and clicking on `Remove saved password`. Available keychains are: macOS Keychain (macOS) Uses the built-in macOS keychain to store your password. The password is only stored locally on your Mac and is encrypted using the system's security features. Touch ID (macOS) Uses the built-in macOS keychain, but requires authentication with Touch ID before you can access the password. The password is only stored locally on your Mac and is encrypted using the system's security features. Requires a compatible Mac with Touch ID enabled. Windows Hello (Windows) Uses the Windows Hello feature to encrypt your password. The password is only stored locally on your Windows device and is encrypted using a key derived from your Windows user account. Requires a compatible Windows device with Windows Hello enabled. Windows Data Protection API (Windows) Uses the Windows Data Protection API to encrypt your password. The password is only stored locally on your Windows device and is encrypted using a key derived from your Windows user account. GNOME Keyring (Linux) Uses the GNOME keyring to store your password. The password is only stored locally in the default GNOME keyring. Requires GNOME keyring to be installed and running on your Linux system, with the default keyring present. KDE Wallet (Linux) Uses the KDE Wallet to store your password. The password is only stored locally in the default KDE Wallet. Requires KDE Wallet to be installed and running on your Linux system, with the default wallet present. Secret Service (Linux) Uses the KDE Wallet or the GNOME keyring to store your password. The password is only stored locally in the default KDE Wallet or the default GNOME keyring. Secret Service is the successor of KDE Wallet and GNOME keyring, as it works for both. Requires KDE Wallet or GNOME keyring to be installed and running on your Linux system, with the default wallet or keyring present. There are also third-party plug-ins for Cryptomator that allow you to store vault passwords in external password managers: * [KeePassXC plug-in](https://plugin.purejava.org) stores Cryptomator's vault passwords in a KeePassXC database. * [Bitwarden plug-in](https://github.com/purejava/cryptomator-bitwarden/wiki) stores the vault passwords in Bitwarden's Secrets Manager. ## Show Recovery Key[​](#show-recovery-key "Direct link to Show Recovery Key") You can derive a recovery key during vault creation or even later as long as you know your vault's password. To increase security, Cryptomator does not store the recovery key on your hard drive and always derives it on the fly. warning A recovery key can reset a vault's current password. So, treat it like a password and ensure only trusted people have access to it. To derive a recovery key: 1. Navigate to the `Password` tab under `Vault Options`. 2. Click on `Display Recovery Key`. 3. Enter the vault's password. A new window will open displaying a sequence of words (i.e., the recovery key). ![This shows your recoverykey](/img/desktop/recoverykey.png) You can copy it to your clipboard and store it in a secure password manager, or print it on paper. ## Reset Password[​](#reset-password "Direct link to Reset Password") We cannot reset the password of a vault for you in any way. Only you can reset a vault's password, assuming you have its recovery key. Keep it ready before you proceed. 1. Navigate to the `Password` tab under `Vault Options`. 2. Click on `Recover Password`. Type or paste your recovery key in the new window. note Cryptomator offers an auto completion feature to make things easier when typing a recovery key. It's helpful if your recovery key is printed on paper or stored somewhere where you cannot copy it. The feature will kick in automatically once you start typing the first few letters of a word. ![Autocompletion during recovery key entry](/img/desktop/recoverykey-recover-enter.png) If the recovery key is valid, a small message will be displayed below the entered recovery key and the `Next` button will be activated. ![A valid recovery key has been entered](/img/desktop/recoverykey-recover-valid.png) info By design, *only* the correct recovery key is accepted. **A valid but incorrect key won't be accepted to prevent your old data from becoming inaccessible.** Finally, assign a new password to your vault. It is the same process as the [vault creation](/desktop/adding-vaults/.md#choose-a-password), except that no new recovery key is generated. Again, please choose a [strong password](/security/best-practices/.md#good-passwords). Once changed, you can unlock your vault with the new password. note Don't discard the recovery key after resetting the password as it will still remain valid. --- # Setup The Desktop version of Cryptomator is currently available for Windows, macOS, and Linux. Download and installation process varies depending on your operating system. Follow the instructions for your operating system. Ensure that your computer's specifications meet the system requirements required to run Cryptomator smoothly. note We maintain archives of all Cryptomator versions along with detailed changelogs on our [GitHub releases page](https://github.com/cryptomator/cryptomator/releases). ## Install Cryptomator on Windows[​](#install-cryptomator-on-windows "Direct link to Install Cryptomator on Windows") 1. Download Cryptomator's `.exe` installer for Windows from our [downloads page](https://cryptomator.org/downloads/#win). 2. Launch the `.exe` installer. 3. Follow the on-screen instructions. ## Install Cryptomator on macOS[​](#install-cryptomator-on-macos "Direct link to Install Cryptomator on macOS") 1. Download Cryptomator's `.dmg` installer for macOS from our [downloads page](https://cryptomator.org/downloads/#mac). 2. Launch the `.dmg` installer. 3. Accept the license. 4. Drag & drop Cryptomator into the Applications folder. On macOS, Cryptomator will use WebDAV volume type by default if no FUSE driver is installed on the system. But we recommend installing *macFUSE* or *FUSE-T* for a smoother file browsing experience. Install *macFUSE* if your Mac comes with an Intel CPU or install *FUSE-T* if your Mac comes with an Apple Silicon CPU. note Change your [Gatekeeper settings](https://support.apple.com/HT202491) if macOS blocks Cryptomator's installation. ## Install Cryptomator on Linux[​](#install-cryptomator-on-linux "Direct link to Install Cryptomator on Linux") Cryptomator is available on Linux via `Flatpak`, `PPA` and `AUR` package managers, and as an AppImage (an `.appimage` file). The easiest and recommended way of installing Cryptomator on Linux is by downloading Cryptomator's AppImage (an `.appimage` file) - as it works on almost all distributions. Just remember to [make it executable](https://docs.appimage.org/user-guide/run-appimages.html#running-appimages) before you try to run it. Visit our [downloads page](https://cryptomator.org/downloads/#linux) to choose your preferred installation method. --- # Synchronization Conflicts Working on encrypted data from multiple locations is the same as working on unencrypted data from multiple locations. If there is a synchronization conflict, it is handled similarly to how most cloud storage services deal with conflicts. When a sync conflict occurs, cloud storage services typically resolve the conflict by leaving the local file as it is and create an additional, conflicting file with the content from the cloud. The file name is the same as the original one, suffixed with a short string (e.g., `(Created by Alice)`) to indicate it's a different version. Cryptomator handles encrypted files in the same way. It detects sync conflicts and appends the suffix from your cloud provider to the decrypted filename. If the filename with the conflict suffix is too long, Cryptomator shortens the overall filename. If the (decrypted) filename with the conflict suffix already exists, the conflicted file has a simple `(X)` suffix, where X is an integer. | Situation | Cloud Provider Suffix | Original Decrypted Name | New Decrypted Name | | ------------------------------------------- | -------------------------------- | --------------------------------------------- | -------------------------------------------------------------- | | Regular | (Created by Alice) | businessPitch.odp | businessPitch (Created by Alice).odp | | Preferred name already taken | (Created by Alice) | businessPitch.odp | businessPitch (1).odp | | Maximum cleartext of the vault is set to 62 | (Created by Alice on 2024-01-31) | businessPitchForTheGreatIdeaIHadLastNight.odp | businessPitchForTheGreatIdeaI (Created by Alice on 2024-01.odp | tip Sync conflicts can happen in cloud storages for several reasons. In such cases, it is up to you to decide what to do with the conflicted files. It is recommended to manually check both files and determine which one to keep. If you conclude that both files are identical, you can delete one copy. The organization of your files is entirely in your hands. ## Handling Sync Conflicts[​](#handling-sync-conflicts "Direct link to Handling Sync Conflicts") 1. When a sync conflict is detected, Cryptomator will display the conflicted file with a suffix, as shown in the table above. 2. Manually review both the original and conflicted files. 3. Decide which file to keep based on your review. 4. If both files are identical, you can delete one of the copies to resolve the conflict. By following these steps, you can effectively manage synchronization conflicts and ensure that your data remains consistent across multiple locations. ## Example[​](#example "Direct link to Example") Suppose you have a file named `projectPlan.doc` in your vault. In the encrypted vault, this file might be represented with an encrypted name such as `5TyvCyF255sRtfrIv...83ucADQ==.c9r`. If a synchronization conflict occurs, it will happen on the encrypted filename. Cryptomator detects unexpected patterns in the encrypted filename and handles the conflict accordingly. For example, if there is a conflict with `5TyvCyF255sRtfrIv...83ucADQ== (Created by Alice).c9r`, Cryptomator will decrypt the encrypted part of the filename and rename the file to include a conflict suffix. The conflicted file might be renamed to something like `FHTa55bH...sUfVDbEb0gTL9hZ8nho.c9r`, which corresponds to `projectPlan (Created by Alice).doc`. --- # Troubleshooting This page contains solutions for common issues you might encounter when using Cryptomator on desktop platforms. ## Log File Locations[​](#log-file-locations "Direct link to Log File Locations") Cryptomator creates log files to help with troubleshooting when issues occur. The default locations for these log files vary by operating system: | Operating System | Default Log File Location | | ---------------- | ---------------------------------- | | Windows | `%localappdata%\Cryptomator\` | | macOS | `~/Library/Logs/Cryptomator/` | | Linux | `~/.local/share/Cryptomator/logs/` | The log files are named with the pattern `cryptomatorX.log`, where `X` is a number from 0 to 9. The most recent log file is always `cryptomator0.log`. ## Debug Mode[​](#debug-mode "Direct link to Debug Mode") Debug mode enables additional diagnostic logging to help troubleshoot issues with Cryptomator. When debug mode is active, the application records more detailed information about its operations in the log files. Privacy Consideration With debug mode enabled, *every accessed file and listed directory inside the vault is written in clear text to the log file*. This creates a record of your file and folder names, which may compromise privacy. Only enable debug mode when actively troubleshooting an issue, and remember to disable it afterward. To enable debug mode: 1. Open Cryptomator and open the preferences. 2. In the general tab, look for the `Enable debug logging` checkbox at the bottom and enable it. Cryptomator will now run in debug mode. The app indicates this by showing a red bar at the bottom of the main window. The additional debug information is written to your log files. Once you have reproduced the issue you're investigating, disable debug mode by unchecking the option to return to normal logging levels. ## Known Issues[​](#known-issues "Direct link to Known Issues") For a list of known issues, please refer to the [Cryptomator Community](https://community.cryptomator.org/c/help/known-issues/16) or [GitHub Issues page](https://github.com/cryptomator/cryptomator/issues). --- # Events and Event View Vault events provide information about your vault's status and activities during file operations. Cryptomator generates events to help you monitor vault health and troubleshoot issues like sync conflicts or file corruption. info Vault events are not persisted on the hard disk. They are only stored in memory and are lost when the application is closed. ## Viewing Events[​](#viewing-events "Direct link to Viewing Events") All vault events are logged in the event view, which can be accessed from the main window. To open the event view, click the **Bell** icon in the lower-left corner of the main window. If new, unread events are present, the icon displays a small red dot. ![Event view](/img/desktop/event-view.png) The event view displays events from all vaults, with the newest events at the top. You can filter events by vault or clear the entire log using the **trash can** icon in the action bar. Each vault event shows a title, the number of occurrences in brackets, an affected file path, and a timestamp. Hover over any event to reveal a context menu with event-specific actions, such as revealing affected files in your file manager. When a vault is locked, its events are anonymized for security. Unlock the vault to view detailed event information. ## Event Types[​](#event-types "Direct link to Event Types") Cryptomator generates five types of vault events. Understanding these events helps you maintain vault health and resolve issues quickly. ### Decryption Failed Event[​](#decryption-failed-event "Direct link to Decryption Failed Event") Cryptomator cannot decrypt an encrypted file in your vault. This indicates potential file corruption or cryptographic integrity issues. **When it occurs:** * An encrypted file cannot be decrypted during a read operation * File corruption has damaged the cryptographic data **What to do:** Investigate the affected file by ensuring it is properly synced. Compare the file size with what appears in your cloud provider's web interface. If the sizes differ, sync conflicts or incomplete uploads may be the cause. Restore the file from a backup if corruption is confirmed. When multiple files are affected, the entire vault's integrity may be compromised. ### Conflict Resolved Event[​](#conflict-resolved-event "Direct link to Conflict Resolved Event") Cryptomator automatically resolved a filename conflict within an encrypted directory. This occurs when two encrypted files have the same base name, with one having an additional suffix. For more information, see [handling sync conflicts](/desktop/sync-conflicts/.md). **When it occurs:** * Two files with conflicting encrypted names exist in the same directory * The automatic conflict resolution successfully renames the conflicting file * Data integrity is maintained during the resolution process **What to do:** Verify that both files contain the expected content and manually merge any necessary changes. This is typically the result of sync conflicts between devices. ### Conflict Resolution Failed Event[​](#conflict-resolution-failed-event "Direct link to Conflict Resolution Failed Event") Cryptomator encounters a filename conflict but fails to automatically resolve it. This typically happens when the automatic renaming process cannot complete due to filesystem restrictions or permissions issues. **When it occurs:** * A filename conflict is detected but cannot be automatically resolved * File system permissions prevent the renaming operation * The target filename for conflict resolution already exists * An I/O error occurs during the resolution process **What to do:** Manual intervention is required. Check file permissions, retry, or free up space in the target directory. Afterward, start the conflict resolution again by listing the decrypted directory. ### Broken File Node Event[​](#broken-file-node-event "Direct link to Broken File Node Event") A path within your vault appears to be corrupted because the encrypted directory is missing required identification files. This might be structural damage to the vault's directory hierarchy. **When it occurs:** * Accessing a path that should exist but has incomplete encrypted directory structure * The directory is missing essential files like *dir.c9r* * Vault structure corruption has occurred **What to do:** Ensure the encrypted directory is properly synced. Compare the content of the encrypted directory with what appears in your cloud provider's web interface or on other devices. Restore from backup if other sources show the same (incomplete) directory content. If the directory is still broken, consider deleting it to free the filesystem node. ### Broken Directory File Event[​](#broken-directory-file-event "Direct link to Broken Directory File Event") A *dir.c9r* file is corrupted, either because it's empty when it shouldn't be, or because it exceeds the maximum allowed size of 1000 bytes. Directory files are critical for maintaining the vault's encrypted directory structure. **When it occurs:** * A *dir.c9r* file is empty * A *dir.c9r* file is larger than 1000 bytes (indicating corruption) * The directory file contains invalid or corrupted data **What to do:** This indicates directory structure corruption. As with the [Broken File Node Event](#broken-file-node-event), ensure proper sync and compare with other sources. The affected directory is inaccessible and access needs to be restored with the health check. If the fix inside the health check was applied, delete the directory containing the broken link. warning Broken file events (both file nodes and directory files) indicate serious vault corruption. When these events occur, you should always investigate for a cause and restore from the cloud or a recent backup to prevent further corruption. --- # Vault Management A *vault* is where your files are stored encrypted. For your operating system or other apps, a vault is a just a normal directory containing some encrypted files. Only Cryptomator can decrypt the vault's contents when you unlock it using a password. ## Remove Vaults[​](#remove-vaults "Direct link to Remove Vaults") To remove a vault from the vault list, right click on a vault, and click remove. This is only possible if the vault is locked. note The vault is **not** deleted from your PC by removing it from the list. If you wish to permanently delete your encrypted files, you need to delete the vault directory using the file manager. ## Reorder Vaults[​](#reorder-vaults "Direct link to Reorder Vaults") You can change the order of the vaults in the list by dragging them. [](/img/desktop/reorder-vaults.mov) ## Vault Options[​](#vault-options "Direct link to Vault Options") Each vault has its own settings which can be customized under vault options. To open a vault's settings, select a vault, lock it, and click on `Vault Options`. The options are divided across three categories: 1. General - Options not fitting in other categories. You can select this option if the vault is unlocked as soon as Cryptomator starts. ![General vault options](/img/desktop/vault-options-general.png) * `Vault Name` - The name of the vault. *You can edit this field to rename the vault.* * `Lock when idle for minutes` - The vault will be locked automatically after the specified time of inactivity. * `Unlock vault when starting Cryptomator` - On app start, Cryptomator will unlock the vault (otherwise the vault will remain locked). * `After successful unlock` * `Do nothing` - Cryptomator will do nothing after unlocking the vault. * `Reveal Drive` - Opens the mount location using the default file manager (Windows Explorer, Finder, …). * `Ask` - Cryptomator will ask you what to do after unlocking the vault. 2. Mounting - Settings that manage how and where a vault is mounted. note The mount options depend on the selected [volume type](/desktop/volume-type/.md). ![Vault options for mounting](/img/desktop/vault-options-mounting.png) 3. Password - Here you can manage the vault's password and recovery key. ![Vault options regarding the password](/img/desktop/vault-options-password.png) note If the `masterkey` file is not present in the vault directory, the functions in the `Password` tab are disabled. To use these functions again, place the `masterkey` file back into the vault directory or restore it using the vault recovery function. Take a look at the [Volume Type](/desktop/volume-type/.md) and [Password And Recovery Key](/desktop/password-and-recovery-key/.md) sections to understand how vault mounting and passwords work. --- # Vault Recovery If a vault cannot be added to Cryptomator or opened from inside the app anymore, you can use the Vault Recovery feature to unlock it again. note Vault Recovery does not restore your encrypted files. It only recreates missing configuration files such as `vault.cryptomator` in order for Cryptomator to recognize and unlock your vault again. It helps with the following scenarios: 1. The masterkey file is missing or damaged - [`Recover Masterkey file`](#recover-masterkey-file) 2. The vault config file is missing or damaged - [`Recover Vault config file`](#recover-vault-config) 3. The masterkey and the vault config files are missing or damaged - [`Recover Masterkey and Vault config files`](#recover-full) If the damaged vault has not yet been added to Cryptomator, you start the recovery during the import process, see [`Add a vault with missing config files and restore them`](#add-recover-vault). warning Recovery of missing files is only supported starting with Vault Format 8 (introduced in Cryptomator 1.6.0). Vaults created with older formats (e.g., Vault Format 7 or earlier) are not compatible with these recovery options. For details, see the [Vault Format History](/misc/vault-format-history/.md). ## Recover Masterkey file[​](#recover-masterkey-file "Direct link to Recover Masterkey file") If the file `masterkey.cryptomator` is missing from your vault folder, Cryptomator will still recognize the folder as a normal vault. When you try to unlock the vault, a dialog appears saying “Masterkey file not found.” In this dialog, you can: * `Choose` a masterkey file manually, if it was stored outside the vault folder. * Or check the option “Restore the masterkey file instead” and click `Restore`. For the latter case, you need the vault recovery key to restore the masterkey file. You’ll be guided through the recovery process and on success, you can unlock the vault as usual. ## Recover Vault config file[​](#recover-vault-config "Direct link to Recover Vault config file") If the file `vault.cryptomator` is missing, Cryptomator can recreate it using either your vault password or your recovery key. In the vault list, the vault is marked with an exclamation mark. In Vault Details, you’ll see `Vault config is missing.`. Here you can click `Restore vault config` to start the recovery process. You either need the Recovery Key or the vault password to restore the vault config file. You’ll be guided through the process and on success, you can open the vault as usual. ## Recover Masterkey and Vault config files[​](#recover-full "Direct link to Recover Masterkey and Vault config files") note If the vault is created with Cryptomator Hub, you can’t restore the missing config files yourself. Please contact the vault owner, who can recreate the configuration file for you. If both config files – `masterkey.cryptomator` and `vault.cryptomator` – are missing, Cryptomator can restore them using your recovery key. In the vault list, the vault is marked with an exclamation mark. In Vault Details, you’ll see `Vault config is missing.`. Here you can click “Restore vault config” to start the recovery process. You need the Recovery Key to restore the vault config file. You’ll be guided through the process and on success, you can open the vault as usual. ## Add a vault with missing config files and restore them[​](#add-recover-vault "Direct link to Add a vault with missing config files and restore them") If a vault has no configuration files and has not yet been added to Cryptomator, you recover it during the import process. Open the main window and click the plus `+` button. In the context menu, choose `Recover Existing Vault…`. Then select the vault directory you want to recover. Depending on which configuration files are missing, Cryptomator picks the right recovery options and will guide you through the same steps as described above. After the process completes, the restored vault will be added to your vault list automatically. --- # Volume Types Volume types play an important role when handling your files. When you unlock a vault, Cryptomator makes decrypted files available in your file manager by mounting a virtual drive on your operating system. This mounting of a virtual drive is handled differently depending on the volume type chosen in Cryptomator's preferences. In general, all volume types Cryptomator offers can be categorized into two categories: 1. [WebDAV](#what-is-a-webdav-volume-type) 2. [FUSE](#what-is-a-fuse-volume-type) ## What Is a WebDAV Volume Type?[​](#what-is-a-webdav-volume-type "Direct link to What Is a WebDAV Volume Type?") WebDAV is a standardized [communication protocol](https://en.wikipedia.org/wiki/WebDAV) used to perform operations on resources (files, directories/folders) between a client (you) and a server (your local computer). WebDAV was intended for remote access, but Cryptomator uses it to start a local-only server, which you can use to browse your decrypted files. You can tweak WebDAV's settings for each vault by navigating to Cryptomator's `Preferences` → `Virtual Drive`. WebDAV has widespread support and adequate performance, but its implementation differs between operating systems. ## What Is a FUSE Volume Type?[​](#what-is-a-fuse-volume-type "Direct link to What Is a FUSE Volume Type?") Filesystem in Userspace ([FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace)) is a filesystem interface originally developed for Unix operating systems that let non-privileged users create their own file systems without editing kernel code. Which means, FUSE does not require admin privileges and has good support across all major desktop operating systems. FUSE volume type also delivers good performance when working on files. All FUSE related volume types support custom mount options, but every option must be prefixed with `-o`. For example, you must enter `-oallow_other` if you want to specify `allow_other` option. ## Choosing a Volume Type[​](#choosing-a-volume-type "Direct link to Choosing a Volume Type") Cryptomator uses the same volume type for all vaults. You can select which volume type to use in the preferences. Every volume type offers fixed set of features for mounting a vault. The feature set is shown when selecting the volume type. In Cryptomator's window, navigate to `Preferences` (gear icon at top right), then `Virtual Drive` to set the volume type. The availability of volume types depends on your operating system and installed drivers. You might have to restart Cryptomator when changing volume types. A notification will be displayed if a restart is needed. ![Virtual Drive Tab in Preferences](/img/desktop/preferences-virtual-drive.png) ## Windows[​](#windows "Direct link to Windows") ### WinFsp / WinFsp (Local Drive)[​](#winfsp "Direct link to WinFsp / WinFsp (Local Drive)") **Requirements:** Windows, WinFsp installed The [WinFsp project](https://winfsp.dev/) provides FUSE bindings for Windows. WinFsp is automatically installed along Cryptomator when you are using the EXE installer, but there's also a WinFsp standalone installer [here](https://winfsp.dev/rel/) if you ever need it. By default, unlocked vaults are mounted to a random drive letter, either as a network or a local drive. Info on custom mount options is available at [WinFsp repository](https://github.com/winfsp/winfsp/blob/c61679a35d041d843173fa3b2eba106b5ab7b01f/src/dll/fuse/fuse.c#L628-L654). note Vaults mounted to a drive letter are only accessible to the current user. If you want to access the vault as a different/elevated user, you have to use WinFsp (Local Drive) and [mount to a directory](/desktop/vault-management/.md#vault-options). ### WebDAV (Windows Explorer)[​](#webdav-windows-explorer "Direct link to WebDAV (Windows Explorer)") **Requirements:** Windows WebDAV on Windows uses the [`net use`](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/gg651155\(v=ws.11\)) command to mount/unmount the virtual drive. The unlocked vaults is displayed as a network drive and assigned to a random drive letter. info WebDAV on Windows uses the native Windows WebDAV-Client. We recommend using [WinFsp](#winfsp) due to its restrictions: * **Maximum file size of 4 GB:** Files bigger than 4GB cannot be copied into or out of the vault. * **Maximum path length of 260 characters:** Files with an absolute path longer than 260 characters cannot be accessed at all * **Wrong reported total and free space:** The total space and free space of the vault are always reported to be the same as the total space and free space of the C: drive, even if the vault is stored on a different drive ## macOS[​](#macos "Direct link to macOS") ### macFUSE[​](#macfuse "Direct link to macFUSE") **Requirements:** macOS, macFUSE installed macFUSE is the most mature FUSE implementation for macOS. If you're comfortable with booting into recovery mode once to enable loading of kernel extensions, this is the recommended option for best compatibility and stability. macFUSE volume type depends on a library provided by the [macFUSE project](https://macfuse.github.io/). It is not included with Cryptomator due to license restrictions. You can install the latest version from [macFUSE's release page](https://github.com/macfuse/macfuse/releases), following the [installation guide](https://github.com/macfuse/macfuse/wiki/Getting-Started). By default, unlocked vaults are mounted to `/Volumes`. Info on custom mount options is available at [macFUSE wiki](https://github.com/macfuse/macfuse/wiki/Mount-options). note macFUSE has been relying on kernel extensions. Apple has deprecated kernel extensions with macOS 12.3, which requires additional steps during installation. Despite this, macFUSE remains the most stable option due to its maturity. Furthermore, macFUSE has already released [experimental support for FSKit](https://github.com/macfuse/macfuse/issues/1025#issuecomment-2850724070), which will eventually replace the older VFS API. ### FUSE-T (Experimental)[​](#fuse-t "Direct link to FUSE-T (Experimental)") **Requirements:** macOS, FUSE-T installed FUSE-T is a newer alternative that runs entirely in user space, avoiding the need for kernel extensions. This volume type depends on a library provided by the [FUSE-T project](https://www.fuse-t.org/). You can install it using brew: ``` brew tap macos-fuse-t/homebrew-cask brew install fuse-t ``` By default, unlocked vaults are mounted to `~/Cryptomator/`. Info on custom mount options is available at [wiki of the FUSE-T project](https://github.com/macos-fuse-t/fuse-t/wiki#supported-mount-options). warning FUSE-T is less mature than macFUSE and some users have reported occasional malfunctions. Consider using macFUSE if you experience issues. ### WebDAV (AppleScript)[​](#webdav-applescript "Direct link to WebDAV (AppleScript)") **Requirements:** macOS WebDAV requires no additional software installation and utilizes the scripting language [AppleScript](https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptLangGuide/introduction/ASLR_intro.html) to mount/unmount the virtual drive. By default, unlocked vaults are mounted to `/Volumes`. While sufficient for most file operations, the experience may feel less polished due to security warnings about the localhost connection not being secure. These warnings are expected since no certificate authority will issue TLS certificates for localhost. ## Linux-Based OS[​](#linux-based-os "Direct link to Linux-Based OS") ### FUSE[​](#fuse "Direct link to FUSE") **Requirements:** Linux, `fuse3` installed FUSE on Linux works only if the `fuse3` package is installed. Luckily, `fuse3` comes pre-installed on many Linux distributions. By default, unlocked vaults are mounted to `~/.local/share/Cryptomator/mnt`, but you can use custom mount options to change the path. Info on custom mount options is available at [man page for mount.fuse](https://man7.org/linux/man-pages/man8/mount.fuse3.8.html). note `allow_root` and `allow_other` cannot be used as [custom mount flags](/desktop/vault-management/.md#vault-options) without enabling (uncommenting) `user_allow_other` option in **/etc/fuse.conf** configuration file. ### WebDAV (gio)[​](#webdav-gio "Direct link to WebDAV (gio)") **Requirements:** Linux, `gio` installed Due to the wide variety of Linux distributions, Cryptomator only supports system integrated WebDAV volume type if [gio](https://manpage.me/?gio) is installed. You can unlock your vault without `gio` using [WebDAV (HTTP Address)](#webdav-http-address), but support across distributions is not guaranteed. Also, it's up to yourself to figure out how to integrate WebDAV share with your distro. ## OS-Independent[​](#os-independent "Direct link to OS-Independent") ### WebDAV (HTTP Address)[​](#webdav-http-address "Direct link to WebDAV (HTTP Address)") **Requirements:** None - Works on all OS. This volume type is always present and comes in handy when all other volume types fail to mount. It starts a local-only WebDAV server, which can be manually integrated into the system or accessed using a third-party application, like [Cyberduck](https://cyberduck.io/). Check out the regarding manuals for your OS on how to connect to a WebDAV server. The address of Cryptomator's local-only WebDAV server can be copied from the vault detail screen by clicking the green "Copy" button. --- # Admin Guide This guide is for administrators of a Cryptomator Hub instance. It covers users and groups, the connection to your identity provider, Emergency Access, the audit log, Web of Trust, and your license. If your instance is fresh, start with the [Quick Start](/hub/admin-guide/quick-start/.md). It walks you through your first day as an administrator. The other pages describe each area in detail. note If you also run the instance yourself, see the [Self-Hosting Guide](/hub/self-hosting-guide/.md) for deployment and maintenance. ## [📄️Quick Start](/hub/admin-guide/quick-start/.md) [Your first day as a Hub administrator — add users and groups, connect your identity provider, enable Emergency Access, and keep an eye on audit logs and license seats.](/hub/admin-guide/quick-start/.md) ## [📄️User & Group Management](/hub/admin-guide/user-group-management/.md) [Users and groups are managed directly in the Cryptomator Hub admin interface. As an administrator, you can create, edit, and delete users and groups, assign roles, and manage group memberships.](/hub/admin-guide/user-group-management/.md) ## [📄️Identity Provider](/hub/admin-guide/keycloak/.md) [Cryptomator Hub delegates authentication and user management to Keycloak, an open-source identity and access management solution. Hub ships with a preconfigured realm named cryptomator that contains the clients Hub needs and the realm roles user, create-vaults, and admin.](/hub/admin-guide/keycloak/.md) ## [📄️License](/hub/admin-guide/license/.md) [Every Cryptomator Hub instance requires a license.](/hub/admin-guide/license/.md) ## [📄️Audit Logs](/hub/admin-guide/audit-logs/.md) [The Audit Logs provide an overview of security-related events within Cryptomator Hub.](/hub/admin-guide/audit-logs/.md) ## [📄️Web of Trust](/hub/admin-guide/web-of-trust/.md) [The Web of Trust (WoT) feature in Cryptomator Hub helps users verify each other's identity by signing the User Key Pair with their private keys using ECDSA.](/hub/admin-guide/web-of-trust/.md) ## [📄️Emergency Access](/hub/admin-guide/emergency-access/.md) [Visit cryptomator.org for more information about Enterprise features.](/hub/admin-guide/emergency-access/.md) --- # Audit Logs The Audit Logs provide an overview of security-related events within Cryptomator Hub. These logs allow administrators to track important account and vault-related actions. note Audit Logs are not available with a Community License. ## Viewing the Audit Log[​](#audit-log-table-view "Direct link to Viewing the Audit Log") The logs are displayed in a structured table containing the following columns: * **Timestamp** – The exact time of the event. * **Event** – The type of event that occurred. * **Details** – Additional information about the event. ![Audit Logs Table View](/img/hub/auditlogs-overview.png) ## Filtering Audit Logs[​](#filtering-audit-logs "Direct link to Filtering Audit Logs") To refine the displayed logs, a filtering function is available: ![Audit Log Filtering Options](/img/hub/auditlogs-filter.png) * **Date Range Filter**: Allows filtering logs between two specific dates. * **Event Type Filter**: A multi-select dropdown enables filtering by event type. ![Audit Log Filtering Options](/img/hub/auditlogs-filter-events.png) ## Event Types[​](#event-types "Direct link to Event Types") The following events are logged: ### Device[​](#event-type-device "Direct link to Device") * **Register Device** - A user [registered a new device](/hub/user-guide/access-vault/.md#register-device). This can be, e.g., a Cryptomator app (desktop/mobile) to unlock a vault or a web browser to access Cryptomator Hub. * **Remove Device** – A user [removed a device](/hub/user-guide/your-account/.md#authorized-devices). ### Web of Trust[​](#event-type-web-of-trust "Direct link to Web of Trust") * **Signed Identity** – A user [signed the identity of another user](/hub/user-guide/vault-management/.md#web-of-trust). * **Update Wot Setting** – A user updated [Web-of-Trust settings](/hub/user-guide/vault-management/.md#web-of-trust), e.g., the `wot_max_depth`. ### Vault[​](#event-type-vault "Direct link to Vault") * **Add Vault Member** – A vault owner [added a member to a vault](/hub/user-guide/vault-management/.md#share-a-vault). This only adds the member but does not derive the vault key for the new member. * **Create Vault** – A user [created a vault](/hub/user-guide/vault-management/.md#create-a-vault). * **Grant Vault Access** – A user [derived the vault key for the new member](/hub/user-guide/vault-management/.md#update-permissions). * **Retrieve Vault Key** – A user retrieved a vault key. This happens when a user [unlocks a vault](/hub/user-guide/access-vault/.md#unlocking-a-vault) but also, e.g., when an owner manages the vault. The IP address and device information are optional for legacy reasons. * **Remove Vault Member** – A vault owner removed a member from a vault. * **Update Vault Member** – A vault owner [changed a member's role](/hub/user-guide/vault-management/.md#change-ownership) (owner or user). * **Update Vault** – A vault owner [updated the vault metadata](/hub/user-guide/vault-management/.md#edit-vault-metadata). This includes the vault name or description. ### Account[​](#event-type-account "Direct link to Account") * **Account Key Changed** – A user [re-generated the account key](/hub/user-guide/your-account/.md#regenerate-account-key). This also logs `User Keys Change` because changing the account key also changes parts of the user keys. * **Reset User Account** – A user [reset their account](/hub/user-guide/your-account/.md#reset-account). * **User Keys Change** – A user changed their keys. This happens, for example, when the user [finished the account setup](/hub/user-guide/your-account/.md#account-setup). ### Emergency Access (Enterprise Only)[​](#event-type-emergency-access "Direct link to Emergency Access (Enterprise Only)") * **Emergency Access Setup** – A vault owner set up or updated the Emergency Access configuration for a vault (e.g. by assigning council members in Vault Details). * **Emergency Access Settings Updated** – An admin changed the [global Emergency Access settings](/hub/admin-guide/emergency-access/.md#admin-settings). * **Emergency Access Recovery Started** – A council member [started](/hub/admin-guide/emergency-access/.md#starting-a-recovery-process) an Emergency Access recovery process. * **Emergency Access Recovery Approved** – A council member [approved](/hub/admin-guide/emergency-access/.md#approve-a-recovery-process) a running recovery process. * **Emergency Access Recovery Completed** – A council member [completed](/hub/admin-guide/emergency-access/.md#complete-a-recovery-process) a recovery process. * **Emergency Access Recovery Aborted** – A council member [aborted](/hub/admin-guide/emergency-access/.md#abort-a-recovery-process) a running recovery process. note When a council member starts a recovery process, both `Emergency Access Recovery Started` and `Emergency Access Recovery Approved` are logged. ### Legacy[​](#event-type-legacy "Direct link to Legacy") * **Claim Vault Ownership** – A user claimed vault ownership. This event is logged when a vault created with hub pre 1.3.0 is claimed by the vault creator using the `Vault Admin Password`. --- # Emergency Access Enterprise Feature Visit [cryptomator.org](https://cryptomator.org/hub/?utm_source=docs.cryptomator.org\&utm_medium=referral\&utm_campaign=emergency-access) for more information about Enterprise features. Emergency Access restores access to a vault inside Cryptomator Hub in case of account loss or ownership issues. Its process requires a group of trusted users (the "council") to approve the recovery. When enough approvals are collected, the emergency change is completed and vault management access is restored. Technically, this is implemented using key splitting based on **[Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing)**. ## Set Up Emergency Access[​](#set-up-emergency-access "Direct link to Set Up Emergency Access") The feature can be activated for new and existing vaults: * **New vaults:** During vault creation, use the `Define Emergency Access Conditions` step. For the full workflow, see [Vault Management](/hub/user-guide/vault-management/.md#create-a-vault). * **Existing vaults:** Open `Vault Details` and [configure Emergency Access](/hub/user-guide/vault-management/.md#emergency-access-council). ## Configure Global Defaults[​](#admin-settings "Direct link to Configure Global Defaults") In the administration area, you can define the default Emergency Access values applied to new or updated vaults. ![Emergency Access](/img/hub/admin-emergency-access.png) Activate `Enable Emergency Access` and configure: * `Required Keys`: Number of required key shares * `Keyholders`: Default council members (only activated users) * Optional: `Let vault owners choose different keyholders` * Optional: `At least` (minimum members if owners can choose a different council) warning A council without redundancy (`Required Keys == number of council members`) is possible, but not recommended. ## Starting a Recovery Process[​](#starting-a-recovery-process "Direct link to Starting a Recovery Process") To start, open the `Emergency Access` page, select the vault, and start the desired process. ![Emergency Access Vault List](/img/hub/emergency_access_vault_list.png) There are two process types: 1. `Change Emergency Access Council`: Change Emergency Access council and threshold 2. `Choose Vault Members`: Choose vault owners/members info Only one running process per type is allowed for the same vault. Use this quick guide to choose the right process: | If you want to... | Start this process | | ---------------------------------------------------------- | ----------------------------------------------------- | | Give vault access to different users (owners/members) | `Choose Vault Members` | | Remove access from specific users | `Choose Vault Members` | | Replace council members who approve emergency operations | `Change Emergency Access Council` | | Change how many council approvals are required (threshold) | Configurable in the [admin settings](#admin-settings) | note Starting a process automatically approves the process. ### Choose Vault Members[​](#choose-vault-members "Direct link to Choose Vault Members") The `Choose Vault Members` process allows you to select new vault `Owners` or `Members`. Users that are no longer part of the vault are shown as `Removed`. ![Emergency Access Vault List](/img/hub/emergency_access_change_permissions_start.png) ### Change Emergency Access Council[​](#change-emergency-access-council "Direct link to Change Emergency Access Council") The `Change Emergency Access Council` process allows you to select a new council. The minimum required number of members is configured in the [Admin settings](#admin-settings). ![Emergency Access Vault List](/img/hub/emergency_access_change_council_start.png) ## Approve a Recovery Process[​](#approve-a-recovery-process "Direct link to Approve a Recovery Process") To view or approve running Emergency Access processes, open the `Emergency Access` list. If an Emergency Access process is running for a vault, the vault is displayed with a process button. If you haven't approved the process, the button includes `Approve now`. ![Emergency Access Vault List Approve Now](/img/hub/emergency_access_vault_list_change_council_approve_now.png) Approve a running process in three steps: 1. Open the vault in the `Emergency Access` list. 2. Click `Approve now` to open the `Approve Emergency Access` dialog. 3. Review the details and click `Approve`. ![Emergency Access Vault List Approve Dialog](/img/hub/emergency_access_vault_list_change_council_approve_dialog.png) After submitting your share, the button shows `Waiting for other approvals`. You can track the ongoing process progress in the same process button and its details popover. You can also inspect details before approving. Hover (or click) the segment ring area on the left side of the process button to open the process details popover. The popover shows: * process type and required approvals * current progress * process council members * per-member status (`Added` / `Pending`) ![Emergency Access Vault List Hover Process](/img/hub/emergency_access_vault_list_hover_process.png) ## Complete a Recovery Process[​](#complete-a-recovery-process "Direct link to Complete a Recovery Process") As soon as enough shares are available, the process button in the `Emergency Access` vault list shows `Complete now`. ![Emergency Access Vault List Complete Now](/img/hub/emergency_access_vault_list_change_council_complete_now.png) Click `Complete now` to open the `Complete Emergency Access` dialog. In this dialog, review the process details and click `Complete Process` to finalize the recovery process. ![Emergency Access Vault List Complete Dialog](/img/hub/emergency_access_vault_list_change_council_complete_dialog.png) Results by type: * `Choose Vault Members`: Vault roles are updated and required access grants are redistributed. * `Change Emergency Access Council`: The old council is replaced by the new council. After successful completion, the process is removed. ## Abort a Recovery Process[​](#abort-a-recovery-process "Direct link to Abort a Recovery Process") Running processes can be canceled in the dialog using `Abort this Process`. ![Emergency Access Vault List Abort Dialog](/img/hub/emergency_access_vault_list_change_council_abort_dialog.png) ## Typical States and Notes[​](#typical-states-and-notes "Direct link to Typical States and Notes") The following warning states can appear in the Emergency Access list: * `No Vault Council Member anymore`: The user is still part of a running process but no longer part of the current vault council. What to do: Ask a current council member to start a new process with the correct council composition. * `Broken Emergency Access`: Too few valid shares remain (for example after council members reset their accounts). What to do: Reconfigure the council in vault details and ensure enough active council members can provide shares. * `No Redundancy`: No fault tolerance in the council. What to do: Increase the number of council members or reduce the required threshold so one unavailable user does not block recovery. ## Audit Log Events[​](#audit-log-events "Direct link to Audit Log Events") See [Emergency Access Audit Log events](/hub/admin-guide/audit-logs/.md#event-type-emergency-access). --- # Identity Provider Cryptomator Hub delegates authentication and user management to [Keycloak](https://www.keycloak.org/), an open-source identity and access management solution. Hub ships with a preconfigured realm named `cryptomator` that contains the clients Hub needs and the realm roles `user`, `create-vaults`, and `admin`. This page describes the Keycloak configuration tasks that are specific to running Hub. For everything else, refer to the [Keycloak documentation](https://www.keycloak.org/documentation). ## External Identity Management[​](#enterprise-external-iam "Direct link to External Identity Management") Connecting Cryptomator Hub to an external identity manager allows you to: * Synchronize users and groups from LDAP or Active Directory * Delegate authentication via OpenID Connect or SAML * Keep your user management centralized in your existing IAM You can access the Keycloak management interface from the admin section of Hub. There you can perform all user- and group-related tasks, such as [creating new users](https://www.keycloak.org/docs/latest/server_admin/index.html#proc-creating-user_server_administration_guide), [deleting users](https://www.keycloak.org/docs/latest/server_admin/index.html#proc-deleting-user_server_administration_guide) or [managing groups](https://www.keycloak.org/docs/latest/server_admin/index.html#proc-managing-groups_server_administration_guide). ![Accessing Keycloak via Hub](/img/hub/access-keycloak-link.png) Setting up LDAP synchronization is described in the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#_ldap). For OpenID Connect and SAML, the Keycloak documentation provides [general information](https://www.keycloak.org/docs/latest/server_admin/#_identity_broker). The configuration steps specific to Hub are covered below: [connecting an external identity provider](#connecting-an-external-identity-provider), [restricting who may access Hub](#restricting-access-to-hub), and [migrating to another identity provider](#migrating-to-another-identity-provider). ## Connecting an External Identity Provider[​](#connecting-an-external-identity-provider "Direct link to Connecting an External Identity Provider") You can connect Hub to your existing identity provider so that users authenticate with the credentials they already have. Keycloak supports two fundamentally different approaches, and the choice affects when users become visible in Hub. With user federation over LDAP or Active Directory, Keycloak reads the directory directly. All users and groups exist in Hub right after the first synchronization, which means you can assign vault permissions before anyone has logged in. With identity brokering over OpenID Connect or SAML, Keycloak redirects users to the external provider. Users only appear in Hub after their first successful login, so you cannot grant vault access to someone who has never signed in. ### OpenID Connect[​](#openid-connect "Direct link to OpenID Connect") To delegate authentication to an OpenID Connect provider such as Microsoft Entra ID, add an OpenID Connect provider under *Identity providers* in the `cryptomator` realm and enter the discovery endpoint, client ID, and client secret issued by your provider. Note that users are created lazily. Keycloak only knows an account after that person has logged in through the external provider for the first time. ### Mapping Groups to Roles[​](#mapping-groups-to-roles "Direct link to Mapping Groups to Roles") Group memberships are not part of the token by default, so you have to enable them on both sides. In Microsoft Entra ID, open your app registration, go to *Manage* → *Manifest*, and set `"groupMembershipClaims": "All"`. Other providers have an equivalent setting that adds a `groups` claim to the token. In Keycloak, open your identity provider and add one *Claim to Role* mapper per group you want to map. Set the claim to `groups` and the claim value to the group's identifier — for Entra ID this is the **Object ID** of the group, not its display name. Then select the realm role to assign, typically `user` for regular members and `admin` for administrators. These mappers are evaluated lazily as well. A role is only assigned when the affected user logs in. ### LDAP and Active Directory[​](#ldap-and-active-directory "Direct link to LDAP and Active Directory") To federate users from an LDAP directory, add an LDAP provider under *User federation* in the `cryptomator` realm and enter the connection URL, the bind credentials, and the base DN of your directory. The [Keycloak documentation on LDAP](https://www.keycloak.org/docs/latest/server_admin/#_ldap) describes the individual settings. Hub additionally requires two mappers on the LDAP provider: 1. Add a *group-ldap-mapper* so that directory groups are imported into Keycloak. Without it, only users are synchronized and you cannot assign vault permissions to groups. 2. Add a *hardcoded-ldap-role-mapper* that assigns the realm role `user` to every imported user. Users without this role cannot log in to Hub. Once both mappers are in place, run *Sync all users* on the LDAP provider. Afterwards, verify the setup by logging in to Hub — not Keycloak — with one of the imported accounts. ### Using the Identity Provider as Default Login[​](#using-the-identity-provider-as-default-login "Direct link to Using the Identity Provider as Default Login") By default, Keycloak shows a login form with the external provider as an additional button. You can skip that screen and redirect users straight to your provider by entering its alias as the default identity provider in the browser authentication flow, as described in the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/index.html#default_identity_provider). warning Once the login form is hidden, local accounts can no longer sign in through the regular flow. Make sure at least one account that you can reach through the external provider holds the `admin` role, otherwise you lock yourself out of Keycloak administration. ### Skipping the Account Creation Screen[​](#skipping-the-account-creation-screen "Direct link to Skipping the Account Creation Screen") When a user logs in through an external provider for the first time, Keycloak asks them to review and confirm their profile. To remove this step: 1. Select *Authentication* in the left panel. 2. Click the three dots next to *first broker login* and choose *Duplicate*. Give the copy a descriptive name such as `first oidc broker login`. 3. Open the duplicated flow and set *Review Profile* in the first section to *Alternative*. 4. Select *Identity providers* in the left panel and open your identity provider. 5. Scroll down to *First login flow*, select the duplicated flow, and save. ### Customizing the Username[​](#customizing-the-username "Direct link to Customizing the Username") Keycloak derives the username of brokered accounts from the email address reported by the identity provider. If you need a different scheme, add a *Username Template Importer* mapper to your identity provider and set its target to `LOCAL`. The template describes how the username is composed. For example, `${ALIAS}.${CLAIM.sub}` uses the alias of the identity provider, a dot, and the `sub` claim of the token. Keycloak currently supports the modifiers `toUpperCase`, `toLowerCase`, and `getEmailLocalPart`. Regular expressions are [not yet implemented](https://github.com/keycloak/keycloak/issues/10107). The mapper takes effect the next time the affected user logs in. ## Restricting Access to Hub[​](#restricting-access-to-hub "Direct link to Restricting Access to Hub") If your identity provider serves more people than should have access to Hub, you can filter them out at the point where Keycloak accepts the external login. Open your identity provider in the `cryptomator` realm, enable *Verify essential claim*, and enter the claim name and the value that identifies an authorized user. Logins that do not carry this claim are rejected before the account is created, so unauthorized users never show up in Hub and never consume a license seat. Users who are turned away see an error screen after logging in with their external credentials. If your identity provider is a Keycloak instance as well, create the claim as follows: 1. Create a client role for Hub in the identity provider's realm. 2. Open *Client scopes* and select the client's *dedicated* scope. 3. Add a *User Client Role* mapper and make sure *Add to ID token* is enabled. Without it, the claim never reaches Hub's Keycloak. 4. Assign the client role to every user or group that should have access to Hub. ## Session Timeouts[​](#session-timeouts "Direct link to Session Timeouts") Keycloak offers a large number of [timeouts](https://www.keycloak.org/docs/latest/server_admin/#_timeouts). Three of them determine how long users stay signed in to Hub. *Access Token Lifespan* defines how long an issued token remains valid and therefore how often Hub refreshes it in the background. *SSO Session Idle* defines how long a session survives without any token refresh, for example while the browser is closed. *SSO Session Max* is the absolute upper bound after which the user is signed out regardless of activity. An example makes the interaction clearer. With an access token lifespan of 10 seconds and an SSO session idle of 30 seconds, closing the browser tab for 20 seconds and reopening it yields a new token. Closing it for 40 seconds signs the user out, because the session expired while no refresh happened. tip If users complain about being signed out too often, *SSO Session Idle* is usually the setting to increase. ## Migrating to Another Identity Provider[​](#migrating-to-another-identity-provider "Direct link to Migrating to Another Identity Provider") Hub identifies users by the IDs that Keycloak assigns to them, and vault permissions are bound to those IDs. When you switch from one identity provider to another, you therefore have to link the new external identity to the existing Keycloak account instead of creating a new one. Done correctly, users keep their vault access and do not have to set up their account again. ### Linking Accounts Manually[​](#linking-accounts-manually "Direct link to Linking Accounts Manually") If you know the user ID and the username in the new identity provider, open the existing user in Keycloak, switch to *Identity provider links*, and add the link directly. The same can be done through the [Keycloak Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/index.html#FederatedIdentityRepresentation), which is the better option for larger user bases. ### Linking Accounts During Login[​](#linking-accounts-during-login "Direct link to Linking Accounts During Login") Users can also link their own accounts. When someone logs in through the new provider with an email address that already exists in Keycloak, Keycloak offers to add the login to the existing account. Choosing *Add existing account* prompts them to authenticate once with the old provider, after which both identities point to the same account. If the old provider has already been shut down, set a password on the affected accounts beforehand. Users can then confirm the link with username and password instead of the old provider. When the account has a verified email address, confirmation by email works as well; both alternatives are reachable through *Try Another Way* on the login screen. ### Forcing the Migration[​](#forcing-the-migration "Direct link to Forcing the Migration") As long as both providers are offered on the login screen, nothing stops users from continuing to sign in with the old one, and their accounts are never migrated. Set the new provider as the [default identity provider](#using-the-identity-provider-as-default-login) to send everyone through the new login and trigger the linking automatically. Once every account is linked, you can remove the old identity provider from the realm. --- # License Every Cryptomator Hub instance requires a license. The license is bound to the instance and cannot be transferred to another instance. Every license has a number of seats and a validity period. As an Hub administrator, you can view license information in the administration area. ![Administration area](/img/hub/admin-area-license.png) ## What Is a Seat?[​](#what-is-a-seat "Direct link to What Is a Seat?") A regular license contains a fixed number of *seats*. A *seat* is taken for every user, which is assigned to at least one, not-archived vault. Note that: * If a user is not assigned to any vault, it *does not occupy* a seat. * If a user is assigned to multiple vaults, it only *occupies one* seat. * If [a user is created or imported to Hub](/hub/admin-guide/user-group-management/.md), it does not occupy a seat. note Enterprise licenses can have an unlimited number of seats. Visit [cryptomator.org](https://cryptomator.org/for-teams/?utm_source=docs.cryptomator.org\&utm_medium=referral\&utm_campaign=admin) for more information. ## Community License[​](#community-license "Direct link to Community License") When you deploy Cryptomator Hub by yourself, it comes with a community license with life-long validity and 5 seats. ## Updating Your License[​](#updating-your-license "Direct link to Updating Your License") If the community license is not sufficient for your needs, you can upgrade it to a paid license. You can also upgrade an already existing, paid license. To do so, click on the button in the lower right corner of the administration area. It will redirect you to the Cryptomator Hub license store. After the purchase, you will be automatically redirected back to your Hub instance. --- # Quick Start This guide walks you through setting up a fresh Cryptomator Hub instance for your organization in about **20 minutes**. As a worked example, meet Alice: she administers Hub at the design agency Acme. Her instance is up and running, and now she adds her first users and a group, connects the company's identity provider, enables Emergency Access, and checks the audit log and license. ## Before You Start[​](#before-you-start "Direct link to Before You Start") You need: * A running Hub instance — a local test instance from the [Quick Start](/hub/self-hosting-guide/quick-start/.md) or a server deployment (managed or selfhosted) * An account with the `admin` [role](/hub/admin-guide/user-group-management/.md#roles), such as the initial admin account created during deployment. tip Not keen on hosting an instance yourself? Cryptomator Hub is also available as a [managed service](https://cryptomator.org/hub/managed/?utm_source=docs.cryptomator.org\&utm_medium=referral\&utm_campaign=admin-guide) with a free 30-day trial period — this guide applies there all the same. ## Add Users and Groups[​](#add-users-and-groups "Direct link to Add Users and Groups") Since version 2.0, users and groups are managed directly in Hub, via the `Users` and `Groups` entries in the sidebar. Alice creates accounts for Bob and Carol, each with username, email, and an initial password. She then creates the group *Designers* and adds both as members — sharing vaults with a group scales better than managing individual permissions. ![Create user form](/img/hub/user-create.png) Bob and Carol can now log in and complete their account setup, as described in the [User Guide](/hub/user-guide/quick-start/.md#set-up-your-account). For more details, read [Create User](/hub/admin-guide/user-group-management/.md#create-user), [Create Group](/hub/admin-guide/user-group-management/.md#create-group), and [Manage Group Members](/hub/admin-guide/user-group-management/.md#manage-group-members). ## Connect Your Identity Provider[​](#connect-your-identity-provider "Direct link to Connect Your Identity Provider") Creating users by hand is fine for a handful of people. Since Acme already manages its staff in a central directory, Alice instead connects Hub's bundled Keycloak to it, so users log in with their existing credentials and accounts stay in sync. ![Accessing Keycloak via Hub](/img/hub/access-keycloak-link.png) The `Manage Keycloak` link takes Alice to the Keycloak admin console, where identity providers are configured on the `Identity providers` page: ![Identity providers in the Keycloak admin console](/img/hub/keycloak-identity-providers.png) Depending on what your organization runs, follow the matching reference section: * [OpenID Connect](/hub/admin-guide/keycloak/.md#openid-connect) providers such as Microsoft Entra ID or Google Workspace. * [LDAP and Active Directory](/hub/admin-guide/keycloak/.md#ldap-and-active-directory) for user federation. * [Mapping groups to roles](/hub/admin-guide/keycloak/.md#mapping-groups-to-roles), e.g. to grant an *IT* directory group the `admin` role automatically. For more details, read [Connecting an External Identity Provider](/hub/admin-guide/keycloak/.md#connecting-an-external-identity-provider) and [External Identity Management](/hub/admin-guide/user-group-management/.md#enterprise-external-iam). ## Enable Emergency Access[​](#enable-emergency-access "Direct link to Enable Emergency Access") What if Bob leaves Acme and the *Client Projects* vault has no other owner? Emergency Access, new in version 2.0, lets a council of trusted users jointly restore access to a vault. Alice enables it in the admin area and defines a default council, so every new vault gets Emergency Access conditions during creation. For existing vaults, owners set up the council in the vault details. ![Emergency Access](/img/hub/admin-emergency-access.png) Enterprise Feature Emergency Access is available as an Enterprise feature. Visit [cryptomator.org](https://cryptomator.org/hub/) for more information. For more details, read [Emergency Access admin settings](/hub/admin-guide/emergency-access/.md#admin-settings), [Set Up Emergency Access](/hub/admin-guide/emergency-access/.md#set-up-emergency-access), and the per-vault [Emergency Access Council](/hub/user-guide/vault-management/.md#emergency-access-council). ## Review the Audit Log[​](#review-the-audit-log "Direct link to Review the Audit Log") The next morning, Alice verifies that everything went as intended. In the audit log, she filters for vault events and sees the creation of *Client Projects* and the access grants for Carol and the *Designers* group, each with actor and timestamp. ![Audit Logs Table View](/img/hub/auditlogs-overview.png) For more details, read [Audit Logs](/hub/admin-guide/audit-logs/.md), [Filtering Audit Logs](/hub/admin-guide/audit-logs/.md#filtering-audit-logs), and the list of [Event Types](/hub/admin-guide/audit-logs/.md#event-types). ## Check Your License[​](#check-your-license "Direct link to Check Your License") Finally, Alice opens the license section of the admin area. With Bob and Carol having vault access, two seats are in use — a seat is occupied by every user who is assigned to at least one vault. The overview shows the used and licensed seats and where to upgrade before the team grows. ![Administration area](/img/hub/admin-area-license.png) For more details, read [License](/hub/admin-guide/license/.md), [What Is a Seat?](/hub/admin-guide/license/.md#what-is-a-seat), and [Updating Your License](/hub/admin-guide/license/.md#updating-your-license). ## Next Steps[​](#next-steps "Direct link to Next Steps") * Set up [backups](/hub/self-hosting-guide/operations/.md#backup) before real data accumulates. * Harden logins with [session timeouts](/hub/admin-guide/keycloak/.md#session-timeouts) and [access restrictions](/hub/admin-guide/keycloak/.md#restricting-access-to-hub). * Send your team the [User Guide](/hub/user-guide/.md) so they can get started on their own. --- # User & Group Management Users and groups are managed directly in the Cryptomator Hub admin interface. As an administrator, you can create, edit, and delete users and groups, assign roles, and manage group memberships. Access the user and group management from the navigation bar in the admin area. ## User Management[​](#user-management "Direct link to User Management") ### User List[​](#user-list "Direct link to User List") The user list displays all users in your Hub instance. You can search for users by name or email and see key metrics for each user: * Number of accessible **vaults** * Number of **group** memberships * Number of registered **devices** ![User list overview.](/img/hub/user-list.png) ### Create User[​](#create-user "Direct link to Create User") To create a new user, click the "Create User" button in the user list. Fill in the following fields: * **Profile Picture URL**: Optional URL to a profile picture * **First Name**: The user's first name * **Last Name**: The user's last name * **Username**: A unique identifier for the user (cannot be changed later) * **Email**: The user's email address * **Roles**: Assign roles to the user (see [Roles](#roles)) * **Password**: Set an initial password for the user ![Create user form](/img/hub/user-create.png) After creation, the user can log in with their credentials and complete the [account setup](/hub/user-guide/your-account/.md#account-setup). ### User Details[​](#user-details "Direct link to User Details") The user detail page shows comprehensive information about a user: * **Groups**: All groups the user is a member of * **Accessible Vaults**: Vaults the user has access to (directly or through group membership) * **Devices**: All registered devices of the user * **Legacy Devices**: Devices registered with older Hub versions (see [Legacy Devices](/hub/user-guide/your-account/.md#legacy-devices)) ![User detail view](/img/hub/user-detail.png) ### Edit User[​](#edit-user "Direct link to Edit User") To edit a user, navigate to the user's detail page and click "Edit". You can modify: * Profile Picture URL * First Name * Last Name * Email * Roles * Password (set a new password) note Username cannot be changed after user creation. ### Delete User[​](#delete-user "Direct link to Delete User") To delete a user, you can either click the delete button in the user list or navigate to the user's detail page and click on the options button next to the "Edit" button, then select "Delete". A confirmation dialog will appear. Deleting a user will: * Remove the user from all groups * Revoke access to all vaults * Delete all registered devices warning This action cannot be undone. ## Group Management[​](#group-management "Direct link to Group Management") Groups allow you to organize users and grant vault access to multiple users at once. ### Group List[​](#group-list "Direct link to Group List") The group list displays all groups with: * Number of **members** * Number of accessible **vaults** ![Group list overview](/img/hub/group-list.png) ### Create Group[​](#create-group "Direct link to Create Group") To create a new group, click the "Create Group" button. Fill in: * **Profile Picture URL**: Optional URL to a group picture * **Name**: A descriptive name for the group ![Create group form](/img/hub/group-create.png) ### Edit Group[​](#edit-group "Direct link to Edit Group") To edit a group, navigate to the group's detail page and click "Edit". You can modify the group name and profile picture URL. ### Delete Group[​](#delete-group "Direct link to Delete Group") To delete a group, you can either click the delete button in the group list or navigate to the group's detail page and click on the options button next to the "Edit" button, then select "Delete". A confirmation dialog will appear. Deleting a group will: * Remove all members from the group * Revoke group-based vault access (users may still have direct access) warning This action cannot be undone. ### Group Details[​](#group-details "Direct link to Group Details") The group detail page shows: * **Members**: All users who are members of this group * **Accessible Vaults**: Vaults the group has access to ![Group detail view](/img/hub/group-detail.png) ### Manage Group Members[​](#manage-group-members "Direct link to Manage Group Members") From the group detail page, you can: * **Add Members**: Click "Add Member" to search for and add users to the group * **Remove Members**: Click the remove button next to a member to remove them from the group ![Add member dialog](/img/hub/group-add-member.png) note Subgroups are not supported. ## Roles[​](#roles "Direct link to Roles") There are three roles in Cryptomator Hub: | Role | Description | | ---------------- | ----------------------------------------------------------- | | **user** | Default role. Can open vaults and manage their own account. | | **admin** | Can manage users and groups and view audit logs. | | **create-vault** | Allows users to create new vaults. | Roles are assigned when creating or editing a user. The `user` role is assigned by default to all users. ## User Avatars[​](#user-avatars "Direct link to User Avatars") Users can have profile pictures displayed throughout Hub (e.g., in vault member lists). As an administrator, you can set the profile picture URL when creating or editing a user. The avatar can be provided as a URL to an image (e.g., `https://example.com/avatar.png`). If no profile picture is set, a generated avatar based on the user's name will be displayed. ## External Identity Management[​](#enterprise-external-iam "Direct link to External Identity Management") Instead of managing users and groups directly in Hub, you can connect Cryptomator Hub to an external identity provider (LDAP, Active Directory, OpenID Connect, or SAML) so users authenticate with the credentials they already have. See [Identity Provider](/hub/admin-guide/keycloak/.md) for how to connect and manage an external identity provider. --- # Web of Trust The Web of Trust (WoT) feature in Cryptomator Hub helps users verify each other's identity by signing the [User Key Pair](/security/hub/.md#user-key-pair) with their private keys using ECDSA. First, the trusting user needs to verify the trustee by entering the first characters of the trustee's public key fingerprint. Once signed, the proof is uploaded to Hub, where others can check its authenticity. WoT also supports transitive trust, meaning if Alice trusts Bob, and Bob trusts Charlie, then Alice implicitly trusts Charlie. This forms a trust chain, allowing users to establish indirect trust relationships. ![Web of Trust Administration](/img/hub/wot-admin.png) **In the administration area, administrators can configure the following trust settings:** The maximum depth of such chains can be configured using the **Maximum WoT Depth** property: * The default value is 3 ("Great-Grandchild") * The maximum value is 9 * The minimum value, 0, means no trust chain is allowed, only direct trust relationships are considered. With the **Fingerprint Verification Preciseness** property, the minimum length of the entered public key fingerprint can be configured: * The default value is 2 * The minimum value, 0, means the fingerprint of the trustee is fully shown without any input needed. note For how a user verifies another user's identity, see [Web of Trust](/hub/user-guide/vault-management/.md#web-of-trust) in the User Guide. note If a user resets their account, their [User Key Pair](/security/hub/.md#user-key-pair) is regenerated, invalidating all previously established trust relationships regarding this user.
Additionally, any existing trust chains that included the user will be broken, requiring re-verification to restore trust. --- ![Cryptomator Hub connects team members](/img/hub/hub-intro.png) # Cryptomator Hub **Cryptomator Hub** adds *zero-knowledge key management* for teams and organizations to Cryptomator, ensuring your confidential data stays confidential - without sharing any passwords. It is GDPR-compliant, offers access management and easily integrates into your existing identity management incl. OpenID Connect, SAML, and LDAP. As usual, your favorite cloud service remains your free choice. This documentation is organized into three guides, one per role. Pick the one that matches what you want to do: …if you **use** Hub, start with the [User Guide](/hub/user-guide/.md): * [Quick Start](/hub/user-guide/quick-start/.md) - a walkthrough from your first login to an unlocked vault. * [Your Account](/hub/user-guide/your-account/.md) - how to manage your own account. * [Managing Vaults](/hub/user-guide/vault-management/.md) - how to create, share, and recover vaults. * [Working with Vaults](/hub/user-guide/access-vault/.md) - how to use Hub vaults with Cryptomator apps to encrypt your data. …if you **administer** Hub, start with the [Admin Guide](/hub/admin-guide/.md): * [Quick Start](/hub/admin-guide/quick-start/.md) - a walkthrough of your first day as a Hub administrator. * [User & Group Management](/hub/admin-guide/user-group-management/.md) - how to manage users and groups. * [Identity Provider](/hub/admin-guide/keycloak/.md) - how to connect your existing OpenID Connect, SAML, or LDAP directory. * [Emergency Access](/hub/admin-guide/emergency-access/.md) - how a council can restore access to a vault. * [License](/hub/admin-guide/license/.md) - how to manage your Hub license. …if you **host** Hub yourself, start with the [Self-Hosting Guide](/hub/self-hosting-guide/.md): * [Quick Start](/hub/self-hosting-guide/quick-start/.md) - a walkthrough from playground to production deployment. * [Deployment Cookbook](/hub/self-hosting-guide/deployment/.md) - recipes for Docker Compose, Kubernetes, and Rancher. * [Operations](/hub/self-hosting-guide/operations/.md) - how to back up, restore, and maintain your Hub instance. --- # New Features **Cryptomator Hub 2.0.0** introduces the following new features: * [User & Group Management](/hub/admin-guide/user-group-management/.md) — Manage users, groups, roles, and permissions directly in Hub * [Emergency Access](/hub/admin-guide/emergency-access/.md) — Restore access to a vault in case of account loss or ownership issues The [Admin Guide](/hub/admin-guide/quick-start/.md) walks through both features in a worked example: see [Add Users and Groups](/hub/admin-guide/quick-start/.md#add-users-and-groups) and [Enable Emergency Access](/hub/admin-guide/quick-start/.md#enable-emergency-access). --- # Self-Hosting Guide This guide is for everyone who runs a Cryptomator Hub instance on their own infrastructure. It covers a local test instance, the way from there to production, and the maintenance tasks that follow. If you want to see Hub in action first, start with the [Quick Start](/hub/self-hosting-guide/quick-start/.md). It gets a test instance running on your machine in about 10 minutes and then continues to production. ## [📄️Quick Start](/hub/self-hosting-guide/quick-start/.md) [Want to see Cryptomator Hub in action before rolling it out to your team? This guide gets a test instance running on your own machine in about 10 minutes. No domain, no TLS certificates, no reverse proxy.](/hub/self-hosting-guide/quick-start/.md) ## [🗃Deployment Cookbook](/hub/self-hosting-guide/deployment/.md) [3 items](/hub/self-hosting-guide/deployment/.md) ## [📄️Operations](/hub/self-hosting-guide/operations/.md) [All state of Cryptomator Hub lives in the PostgreSQL database: the hub database holds vaults, keys, and the audit log, the keycloak database holds users, groups, and credentials. Back up both, and always do so before upgrading. For an end-to-end walkthrough from deployment to backups, see Going to Production.](/hub/self-hosting-guide/operations/.md) --- # Deployment Cookbook This section collects recipes for running Cryptomator Hub in production. If you just want to try Hub, start with the [Quick Start](/hub/self-hosting-guide/quick-start/.md) instead. For an end-to-end walkthrough from deployment to backups, see [Going to Production](/hub/self-hosting-guide/quick-start/.md#going-to-production). tip Cryptomator Hub is also offered as a hosted solution, including 99.5%-uptime guarantee and regular backups! Visit [cryptomator.org](https://cryptomator.org/for-teams/) for more information. ## Before You Begin[​](#before-you-begin "Direct link to Before You Begin") Whichever recipe you follow, decide on these up front: * **Public URLs.** Hub and Keycloak each need one, either as two hostnames (`https://hub.example.com`, `https://kc.example.com`) or as two paths on one host (`https://example.com/hub`, `https://example.com/kc`). Create the DNS records before you deploy. * **TLS termination.** Hub, Keycloak, and PostgreSQL speak plain HTTP and plain PostgreSQL protocol. Their ports must never be published directly; the only component listening on a public interface is your TLS-terminating reverse proxy or ingress controller. * **Bundled or existing services.** Every recipe can run Keycloak and PostgreSQL for you, or connect to instances you already operate, e.g. your organization's SSO. See [example](https://github.com/cryptomator/hub/tree/2.0.0/deploy/helm/existing-keycloak). important Keycloak creates Hub's realm, including the redirect URIs derived from your public URLs, only on its **first** start. Decide on the final URLs before deploying. Changing them later means editing the `cryptomatorhub` client in the Keycloak admin console (*Clients → cryptomatorhub → Valid redirect URIs*) in addition to updating the deployment. Otherwise, login fails with `Invalid parameter: redirect_uri`. ## Recipes[​](#recipes "Direct link to Recipes") ## [📄️Rancher](/hub/self-hosting-guide/deployment/rancher/.md) [Install the Helm chart through the Rancher UI.](/hub/self-hosting-guide/deployment/rancher/.md) ## [📄️Kubernetes](/hub/self-hosting-guide/deployment/kubernetes/.md) [Install the Helm chart with the Helm CLI.](/hub/self-hosting-guide/deployment/kubernetes/.md) ## [📄️Docker Compose](/hub/self-hosting-guide/deployment/compose/.md) [Run Hub on a single Docker host behind Traefik.](/hub/self-hosting-guide/deployment/compose/.md) Once Hub is running, see [Operations](/hub/self-hosting-guide/operations/.md) for backups, restores, and other maintenance tasks. ## Sizing[​](#sizing "Direct link to Sizing") The defaults of the Compose example and the Helm chart target a small installation: | Service | Memory | Notes | | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Hub | 64 MiB | Native binary, no JVM | | Keycloak | 512 MiB requested, 1 GiB limit | JVM; heap is 70% of the limit. Raise the limit for larger user bases, see Keycloak's [sizing guide](https://www.keycloak.org/high-availability/concepts-memory-and-cpu-sizing). | | PostgreSQL | 256 MiB, 2 GiB storage | Serves only Hub and Keycloak | Startup and realm import of Keycloak are CPU-heavy; avoid strict CPU limits on it. --- # Docker Compose We maintain example Compose files in the [Hub repository](https://github.com/cryptomator/hub/tree/develop/deploy/compose). The production example runs Hub, Keycloak, and PostgreSQL behind a [Traefik](https://traefik.io/) reverse proxy that obtains a TLS certificate from Let's Encrypt. ## Prerequisites[​](#compose-prerequisites "Direct link to Prerequisites") * Docker with Docker Compose 2.23.1 or newer (`docker compose version`). * Ports 80 and 443 of the host reachable from the internet (Let's Encrypt HTTP challenge) and from your users. * DNS records for the Hub and Keycloak hostnames pointing to the host. ## Deploy[​](#compose-deploy "Direct link to Deploy") Download the production example into an empty directory: ``` curl -fsSLO https://raw.githubusercontent.com/cryptomator/hub/2.0.0/deploy/compose/prod/compose.yaml ``` Open `compose.yaml` and replace every placeholder before starting the stack: 1. The two public hostnames, in all places they appear (see [Configuration](#compose-configuration)). 2. The email address for Let's Encrypt. 3. All passwords and secrets: the PostgreSQL admin password, the database passwords of `hub` and `keycloak`, the Keycloak bootstrap admin password, the Hub admin password, and the secret of the `cryptomatorhub-system` client. Generate them, e.g. with `openssl rand -hex 32`. Then start everything: ``` docker compose up -d ``` Keycloak takes a minute or two on first start to import the realm. Once all services are healthy, open the Hub URL, sign in as `admin` with the password you chose, and enter your license. ## Configuration[​](#compose-configuration "Direct link to Configuration") You can find a reference table of all settings alongside the example in [the project's GitHub repository](https://github.com/cryptomator/hub/tree/2.0.0/deploy/compose/prod). Never publish service ports Traefik is the only service in the example with a `ports:` section. Do not add `ports:` to `hub`, `keycloak`, or `postgres`, not even "just for testing" or bound to a non-standard port. Doing so exposes unencrypted logins, tokens, and the database to the network. Traefik reaches the services over the internal Compose network; if you need to inspect a service, use `docker compose exec` or an SSH tunnel instead. ## Upgrading[​](#compose-upgrading "Direct link to Upgrading") [Back up the database](/hub/self-hosting-guide/operations/.md#backup) first. Image versions are pinned in `compose.yaml`; to upgrade, change the tags and run `docker compose up -d`. Hub applies its database migrations automatically at start. For Keycloak, follow the [Keycloak upgrade guide](https://www.keycloak.org/docs/latest/upgrading/). PostgreSQL minor updates (e.g. `18.6` → `18.7`) are drop-in. A major update (`18` → `19`) is not: the data directory must be migrated with `pg_upgrade` or a dump and restore, see the [PostgreSQL upgrade notes](https://www.postgresql.org/docs/current/upgrading.html). --- # Kubernetes The Helm chart `oci://ghcr.io/cryptomator/charts/cryptomator-hub` deploys Hub together with an optional Keycloak and PostgreSQL. Passwords you don't set are generated on install and stored in Kubernetes Secrets. All values are documented in the chart's [`values.yaml`](https://github.com/cryptomator/hub/blob/develop/chart/values.yaml) and validated against a schema. Using Rancher? The same chart can be installed through its UI, see [Rancher](/hub/self-hosting-guide/deployment/rancher/.md). ## Prerequisites[​](#kubernetes-prerequisites "Direct link to Prerequisites") * A Kubernetes cluster, version 1.27 or newer. * A **Traefik** ingress controller (bundled with K3s, for example). nginx is supported as well, see [Configuration](#kubernetes-configuration); the examples below assume Traefik. * A default StorageClass; the bundled PostgreSQL needs one `ReadWriteOnce` volume. * DNS records for the two hostnames pointing at the ingress controller. * For TLS: [cert-manager](https://cert-manager.io/) with a `ClusterIssuer`, or an existing TLS secret. See [Configuration](#kubernetes-configuration) for alternatives. * `kubectl` and Helm 3.8 or newer (OCI support). ## Install[​](#kubernetes-install "Direct link to Install") ``` helm install hub oci://ghcr.io/cryptomator/charts/cryptomator-hub --version 2.0.0 \ --namespace cryptomator --create-namespace \ --set urls.hub.public=https://hub.example.com \ --set urls.kc.public=https://kc.example.com \ --set ingress.controller=traefik \ --set ingress.certificate.clusterIssuer=letsencrypt ``` Helm prints the service names and the commands to retrieve the generated passwords. Wait until all pods are ready; Keycloak needs a minute on first start to import Hub's realm: ``` kubectl get pods -n cryptomator -w ``` Then retrieve the two admin passwords: ``` # Hub admin (realm user `admin`; the password must be changed on first login) kubectl get secret -n cryptomator hub-secrets-hub -o jsonpath='{.data.hub_admin_password}' | base64 -d && echo # Keycloak bootstrap admin (`admin`) kubectl get secret -n cryptomator hub-secrets-kc -o jsonpath='{.data.kc_admin_password}' | base64 -d && echo ``` Open `https://hub.example.com`, sign in as `admin`, set a new password, and enter your license. Users and groups are managed in Keycloak at `https://kc.example.com`; Hub syncs them every 5 minutes (`hub.config.keycloakSyncerPeriod`). ## Configuration[​](#kubernetes-configuration "Direct link to Configuration") You can find a reference table of all settings alongside the chart in [the project's GitHub repository](https://github.com/cryptomator/hub/tree/2.0.0/deploy/helm/prod). Never expose service ports Leave `hub.service.type`, `keycloak.service.type`, and `postgres.service.type` at `ClusterIP`. Setting them to `NodePort` or `LoadBalancer` exposes unencrypted logins, tokens, and the database to the network. The ingress controller is the only entry point; if you need to inspect a service, use `kubectl port-forward` instead. ## Upgrading and Uninstalling[​](#kubernetes-upgrading "Direct link to Upgrading and Uninstalling") [Back up the database](/hub/self-hosting-guide/operations/.md#backup) first, then: ``` helm upgrade hub oci://ghcr.io/cryptomator/charts/cryptomator-hub --version \ --namespace cryptomator --reuse-values ``` Hub applies its schema migrations at start; generated passwords are re-read from the existing Secrets, so they stay stable across upgrades. `helm uninstall hub -n cryptomator` removes the workloads and Secrets but keeps the PVC `data-hub-pg-0`; delete it explicitly if you want the data gone. --- # Rancher Rancher installs the same Helm chart as the [Kubernetes](/hub/self-hosting-guide/deployment/kubernetes/.md) path, but through a guided form instead of the Helm CLI. The chart ships a `questions.yaml`, so the form asks only for what you have to decide; everything else keeps its default. ## Prerequisites[​](#rancher-prerequisites "Direct link to Prerequisites") * Rancher 2.9 or newer (required for OCI chart repositories). * Traefik or Nginx as ingress controller and a way to obtain TLS certificates. * A default StorageClass ## Install[​](#rancher-install "Direct link to Install") 1. Add the chart repository once: go to *Apps → Repositories → Create*, choose the OCI type, and enter `oci://ghcr.io/cryptomator/charts`. 2. Go to *Apps → Charts*, select *Cryptomator Hub*, and click *Install*. 3. Click *Install* and wait until all workloads are active. Keycloak needs a minute on first start to import Hub's realm. Advanced Configuration Everything the form does not ask for is available in the *Edit YAML* view, see the [reference table](https://github.com/cryptomator/hub/tree/2.0.0/deploy/helm/prod). Generated passwords appear under *Storage → Secrets* in the release namespace: `hub-secrets-hub` holds the Hub admin password, `hub-secrets-kc` the Keycloak bootstrap admin password, `hub-secrets-pg` the database passwords. Open the Hub URL, sign in as `admin`, set a new password, and enter your license. ## Upgrading[​](#rancher-upgrading "Direct link to Upgrading") [Back up the database](/hub/self-hosting-guide/operations/.md#backup) first. Then go to *Apps → Installed Apps*, select the release, click *Upgrade*, and choose the new chart version. Your values are kept; generated passwords stay stable across upgrades. --- # Operations All state of Cryptomator Hub lives in the PostgreSQL database: the `hub` database holds vaults, keys, and the audit log, the `keycloak` database holds users, groups, and credentials. Back up both, and always do so before upgrading. For an end-to-end walkthrough from deployment to backups, see [Going to Production](/hub/self-hosting-guide/quick-start/.md#going-to-production). ## Backup[​](#backup "Direct link to Backup") The easiest way is a logical dump of the entire PostgreSQL instance with `pg_dumpall`, run regularly, e.g. from a cron job on the host. Docker Compose: ``` docker compose exec -u postgres postgres pg_dumpall > "$(date +%F)-hub-backup.sql" ``` Kubernetes: ``` kubectl exec -n cryptomator hub-pg-0 -- pg_dumpall -U postgres > "$(date +%F)-hub-backup.sql" ``` On Kubernetes you can alternatively snapshot the volume `data-hub-pg-0` with your storage provider. See the [PostgreSQL documentation](https://www.postgresql.org/docs/current/app-pg-dumpall.html) for more information on `pg_dumpall`. If you also back up your `compose.yaml` or Helm values, you can restore the entire installation in minutes. note Make sure the backup is moved to another secure location. ## Restore[​](#restore "Direct link to Restore") To bring a Hub deployment back to the state of a backup, replace the `hub` database with the contents of the dump. The following steps use Docker Compose; the Kubernetes equivalents are noted where they differ. 1. Create a fresh backup of the entire PostgreSQL instance, including the Keycloak database, so that you can return to the current state if something goes wrong. 2. Stop Hub with `docker compose stop hub`. Keycloak and PostgreSQL keep running. (Kubernetes: `kubectl scale -n cryptomator deployment/hub-hub --replicas=0`) 3. Connect to PostgreSQL with `docker compose exec -ti postgres psql -U postgres`. (Kubernetes: `kubectl exec -ti -n cryptomator hub-pg-0 -- psql -U postgres`) 4. Rename the existing database with `ALTER DATABASE hub RENAME TO hub_backup;` so that it remains available as an additional safety net. 5. Create an empty database with `CREATE DATABASE hub WITH ENCODING 'UTF8'; GRANT ALL PRIVILEGES ON DATABASE hub TO hub;` and leave the shell with `exit`. 6. Import the dump with `docker compose exec -T postgres psql -U hub -d hub -v ON_ERROR_STOP=1 < backup.sql`. (Kubernetes: `kubectl exec -i -n cryptomator hub-pg-0 -- psql -U hub -d hub -v ON_ERROR_STOP=1 < backup.sql`) 7. Start Hub again with `docker compose start hub`. (Kubernetes: `kubectl scale -n cryptomator deployment/hub-hub --replicas=1`) Once you have confirmed that Hub works as expected, you can drop the `hub_backup` database. warning Hub and Keycloak reference each other by user ID. If you restore the Hub database from a backup, restore the Keycloak database from the same point in time as well. Otherwise users may exist in one system but not in the other. ## Changing the Database Password[​](#changing-the-database-password "Direct link to Changing the Database Password") Change the password in Postgres first, then update the deployment. Connect to the Postgres container with `docker compose exec -it postgres /bin/sh` or `kubectl exec -it hub-pg-0 -n cryptomator -- /bin/sh`, open the database with `psql -h localhost -d hub -U hub`, and run `\password` to set a new password for the Hub database user. Afterwards, set the new password in your deployment and restart Hub: the environment variable `QUARKUS_DATASOURCE_PASSWORD` in `compose.yaml`, or `hub.database.password` on `helm upgrade`. note Keycloak uses its own database user. Changing the Hub password does not affect it. ## Verifying Container Images[​](#verifying-container-images "Direct link to Verifying Container Images") The Hub and Keycloak container images are published together with build provenance attestations, which allow you to confirm that an image was built by the official GitHub Actions workflow and has not been tampered with. The following example verifies the Keycloak image using [regctl](https://github.com/regclient/regclient) and [cosign](https://github.com/sigstore/cosign): ``` KC_VERSION=26.7.2 regctl manifest get --format raw-body ghcr.io/cryptomator/keycloak:${KC_VERSION} > manifest.json DIGEST="sha256-$(sha256sum manifest.json | awk '{ print $1 }')" regctl artifact get ghcr.io/cryptomator/keycloak:${DIGEST} > bundle.json cosign verify-blob-attestation \ --bundle bundle.json \ --new-bundle-format \ --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \ --certificate-identity-regexp="^https://github.com/cryptomator/hub/.github/workflows/keycloak.yml@refs/heads/release/keycloak-${KC_VERSION}" \ manifest.json ``` A successful run prints `Verified OK`. The Hub image itself is attested by the `build.yml` workflow of the same repository. To verify it, use the corresponding image name and adjust `--certificate-identity-regexp` to that workflow and the Git reference the release was built from. The Helm chart is signed as well. Verify the signature and inspect the provenance attestation with: ``` cosign verify \ --certificate-identity-regexp 'https://github.com/cryptomator/hub/.github/workflows/helm-chart.yml@refs/(heads|tags)/.+' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ ghcr.io/cryptomator/charts/cryptomator-hub:2.0.0 cosign verify-attestation \ --type https://slsa.dev/provenance/v1 \ --certificate-identity-regexp 'https://github.com/cryptomator/hub/.github/workflows/helm-chart.yml@refs/(heads|tags)/.+' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ ghcr.io/cryptomator/charts/cryptomator-hub:2.0.0 ``` ## Trusting a Private Certificate Authority[​](#trusting-a-private-certificate-authority "Direct link to Trusting a Private Certificate Authority") If Hub connects to a Keycloak instance whose TLS certificate was not issued by a well-known certificate authority, you have to make the issuing CA known to Hub. Hub runs on the JVM, which uses its own trust store and ignores the certificates trusted by the host system. Start by preparing a file `rootWithIntermediates.pem` that contains the root certificate and all intermediate certificates that are not publicly available, in PEM format. Then create a PKCS12 trust store from it: ``` keytool -importcert \ -alias keycloak-ca-chain \ -file rootWithIntermediates.pem \ -keystore keycloak-truststore.p12 \ -storepass changeit \ -noprompt ``` Replace `changeit` with a password of your own. You can verify the result with `keytool -list -v -keystore keycloak-truststore.p12 -storepass changeit`. Hub reads the trust store from the Java system properties `javax.net.ssl.trustStore` and `javax.net.ssl.trustStorePassword`, which you pass as arguments to the application command. In Docker Compose, mount the file into the container and override the command: ``` services: hub: image: ghcr.io/cryptomator/hub:2.0.0 command: > ./application -Djavax.net.ssl.trustStore=/etc/certs/keycloak-truststore.p12 -Djavax.net.ssl.trustStorePassword=changeit volumes: - './certs/keycloak-truststore.p12:/etc/certs/keycloak-truststore.p12:ro' ``` In Kubernetes, store the trust store in a secret and mount it as a volume. Encode the file with `base64 -w0 keycloak-truststore.p12` and add the output to a secret: ``` apiVersion: v1 kind: Secret metadata: namespace: cryptomator name: keycloak-truststore type: Opaque data: keycloak-truststore.p12: BASE64_ENCODED_TRUSTSTORE ``` The chart has no value for this, so patch the Hub deployment (`hub-hub` for a release named `hub`) after installing: ``` spec: template: spec: containers: - name: hub args: - '-Djavax.net.ssl.trustStore=/etc/certs/keycloak-truststore.p12' - '-Djavax.net.ssl.trustStorePassword=changeit' volumeMounts: - name: keycloak-truststore mountPath: /etc/certs readOnly: true volumes: - name: keycloak-truststore secret: secretName: keycloak-truststore ``` ``` kubectl patch deployment hub-hub -n cryptomator --patch-file truststore-patch.yaml ``` note Quarkus also offers the configuration options `QUARKUS_OIDC_CERTIFICATE_CHAIN_TRUST_STORE_FILE` and `QUARKUS_OIDC_CERTIFICATE_CHAIN_TRUST_STORE_PASSWORD`. These do not work for this purpose, so use the Java system properties shown above. If the Cryptomator desktop app also needs to talk to that Hub instance, the same applies there. Add `java-options=-Djavax.net.ssl.trustStore=/path/to/your/truststore` to the `Cryptomator.cfg` file in the installation directory. --- # Quick Start Want to see Cryptomator Hub in action before rolling it out to your team? This guide gets a test instance running on your own machine in about **10 minutes**. No domain, no TLS certificates, no reverse proxy. What you end up with is a playground, not a production system. It only listens on `localhost`, uses plain HTTP, and comes with default passwords. When you are ready for the real thing, continue with [Going to Production](#going-to-production) below. ## Before You Start[​](#before-you-start "Direct link to Before You Start") You need: * A machine with [Docker](https://docs.docker.com/get-docker/) installed, including Docker Compose (`docker compose version` should print a version number). * Ports `8080` and `8180` free on that machine. * About 1 GB of free RAM for the three containers (Hub, Keycloak, and Postgres). ## Start Hub[​](#start-hub "Direct link to Start Hub") We provide a ready-made Compose file that runs Hub locally. Nothing to configure. Open a terminal in an empty directory, download the file, and start the stack: ``` curl -fsSLO https://raw.githubusercontent.com/cryptomator/hub/refs/tags/2.0.0/deploy/compose/local/compose.yaml docker compose up -d ``` Docker now pulls the images and starts the containers. Keycloak takes a minute or two to initialize on first start, so grab a coffee. Once Docker reports the `hub` container as started and healthy, you are good to go. ## Log In[​](#log-in "Direct link to Log In") Open in your browser and log in with `admin` / `admin`. note Keycloak's admin console is available at , also with `admin` / `admin`. You don't need it for this tutorial, but it's where user federation and identity providers are configured later on. See [Identity Provider](/hub/admin-guide/keycloak/.md) for details. ## Start Using[​](#start-using "Direct link to Start Using") Hub greets you with a short onboarding on your first login: 1. **Complete the admin profile.** Hub needs a name and email address for the admin account. 2. **Choose a license.** For a local test, the *free trial* is what you want. You can claim it as often as you like. There are further free options for perpetual use on production installations as well. 3. **Save your Account Key.** Hub generates an [Account Key](/hub/user-guide/your-account/.md#account-key) in your browser. It's what you use to link further devices (browsers and Cryptomator apps) to your account, so keep it somewhere safe. That's it, you are in. Try [creating a vault](/hub/user-guide/vault-management/.md#create-a-vault), [adding a user](/hub/admin-guide/user-group-management/.md#create-user), or [unlocking the vault](/hub/user-guide/access-vault/.md) from the Cryptomator desktop app. The [User Guide](/hub/user-guide/quick-start/.md) and [Admin Guide](/hub/admin-guide/quick-start/.md) walk you through these tasks using complete worked examples. ## Clean Up[​](#clean-up "Direct link to Clean Up") To stop Hub but keep your data: ``` docker compose stop ``` To remove everything, including the database: ``` docker compose down -v ``` ## Going to Production[​](#going-to-production "Direct link to Going to Production") When you are ready to run Hub for real, this section sequences the [Deployment Cookbook](/hub/self-hosting-guide/deployment/.md) and [Operations](/hub/self-hosting-guide/operations/.md) references into one path; how long it takes depends mostly on your infrastructure — plan for **an hour** plus DNS. As a worked example, meet Alice: she liked the playground and now deploys Hub for the design agency Acme, a team of about 20 people. tip Not keen on running Hub yourself? We also offer Hub as a [managed service](https://cryptomator.org/hub/managed/?utm_source=docs.cryptomator.org\&utm_medium=referral\&utm_campaign=self-hosting-guide) with uptime guarantee and regular backups. ### Plan Your Deployment[​](#plan-deployment "Direct link to Plan Your Deployment") Decide on these up front — they are hard to change later: * Two public URLs, one for Hub and one for Keycloak, with DNS records created before deploying. * TLS termination via a reverse proxy or ingress controller — Hub, Keycloak, and PostgreSQL must never be exposed directly. * Whether to run the bundled Keycloak and PostgreSQL or connect existing instances. The defaults are sized for small installations like Acme's; see [Sizing](/hub/self-hosting-guide/deployment/.md#sizing) for larger teams. For more details, read [Before You Begin](/hub/self-hosting-guide/deployment/.md#before-you-begin) — including why the public URLs must be final before the first start. ### Choose a Recipe[​](#choose-a-recipe "Direct link to Choose a Recipe") The [Deployment Cookbook](/hub/self-hosting-guide/deployment/.md#recipes) offers three recipes: * [Docker Compose](/hub/self-hosting-guide/deployment/compose/.md) — a single Docker host behind a Traefik reverse proxy with Let's Encrypt. The simplest production setup. * [Kubernetes](/hub/self-hosting-guide/deployment/kubernetes/.md) — the Helm chart via the Helm CLI, for teams that already operate a cluster. * [Rancher](/hub/self-hosting-guide/deployment/rancher/.md) — the same Helm chart installed through the Rancher UI. Acme has no Kubernetes cluster and 20 users fit comfortably on one virtual machine, so Alice picks Docker Compose. The rest of this guide follows that path. ### Deploy with Docker Compose[​](#deploy-with-docker-compose "Direct link to Deploy with Docker Compose") Alice provisions a VM with Docker, points the two DNS records at it, and opens ports 80 and 443. She downloads the production Compose example, replaces the placeholders — hostnames, Let's Encrypt email, and freshly generated passwords and secrets — and starts the stack with `docker compose up -d`. Once all services are healthy, she signs in as `admin`, enters the license, and Hub is live at Acme's own domain. For more details, read [Prerequisites](/hub/self-hosting-guide/deployment/compose/.md#compose-prerequisites), [Deploy](/hub/self-hosting-guide/deployment/compose/.md#compose-deploy), and [Configuration](/hub/self-hosting-guide/deployment/compose/.md#compose-configuration) — including which ports must never be published. ### Set Up Backups[​](#set-up-backups "Direct link to Set Up Backups") All of Hub's state lives in PostgreSQL: vaults, encrypted keys, and the audit log in the `hub` database, users and credentials in the `keycloak` database. Alice schedules a nightly `pg_dumpall` via cron and moves the dumps off the VM. Then she does what most people skip: she [restores](/hub/self-hosting-guide/operations/.md#restore) one dump onto a scratch instance to confirm the backup actually works — a backup that has never been restored is a hope, not a backup. For more details, read [Backup](/hub/self-hosting-guide/operations/.md#backup) and [Restore](/hub/self-hosting-guide/operations/.md#restore). ### Keep It Healthy[​](#keep-it-healthy "Direct link to Keep It Healthy") Running Hub is low-maintenance; these are the recurring and occasional tasks: * [Upgrading](/hub/self-hosting-guide/deployment/compose/.md#compose-upgrading) — back up first, bump the pinned image tags, `docker compose up -d`. * [Verifying container images](/hub/self-hosting-guide/operations/.md#verifying-container-images) before deploying new versions. * [Trusting a private certificate authority](/hub/self-hosting-guide/operations/.md#trusting-a-private-certificate-authority) if your organization uses one. * [Changing the database password](/hub/self-hosting-guide/operations/.md#changing-the-database-password) as part of credential rotation. ## Next Steps[​](#next-steps "Direct link to Next Steps") * Set up your organization — the [Admin Guide](/hub/admin-guide/.md) walks through users, groups, identity providers, and more. * Bookmark [Operations](/hub/self-hosting-guide/operations/.md) as the reference for everything maintenance. --- # User Guide This guide is for everyone who uses Cryptomator Hub to store and share encrypted data. It covers your own account, the vaults you own or are a member of, and how you unlock them with the Cryptomator apps. If Hub is new to you, start with the [Quick Start](/hub/user-guide/quick-start/.md). It walks you from your first login to an unlocked vault. The other pages describe each area in detail. ## [📄️Quick Start](/hub/user-guide/quick-start/.md) [From your first login to an unlocked vault — set up your account, create a vault, invite teammates, and unlock it with Cryptomator.](/hub/user-guide/quick-start/.md) ## [📄️Your Account](/hub/user-guide/your-account/.md) [To open vaults secured by a Cryptomator Hub instance, you need an account on the regarding Hub instance.](/hub/user-guide/your-account/.md) ## [📄️Vault Management](/hub/user-guide/vault-management/.md) [The central entities in Cryptomator Hub are vaults.](/hub/user-guide/vault-management/.md) ## [📄️Working with Vaults](/hub/user-guide/access-vault/.md) [To encrypt your data securely with Cryptomator Hub vaults, you need the Cryptomator app for your OS.](/hub/user-guide/access-vault/.md) ## [📄️Vault Recovery](/hub/user-guide/vault-recovery/.md) [This section contains instructions for recovering Cryptomator Hub vaults using the vault recovery key.](/hub/user-guide/vault-recovery/.md) --- # Working with Vaults To encrypt your data securely with Cryptomator Hub vaults, you need the Cryptomator app for your OS. Cryptomator runs on Windows, macOS, Linux, Android and iOS. You can download the version for your OS from [cryptomator.org](https://cryptomator.org/downloads/). This section describes exemplarily how to unlock a vault in the Desktop app. Android and iOS work analogously. As described in [open an existing vault](/desktop/adding-vaults/.md#open-an-existing-vault), you should have already added the vault to the vault list, e.g., by selecting the `vault.cryptomator` file. ## Unlocking a Vault[​](#unlocking-a-vault "Direct link to Unlocking a Vault") ### 1. Click Unlock[​](#click-unlock "Direct link to 1. Click Unlock") To unlock the vault, click on the large `Unlock` button in the center of Cryptomator's main window. ![Click 'Unlock' to unlock a Hub vault with the Desktop app](/img/hub/unlock-auth-desktop-app.png) ### 2. Authenticate[​](#authenticate "Direct link to 2. Authenticate") Cryptomator should open your default browser for authentication. If you're not already logged in, you need to provide your user credentials, e.g., by entering your username and password or by inserting your key when WebAuthn is enabled. ![After your browser asks for credentials, enter your username and password](/img/hub/unlock-authenticate.png) ### 3. Register Device[​](#register-device "Direct link to 3. Register Device") If you connect to Hub with this device for the first time, you need to register it. Desktop ![Register your device by entering the setup code and a name for it](/img/hub/unlock-register-device-desktop-app.png) Hub ![Hub shows the new device view during unlock](/img/hub/unlock-register-device-hub.png) Enter a name for the device to identify it later on and the [Account Key](/hub/user-guide/your-account/.md#account-key) which was generated during the account setup. You can also find it in the [account settings](/hub/user-guide/your-account/.md#profile-page). After that, you will see a confirmation dialog, unlock the vault again. ### 4. Vault Unlocked[​](#vault-unlocked "Direct link to 4. Vault Unlocked") You are all set up and an unlock should be successful from now on. You can then reveal the vault's contents as usual. Desktop ![Desktop shows unlock successful](/img/hub/unlock-success-desktop-app.png) Hub ![Hub shows unlock successful](/img/hub/unlock-success-hub.png) --- # Quick Start This guide walks you through your first steps in Cryptomator Hub, from logging in for the first time to working with an unlocked vault, in about **15 minutes**. As a worked example, meet Bob: he just joined the design agency Acme, and his administrator Alice sent him the Hub URL and his login credentials. Bob will set up his account, create a vault called *Client Projects*, share it with his colleague Carol and the *Designers* group, and unlock it with the Cryptomator desktop app. ## Before You Start[​](#before-you-start "Direct link to Before You Start") You need: * The URL of your organization's Hub instance and login credentials, both provided by your administrator. * The [Cryptomator app](https://cryptomator.org/downloads/?utm_source=docs.cryptomator.org\&utm_medium=referral\&utm_campaign=user-guide) for your OS. This guide uses the desktop app; Android and iOS work analogously, see [Working with Vaults](/hub/user-guide/access-vault/.md). * The `create-vaults` role to create a vault yourself. If the `Add` button in the vault list stays grayed out for you, ask your administrator for the [role](/hub/admin-guide/user-group-management/.md#roles) — or skip that section and continue with a vault someone shared with you. ## Set Up Your Account[​](#set-up-your-account "Direct link to Set Up Your Account") Bob opens the Hub URL, logs in with his credentials, and Hub greets him with a one-time account setup. ![Account setup on first login](/img/hub/account-setup.png) The setup generates his personal *Account Key*. It is what links further browsers and Cryptomator apps to his account later, so he copies it into his password manager before finishing the setup. After finishing the setup, Bob lands on the vault list — Acme's is still empty. The `Add` button in the top right corner is the starting point for the next section: `Create New` opens the vault creation wizard. ![Empty vault list with the Add button in the top right corner](/img/hub/vaultlist-empty.png) For more details, read [Account Setup](/hub/user-guide/your-account/.md#account-setup) and [Account Key](/hub/user-guide/your-account/.md#account-key). ## Create a Vault[​](#create-a-vault "Direct link to Create a Vault") Time for the first vault: 1. In the vault list, Bob clicks `Add` → `Create New` and names the vault *Client Projects*. 2. He follows the creation wizard and stores the displayed recovery key in his password manager — it restores access to the vault data if Hub is ever unavailable. 3. In the last step, he downloads the vault template (a zip file, exactly once) and unzips it into the cloud storage folder the team already shares. ![Create a vault](/img/hub/create-vault.png) For more details, read [Create a Vault](/hub/user-guide/vault-management/.md#create-a-vault), [Show Recovery Key](/hub/user-guide/vault-management/.md#show-recovery-key), and [Download Vault Template](/hub/user-guide/vault-management/.md#download-vault-template). ## Add Members[​](#add-members "Direct link to Add Members") The vault is Bob's alone so far. In the vault details, he clicks into the search field of the `Shared with` section, picks Carol, and clicks `Add`. He then adds the *Designers* group the same way, so future team members get access automatically through their group membership. ![Add a user or group in the vault details](/img/hub/vault-details-search.png) note When a member completes their account setup (or resets their account), a vault owner has to confirm the access once via the `Update Permissions` button before that member can unlock the vault. For more details, read [Share a Vault](/hub/user-guide/vault-management/.md#share-a-vault), [Update Permissions](/hub/user-guide/vault-management/.md#update-permissions), and [Web of Trust](/hub/user-guide/vault-management/.md#web-of-trust) for verifying the identity of vault members. ## Unlock the Vault[​](#unlock-the-vault "Direct link to Unlock the Vault") To work with the encrypted data, Bob opens the Cryptomator desktop app, adds the vault by selecting the `vault.cryptomator` file from the shared cloud folder, and clicks `Unlock`. His browser opens for authentication, and since this is the first unlock from this device, Hub asks him to register it with a device name and his Account Key. After that, the vault unlocks, and Bob can reveal and edit the *Client Projects* files as usual. ![Desktop shows unlock successful](/img/hub/user-guide-unlock-success-desktop.png) For more details, read [Unlocking a Vault](/hub/user-guide/access-vault/.md#unlocking-a-vault), in particular [Register Device](/hub/user-guide/access-vault/.md#register-device). ## Next Steps[​](#next-steps "Direct link to Next Steps") * Lost access to a vault or Hub itself? See [Vault Recovery](/hub/user-guide/vault-recovery/.md). * Review and revoke your registered browsers and apps under [Authorized Devices](/hub/user-guide/your-account/.md#authorized-devices). * Curious how the zero-knowledge key management works? Read the [security architecture](/security/hub/.md). --- # Vault Management The central entities in Cryptomator Hub are vaults. In Hub, every vault contains a key to encrypt and decrypt your data stored in the cloud of your choice. Hub manages access to the vaults, it does not store any encrypted user data. This section describes how to manage vaults in Cryptomator Hub. ## Vault List[​](#vault-list "Direct link to Vault List") The vault list is the main page of Cryptomator Hub. Here, all vaults which are shared with you, are listed. After signing in, Hub redirects you to this list. Alternatively, you can also access the list by clicking on the `Vaults` tab in the navigation bar. ![List vaults](/img/hub/vaultlist.png) note * As a user, you will only see the vaults that you have access to. * As an admin of the Hub instance, you can see all vaults, but you can only access those that you have been granted access to. Emergency Access Status in Vault List (Enterprise only) In the `Vault List`, owners can see the Emergency Access status directly via badges: * `Council missing`: No council is configured for the vault * `Broken Emergency Access`: Not enough valid council members (for example after council members reset their accounts) * `Insufficient Emergency Access`: No fault tolerance in the council ## Create a Vault[​](#create-a-vault "Direct link to Create a Vault") note Creating vaults require the `create-vault` role. [Here](/hub/admin-guide/user-group-management/.md#roles) you can read more about roles. To create a vault in Hub, navigate to the vault list and click `Add` → `Create New` in the top-right corner. Every vault has a name and optionally a description. Fill out the form and continue the process by clicking the `Next` button in the right corner. ![Create a vault](/img/hub/create-vault.png) If the [Emergency Access](/hub/admin-guide/emergency-access/.md) feature is enabled, the following step appears: Here, the conditions for Emergency Access are defined for the new vault. If the administrator allows custom council selection, you can adjust the default council. Select the council members who should participate in emergency recovery and review the example recovery scenario. Click `Next` to continue to the recovery key step. Enterprise Feature Visit [cryptomator.org](https://cryptomator.org/hub/?utm_source=docs.cryptomator.org\&utm_medium=referral\&utm_campaign=vault-management) for more information about Enterprise features. ![Define Emergency Access Conditions](/img/hub/create-vault-emergency-access.png) In the next step, the vault *recovery key* is displayed. It can [restore access to the vault data](/hub/user-guide/vault-recovery/.md) in case of an emergency, e.g. if Cryptomator Hub is down. Store it at a safe location, tick the checkbox and complete the setup by clicking the `Create Vault` button at the bottom ![Save vault recoverykey](/img/hub/create-vault-recoverykey.png) warning The recovery key is **highly confidential**. It is a human-readable form of the vault [masterkey](/security/architecture/.md#masterkey), which is used to encrypt your data and independent of the key management in Cryptomator Hub. When the setup is finished, you have the opportunity to download the initial vault template and place it in your desired cloud storage location. You can unlock the vault and place data inside with [Cryptomator](https://cryptomator.org/downloads/). If you skip this step, you can download the template [later](#download-vault-template). ![Download vault template](/img/hub/create-vault-download.png) ## Vault Details[​](#vault-details "Direct link to Vault Details") The vault details page shows metadata of a vault (e.g. creation date) and contains the management section of the vault (e.g. grant a user access). To open it, navigate to the vault list and click on entry in the list. The details are displayed on the right side. With the user role, you have access to the following details: ![Display vault details as user](/img/hub/vault-details-user.png) With the owner role, you have access to the following sections: ![Display vault details as vault owner](/img/hub/vault-details-owner.png) ### Manage Vault[​](#manage-vault "Direct link to Manage Vault") To add a user, grant devices access, or view the members list, you need to have the vault owner role. Open the [vault details](#vault-details) page to manage a vault. * `Shared with` members list * `Update Permissions` button (only clickable if necessary) * `Edit Vault Metadata` button * `Download Vault Template` button * `Show Recovery Key` button * `Setup Emergency Access Council` button (only visible if necessary) * `Fix Emergency Access Council` button (and only visible if necessary) * `Archive Vault` button ### Share a Vault[​](#share-a-vault "Direct link to Share a Vault") If a user should have access to this vault, you need to share it with the user. Click in the search field of the `Shared with` section, select it from the results list and click the `Add` button. ![Add a user or group in the vault details](/img/hub/vault-details-search.png) ### Change Ownership[​](#change-ownership "Direct link to Change Ownership") To change user's ownership of a vault, click on the three dots next to the user's details in the [Share a vault](#share-a-vault) section of the [vault details](#vault-details). ### Update Permissions[​](#update-permissions "Direct link to Update Permissions") If members of the vault have finished the [first login](/hub/user-guide/your-account/.md#account-setup) or reset user accounts, a vault owner must explicitly grant access to these users. Only then, the user can unlock the vault with its device. As a vault owner, you can see that an update is necessary when the `Update Permissions` button is clickable. ![Update permissions in the vault details](/img/hub/update-permission.png) ### Edit Vault Metadata[​](#edit-vault-metadata "Direct link to Edit Vault Metadata") To edit the vault metadata, click on the `Edit Vault Metadata` button in the [vault details](#vault-details). It opens a form where you can change the vault name and description. ### Download Vault Template[​](#download-vault-template "Direct link to Download Vault Template") To download the vault template, click on the `Download Vault Template` button in the [vault details](#vault-details). It downloads the vault template to your local device. You can place it in your desired cloud storage location and unlock it with [Cryptomator](https://cryptomator.org/downloads/). You can do that if you skipped the download vault template step during the vault creation. note Download the vault template only once! If you download it multiple times, you will have multiple vault templates in your cloud storage location. This can lead to confusion. ### Show Recovery Key[​](#show-recovery-key "Direct link to Show Recovery Key") To show the vault recovery key, click on the `Show Recovery Key` button in the [vault details](#vault-details). It shows the same recovery key shown during vault creation. You can use it to [restore access to the vault data](/hub/user-guide/vault-recovery/.md) in case of an emergency, e.g. if Cryptomator Hub is down. Store it at a safe location. ### Setup/Fix Emergency Access Council[​](#emergency-access-council "Direct link to Setup/Fix Emergency Access Council") Enterprise Feature Visit [cryptomator.org](https://cryptomator.org/hub/?utm_source=docs.cryptomator.org\&utm_medium=referral\&utm_campaign=vault-management) for more information about Enterprise features. To configure [Emergency Access](/hub/admin-guide/emergency-access/.md) for a vault, click `Setup Emergency Access Council` in the [vault details](#vault-details). If Emergency Access is already configured but needs correction, click `Fix Emergency Access Council`. This opens a dialog where you define the council members and confirm with `Grant`. ### Archive Vault[​](#archive-vault "Direct link to Archive Vault") To archive the vault, click on the `Archive Vault` button in the [vault details](#vault-details). It archives the vault and removes it from the "accessible" vault list. You can unarchive it by clicking on the `Owned by me` tab in the navigation bar, select the vault and clicking on the `Reactive Vault` button. ## Web of Trust[​](#web-of-trust "Direct link to Web of Trust") Cryptomator Hub uses a Web of Trust (WoT) to verify the identity of users during vault sharing. The WoT state of a user is displayed in the vault details page. The state can be one of the following: * **Unverified**: There is no trust chain between you and the specific user. Indicated with a red shield. You can change this by verifying the user. * **Verified**: There is a trust chain between you and the specific user. Indicated with a green shield. You or a user you trust has verified the user. To verify `carol`, click on the red shield icon and select `Check Identity…` ![Carol is unverified regarding her Web of Trust state](/img/hub/wot-carol-unverified.png) While verifying a user, you need to enter the first characters of the user's public key fingerprint. This fingerprint is displayed in the user's profile page. ![Verify Carol regarding her Web of Trust state](/img/hub/wot-carol-verify.png) `carol` is now verified ![Carol is verified regarding her Web of Trust state](/img/hub/wot-carol-verified.png) The verification process is logged in the audit log with event type `Signed Identity` ![Audit log](/img/hub/wot-audit-log.png) `signature still valid` means that the `identity` has still the same key. If the user account gets reset after verification, this message changes to `was valid; signed key changed by now` and the user needs to get verified again. You can read more details about Web of Trust and how to configure its settings in the [Admin section of Hub](/hub/admin-guide/web-of-trust/.md). ## Import a Vault[​](#import-a-vault "Direct link to Import a Vault") If you have a existing, password-based Cryptomator vault and want to switch to centralized, password-less user access management, you can import the vault in Cryptomator Hub. For a successful import, the [recovery key](/desktop/password-and-recovery-key/.md#show-recovery-key) of the vault and write access to its storage location is needed The import is done via the Hub vault recovery feature. Follow the [vault online recovery guide](/hub/user-guide/vault-recovery/.md#online-recovery) and use the recovery key of the password-based vault in the process. Don't forget to replace the vault config file `vault.cryptomator` at the vault storage location at the end. Finally, to ensure that the vault cannot be unlocked with its old password anymore, remove the file `masterkey.cryptomator` and all backup files (ending with `.bkup`). --- # Vault Recovery This section contains instructions for recovering Cryptomator Hub vaults using the vault recovery key. Cryptomator Hub vaults can be recovered in two different ways: 1. [Online Recovery](#online-recovery) - Reestablishes Hub-controlled access management for a vault in case it can no longer be managed in Hub 2. [Offline Recovery](#offline-recovery) - Restores vault data access of a Hub-managed vault in case of a disaster (e.g. Cryptomator Hub is down and immediate data access is needed) ## Online Recovery[​](#online-recovery "Direct link to Online Recovery") This recovery method should be used if a vault can no longer be managed in Hub, for example because it lost all its owners or was accidentally removed from Hub. In the process, a new Hub vault with the same key material as the "to-be-recovered" vault is created. The membership information of the old vault cannot be migrated, hence all users/groups need to be added manually afterwards. Requirements: * Access to Cryptomator Hub * Write access to the storage location of the vault * Access to the recovery key of the vault In Cryptomator Hub navigate to the vault list, click `Add` and `Recover Existing` ![Vault list add drop down](/img/hub/vault-onlinerecovery-step1.png) Enter the recovery key for the vault you want to restore. If you enter a recovery key from a different vault, the recovery will not work. Proceed with `Recover Vault`. ![Vault enter recovery key](/img/hub/vault-onlinerecovery-step2.png) Enter a name and an optional description for the new vault. As its creator, you become the owner of the recovered vault and can grant or revoke access to it. ![Creating a vault using recovery key](/img/hub/vault-onlinerecovery-step3.png) If successful, a new vault has been created. Proceed as follows: 1. Click on `Download zipped vault folder` of the new created vault 2. Unzip the downloaded folder 3. Copy the file `vault.cryptomator` of the unzipped folder 4. Browse locally on the device, directly in the cloud or network storage to the location of the vault folder. In that folder, replace the existing `vault.cryptomator` file with the one you just copied. Afterwards, you can manage vault data access over the newly created vault in Hub. You will need to regrant permission to the vault members, and then the vault can be unlocked by the team. ## Offline Recovery[​](#offline-recovery "Direct link to Offline Recovery") This recovery method should only be used in an emergency, i.e. immediate data access is needed but Cryptomator Hub not reachable. In the process, the authentication needed to unlock the vault is changed from Hub- to password-based by creating/changing vault configuration files. If these changes are synchronized to the online storage, everyone with the chosen password can unlock and access the vault data without requiring a connection to Cryptomator Hub. If you don't want that, ensure that the vault is stored at an offline location without any kind of synchronization. note This process is reversible. See the [end of this section](#reversing-offline-conversion). Requirements: * Access to the Cryptomator desktop application * Write access to the storage location of the vault * Access to the recovery key of the vault Open the Cryptomator desktop app, right-click on the vault you want to restore in the vault list, click `Show vault options` in the opened context menu. In the opening window, select the `Recovery`, read the label description and click the `Convert to Password-Based Vault` button. ![Vault recovery convert to Password-Based-Vault](/img/hub/vault-offline-recovery-step1.png) Enter the recovery key for the vault you want to restore. If you enter a recovery key from a different vault, the recovery will not work. Proceed with `Next`. ![Convert vault enter recovery key](/img/hub/vault-offlinerecovery-step2.png) In the next step choose a [good password](/security/best-practices/.md#good-passwords) used for unlocking the vault. Cryptomator requires at least 8 characters but we recommend you to use a longer phrases such as pass-sentences. The bar below the password field estimates the strength of your password. ![Convert vault enter new password](/img/hub/vault-offline-recovery-step3.png) If the conversion was successful, a success message is shown. You can close the dialog box. This vault is now converted to a password-based vault and can be unlocked with the above chosen password. ## Reversing Offline Conversion[​](#reversing-offline-conversion "Direct link to Reversing Offline Conversion") You can reverse the offline conversion. In order to do that, remove the following files: * all files named or starting with `masterkey.cryptomator` * `vault.cryptomator` * the *most recent* `vault.cryptomator.XXXXXXXX.bkup` Then restore the original config by renaming `vault.cryptomator.XXXXXXXX.bkup` to `vault.cryptomator`. You can then unlock the vault again using the Cryptomator Hub. --- # Your Account To open vaults secured by a Cryptomator Hub instance, you need an account on the regarding Hub instance. The account is used to authenticate your identity and to manage your trusted devices. If you don't have an account, contact your local administrator to create one for you. ## Account Key[​](#account-key "Direct link to Account Key") Every account has a private *Account Key*. The Account Key is used for authorizing browsers or apps which try to connect to Hub. It is not used for encrypting vault data. Keep your account key secret and only store it in a secure place (e.g. password manager). You can view your account key in your [profile](#profile-page) on trusted browsers. note If you lose your account key, you have two options: If you have access to an authorized browser, you can view it on the [profile page](#profile-page) or otherwise, you can [reset your account](#reset-account). ## Account Setup[​](#account-setup "Direct link to Account Setup") The very first time you log in to Cryptomator Hub, you're asked to set up your account. This is a one-time process that takes just a minute. ![Account setup on first login](/img/hub/account-setup.png) In the setup your [Account Key](#account-key) is generated and displayed. We recommend to copy your Account Key to a secure place (e.g. password manager), but you can always view it later in your profile from any trusted browser. The browser used for the setup is automatically trusted. You can revoke the trust at any time in your profile. After storing your account key securely, tick the checkbox and finish the setup. You are now logged in to Hub and can start using it. ## Profile Page[​](#profile-page "Direct link to Profile Page") On the profile page, you can manage your account. It shows your account key and fingerprint, lists your trusted devices and more. You can open it by clicking on your profile icon in the top right corner and select *Your Profile*. ![Your account in Cryptomator Hub](/img/hub/profile-view.png) ### Change Language[​](#change-language "Direct link to Change Language") You can change the language of Cryptomator Hub to match your preference. The language selection is available in the profile settings. Is your preferred language not available yet? We are continuously working on adding more languages. If you're interested, you can contribute translations via Crowdin: [Cryptomator Hub on Crowdin](https://crowdin.com/project/cryptomator). ### Regenerate Account Key[​](#regenerate-account-key "Direct link to Regenerate Account Key") If you suspect that your old Account Key has been compromised, you can regenerate it. You will then only be able to add new devices with the new Account Key. Your existing devices will remain trusted. ### Authorized Devices[​](#authorized-devices "Direct link to Authorized Devices") A device is authorized if it has been authenticated with your Account Key. Only on authorized devices you can log in to Hub and open vaults. For each authorized device, you can view its name, type (e.g., browser), the date it was added, the last time it accessed a vault, and its IP address. If the last access values are not present this can have multiple reasons: 1. The device has not accessed any vaults yet 2. The device is not up to date and does not send the required information The device marked with `This Device` is the one you are currently using. This allows you to easily verify your active session and detect any unauthorized access. By managing your authorized devices, you ensure that only trusted ones remain active, giving you greater security and control over your account. If you don't trust a device anymore, you can remove it from the list of authorized devices. This will log out the device and revoke access to all shared vaults. note Periodically review your devices and promptly remove unused and unknown ones. ### Legacy Devices[​](#legacy-devices "Direct link to Legacy Devices") This section lists devices that have been authorized with an older version of Cryptomator Hub. It is only visible if you have any legacy devices. Legacy devices where created before the introduction of the current user key system and will be removed from your account within one of the next major updates of Hub. ![Your legacy devices](/img/hub/legacy-devices.png) If you have any legacy device 1. check if you still use them, if so, update the client version on this device which migrates it to the new format 2. if you don't use them anymore, remove them to revoke access of this device to your accessible vaults ### User Key Fingerprint[​](#user-key-fingerprint "Direct link to User Key Fingerprint") The fingerprint can be used to verify the identity of the user, for example when [updating the permissions](/hub/user-guide/vault-management/.md#update-permissions) of a vault. It will only change if you [reset your account](#reset-account). ## Reset Account[​](#reset-account "Direct link to Reset Account") If you lose your account key and can't access any trusted browser, you can reset your account when logging in from a new device. All already authorized devices will be removed and access to shared vaults will be revoked. After the reset, you can log in to Hub from a new browser and set up your account again. ![Reset account on login](/img/hub/trust-device.png) --- # Working with Vaults Cryptomator for iOS is fully integrated into the Files app of iOS. In order to access your encrypted data, you have to use the Files app. ## Enable Cryptomator in Files App[​](#enable-cryptomator-in-files-app "Direct link to Enable Cryptomator in Files App") In order for Cryptomator to be listed in the Files app under "Locations", you may have to enable Cryptomator first. Open the Files app and then: 1. Tap on the **Browse** tab in the lower right corner. 2. Tap on the **(…)** button in the upper right corner. 3. Tap on **Edit**. 4. Enable **Cryptomator**. 5. Tap on **Done** in the upper right corner. ![How to enable Cryptomator in Files app](/img/ios/enable-cryptomator-in-files-app-01.png)![How to enable Cryptomator in Files app](/img/ios/enable-cryptomator-in-files-app-02.png) --- # Cloud Management ## WebDAV[​](#webdav "Direct link to WebDAV") Please see [Cloud Services With WebDAV Support](/misc/supported-cloud-services/.md#cloud-services-with-webdav-support) for a non-exhaustive list of Cloud Services and information about accessing them with WebDAV. note While creating the WebDAV connection, please make sure to add the root of the accessible storage and don't navigate directly into the vault. If you encounter the `Request method not supported by the target resource.` error, it means that the WebDAV URL entered is invalid or the server doesn't support WebDAV properly. To resolve this: 1. Verify you're using the correct WebDAV URL for your cloud service 2. Check the [list of supported cloud services](/misc/supported-cloud-services/.md#cloud-services-with-webdav-support) for the correct WebDAV URLs 3. Ensure your cloud provider has WebDAV enabled (some require enabling it in account settings) 4. If using 2FA, you might need to generate an app-specific password for WebDAV access ## Other File Provider[​](#other-file-provider "Direct link to Other File Provider") This option allows you to add a vault from any supported [file provider](https://developer.apple.com/documentation/fileprovider/). Default implementations by Apple are iCloud Drive and On My iPhone/iPad. Inside the Files app, you can also add custom connections to SMB-compatible servers. If you have a lot of apps installed that include a file provider, you may notice that most of them are grayed out. This is because third-party file providers usually don't support "picking folders". To our best of knowledge, this is unsupported by Apple. You can find a technical discussion [here](https://github.com/cryptomator/ios/issues/51). --- # Settings You can configure Cryptomator to your needs. Access the settings by tapping the gear icon in the top left corner. ## Support[​](#support "Direct link to Support") If you have problems with the app, you can enable `Debug Mode`. After reproducing the problem, you should disable `Debug Mode` again and then `Send Log File`. --- # Setup You can get Cryptomator for iOS on the [App Store](https://apps.apple.com/app/cryptomator/id1560822163). Cryptomator is available for free with in-app purchases. The free version gives you read-only access to your vaults. With the in-app purchase, you can unlock the full version to gain write access to your vaults. You can also try out the full version free for 30 days. ## Full Version[​](#full-version "Direct link to Full Version") A full version of Cryptomator without in-app purchases is available on the [App Store](https://apps.apple.com/app/cryptomator-full-version/id1665616242) as well. This version is unlisted and only available via the direct link. The "Full Version" is basically the same as Cryptomator with the in-app purchase "Full Version" unlocked. This app is available for interested parties using Apple School Manager or Apple Business Manager that are unable to buy in-app purchases. Or if you want to gift the app to your friends or family. ## Requirements[​](#requirements "Direct link to Requirements") Requires iOS 14.0 or later. Compatible with iPhone, iPad, and iPod touch. --- # Shortcuts Guide The Shortcuts integration of Cryptomator allows you to build different automations in the [Shortcuts app](https://support.apple.com/guide/shortcuts/welcome/ios). With that, you can automate recurring tasks quickly and easily. For a shortcut to run smoothly, the vault must be unlocked during the execution of the shortcut. For automations, you should set the unlock duration to "Indefinite" in the [settings of your vault](/ios/vault-management/.md#unlock-duration). In addition, you should know that some Cryptomator shortcut actions build on each other. For example, the "Save File" action requires a folder inside a vault as an input, which can be obtained using the "Get Folder" action. ## Automatic Photo Upload[​](#automatic-photo-upload "Direct link to Automatic Photo Upload") With Cryptomator's integration in Shortcuts, you can build an action to automatically upload your photos to a Cryptomator vault. You can either follow these step-by-step instructions or use the following shortcut to get started: **Step 1: Create new shortcut** * Open the Shortcuts app on your iOS device. * Tap on the "+" at the top right to create a new shortcut. If the Shortcuts app is not installed, download it from the [App Store](https://apps.apple.com/app/shortcuts/id915249334). **Step 2: Add "Find Photos" action** * Select the search field at the bottom to add an action. * Under the tab "Apps", select "Photos". * Select the action "Find Photos". You can customize this action to your needs by adding various filters or to limit the number of photos to be selected. **Step 3: Add "Get Folder" action** * Add the "Get Folder" action from Cryptomator. * Specify the vault and the path of the folder where your photos should be stored. Important: It will check if the folder exists in your vault. If it doesn't exist, the action will fail and no photos will be uploaded. **Step 4: Add "Save File" action** We're going to add the "Save File" action from Cryptomator. But since this action only saves a single file (or in this case, photo), we need to add wrap this action around a different action first. * Add the "Repeat with Each" action, which you can find under the "Categories" tab and then under "Scripting". * Add the "Save File" action from Cryptomator. * Make sure that the two variables are correctly set: The image you want to save and the folder from the "Get Folder" action in step 3. In order to set these variables, you may have to tap on the "File" field, then "Select Magic Variable", and tap on "Repeat Item". Congratulations, you have just created your first shortcut with Cryptomator actions! **Hints:** 1. To fully automate your photo upload, you should run a shortcut using an automation. To do this, [create a new automation](https://support.apple.com/guide/shortcuts/create-a-new-personal-automation-apdfbdbd7123/ios) in the Shortcuts app. You don't have to create the whole shortcut again. You can just add the action "Execute Shortcut" and select the previously created shortcut. 2. Executing a shortcut with a lot of photos (>1,000) can take much longer than executing it with 2x500 photos. To our knowledge, this seems to be a limitation of the Shortcuts app. Therefore, try to limit the number of photos using the available filters. One possible filter is to consider only the photos of the last 2-7 days for a shortcut that is executed daily. ## Photo to PDF (Advanced Example)[​](#photo-to-pdf "Direct link to Photo to PDF (Advanced Example)") Another example, inspired by community member JB, is to convert the latest photo to a PDF and save it in a vault under a chosen path. This example is a bit more advanced, but it shows how you can combine different actions to create a more complex automation. You can either follow these step-by-step instructions or use the following shortcut to get started: We assume that you have already installed Shortcuts, see step 1 of the previous example. **Step 1: Add "Is Vault Unlocked" action** * Add the "Is Vault Unlocked" action from Cryptomator. * Specify the vault you want to use. * Add the "If" action from the "Scripting" category. * Set the condition to "is" and the number to "0". This makes sure that your vault is unlocked. If it is not, the shortcut will ask you to unlock it, see step 2. **Step 2: Add "Open Vault" action** * Add the "Open Vault" action from Cryptomator. * Drag this action below the "If" action (and above "Otherwise"). * Specify the same vault you used before. * Add the "Show Alert" action from the "Scripting" category. * Drag this action below the "Open Vault" action (and above "Otherwise"). * Replace the informational message with something like "Unlock this vault and run this shortcut again". This completes the "If" block. Now we can be certain that the vault is unlocked for the "Otherwise" block. **Step 3: Add "List" action** If you only want to save the PDF in one specific path, you can skip this step and go to step 4. Otherwise, you can add a list of paths to choose from. * Add the "List" action from the "Scripting" category. * Drag this action below the "Otherise" action (and above "End If"). * Customize this list to your needs by specifying paths of the folders where your PDFs could potentially be stored, something like a "favorites" list. * Add the "Choose from List" action from the "Scripting" category. Don't worry about dragging these actions inside the "Otherwise" block of the "If" action, we'll do that in the very end. **Step 4: Add "Get Latest Photos" + "Make PDF" actions** * Add the "Get Latest Photos" action from the "Media" category. * Add the "Make PDF" action from the "Documents" category. This is just an example. Shortcuts offer you many other ways to get the file or media that you could use as an input for encryption. **Step 5: Add "Get Folder" action** * Add the "Get Folder" action from Cryptomator. * Select the variable "Chosen Item" for the path (or enter a specific path if you skipped step 3) and specify the same vault you used before. Important: It will check if the folder exists in your vault. If it doesn't exist, the action will fail and no PDF will be uploaded. **Step 6: Add "Save File" action** * Add the "Save File" action from Cryptomator. * Make sure that the two variables are correctly set: The PDF you want to save and the folder from the "Get Folder" action in step 5. **Step 7: Finish "Otherwise" block** * Drag the "End If" action to the very bottom, which will enclose all actions that you have created between the steps 3 and 6 into the "Otherwise" block. Congratulations, you have just created a more advanced shortcut with Cryptomator actions! --- # Vault Management ## Unlock Duration[​](#unlock-duration "Direct link to Unlock Duration") With the vault setting "Unlock Duration", you can specify for how long you want your vault to stay unlocked when idle. The following options are: * Let iOS Decide Automatically * 5 Minutes * 10 Minutes * 30 Minutes * 1 Hour * Indefinite The default option is "Let iOS Decide Automatically". Accessing Cryptomator via the Files app is possible via a so-called File Provider Extension. This extension has limited capabilities, e.g., it has a lower memory limit than regular apps. To free up memory, iOS may terminate Cryptomator at any time, which is basically the same as locking the vault since the key is held in memory. This option has two consequences: * There is no guarantee for how long your vault stays unlocked. Of course, while you're accessing your vault, it's highly unlikely that Cryptomator gets terminated. * You're responsible for locking your vault manually. Or if that's not a concern of yours, you can just let iOS decide when Cryptomator is getting terminated. In order to have a guarantee that your vault stays unlocked for a certain amount of time, the other options are available. By using one of these options, a copy of your key needs to be stored in the iOS keychain, as long as your vault is unlocked. E.g., if you choose "1 Hour" and Cryptomator gets terminated by iOS within that time frame, your vault can automatically be unlocked again using the key from the iOS keychain. If the selected time frame has passed, the key will be removed from the iOS keychain and your vault will get automatically locked. If you choose the "Indefinite" option, your vault will be kept unlocked until you have manually locked it. ## Security Considerations[​](#security-considerations "Direct link to Security Considerations") Cryptomator balances security and usability by storing certain credentials in the iOS Keychain to enable convenient features like biometric authentication and reduced password prompts. Here's how it works: * Vault Passwords: Cryptomator stores a copy of your vault password in the iOS Keychain when Touch ID or Face ID is enabled. * Masterkeys: Cryptomator stores a copy of the masterkey in the iOS Keychain for vaults with a specified "Unlock Duration" (anything except "Let iOS Decide Automatically"). These credentials are stored with the [kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly](https://developer.apple.com/documentation/security/ksecattraccessibleafterfirstunlockthisdeviceonly) attribute, ensuring: 1. Keychain entries are only accessible after the first unlock using your device's passcode following a reboot. 2. Keychain entries are not transferred to a new device when restoring from a backup. 3. Keychain entries are not synchronized to iCloud. These measures are designed to provide a secure yet convenient experience on your trusted devices. If you prefer not to store these credentials in the Keychain due to security concerns, you can opt out of using these features. However, for most users, this balance between security and usability is appropriate and safe. --- # Contribute ## How Can You Help Us?[​](#how-can-you-help-us "Direct link to How Can You Help Us?") Cryptomator is an open-source project and wouldn't be possible without contributions from users who support the idea. There are several ways you can help us: * By reporting bugs or feature requests on [GitHub](https://github.com/cryptomator/cryptomator/issues/new/choose), * By discussing solutions in our [community](https://community.cryptomator.org), * By contributing patches or features via pull requests, * By helping us with the [localization](https://translate.cryptomator.org/) of Cryptomator, * By improving this documentation, * By becoming a [sponsor](https://cryptomator.org/sponsors/), * Or by [donating](https://cryptomator.org/donate/) to the maintainers. ## Before You Start[​](#before-you-start "Direct link to Before You Start") If you plan to help, please stick to our [Code of Conduct](https://github.com/cryptomator/cryptomator/blob/develop/.github/CODE_OF_CONDUCT.md). Our code is licensed under GPLv3 and this documentation under CC-BY-SA 4.0. If you contribute either, you grant us the rights to publish your contributions under those licenses. Also, you have to digitally sign a [Contributor License Agreement (CLA)](https://gist.github.com/cryptobot/80c6654b7c8d5529cc365f1124cef50e). This is required to protect the maintainers of Cryptomator from legal problems with patent or copyright infringement. The CLA signature process is triggered by your first pull request automatically. You will be asked to authenticate with your GitHub account and your username will be stored even if you revoke any activity on GitHub. --- # Glossary ## Terms[​](#terms "Direct link to Terms") ### Account Key[​](#account-key "Direct link to Account Key") A sequence of digits and characters that looks like this: `535cf7e3-f305-4d97-9309-dcce813183cf`. It is used to authorize new devices to access your Cryptomator Hub account. It can be looked up in the profile of existing devices. If you lose it, you can reset your account, however doing so will revoke access from all vaults. ### Recovery Key[​](#recovery-key "Direct link to Recovery Key") A human-readable representation of a vault's master key that is supposed to be printed out and archived for the case that you ever forget or lose access to your regular passphrase. ## Localization of Terms[​](#localization-of-terms "Direct link to Localization of Terms") warning Some of the terms mentioned above are carefully chosen to be distinguishable from another. This is particularly important for key material, as we deal with many different kinds of keys. **Mixing these up can cause confusion or even bear the risk of information exposure.** Translating technical terms shall be considered with great care. Here are our official recommendations to translators: 1. If using English terms in the realm of software is common practice in your native language, *do not translate* these terms. 2. Otherwise, if you feel uncertain about a translation, then better put the English term in parenthesis (if there is enough room). 3. Only if you are absolutely confident, that a translation precisely reflects the meaning as defined in this glossary, translate it. note We may add further terms in the future. If, for example, you deem it acceptable to translate *account* to something that has the same meaning as *user*, keep in mind that a translation of *account key* may eventually collide with *user key*. --- # Manual Migration Under some circumstances, Cryptomator refuses to automatically migrate a vault to a newer format. In this case, your vault will remain untouched, so you can continue using it with the previous version. To upgrade to the latest version, you can perform a migration manually: 1. Unlock the vault with the previous version of Cryptomator that you have used. You can find downloads of older versions [on our GitHub site](https://github.com/cryptomator/cryptomator/releases/). 2. Copy all files from this vault onto a temporary storage location on your computer. Be aware that these files are decrypted. 3. Once finished, lock your vault and quit Cryptomator. Now install the latest version of Cryptomator. 4. Create new vault with the latest version of Cryptomator and unlock it. 5. Copy all files from step 2 into the new vault. note One reason why automatic migration is impossible might be the fact that your vault is stored in a location that limits filename or path lengths, such as: * Network drives on Windows, such as WebDAV mounts * eCryptfs-encrypted volumes on Linux In this case, during step 5, you may encounter warnings indicating that you can not encrypt files due to such length limitations. Feel free to simply change the name of any affected files. --- # Supported Cloud Services A standard use case for Cryptomator is storing your encrypted vaults in a Cloud Service of your choice for safe and private synchronization of your data. When using Cryptomator for Desktop, you will need to have your Cloud Service's synchronization software installed on your computer to access cloud-based vaults. In comparison, Cryptomator for Android and Cryptomator for iOS support access to vaults that are stored with a range of Cloud Services directly from within the app. While the Cryptomator for Android and Cryptomator for iOS apps offer native support for a growing number of cloud services, it can happen, especially with smaller ones, that your Cloud Service is not natively supported. In this case, however, most providers allow you to connect to your vaults via WebDAV instead. note Depending on how well it is supported by your provider, individual features may not work optimally when using WebDAV. If possible, *we therefore recommend that you access your data using the native integration* of your Cloud Service for an optimal user experience. The following sections will provide you with an overview of [natively supported Cloud Services](#natively-supported-cloud-services), as well as information about [selected Cloud Services with WebDAV support](#cloud-services-with-webdav-support) and a list of [incompatible Cloud Services](#incompatible-cloud-services). ## Natively Supported Cloud Services (Recommended)[​](#natively-supported-cloud-services "Direct link to Natively Supported Cloud Services (Recommended)") The following Cloud Services are natively supported by Cryptomator for Android and/or Cryptomator for iOS. | Cloud Service | Android [1](#user-content-fn-android-recommendation) | iOS | | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | --- | | Dropbox | ✅ [2](#user-content-fn-no-fdroid-main) | ✅ | | Google Drive | ✅ [2](#user-content-fn-no-fdroid-main) [3](#user-content-fn-no-fdroid-cryptomator) [4](#user-content-fn-no-accrescent) | ✅ | | OneDrive | ✅ [2](#user-content-fn-no-fdroid-main) | ✅ | | pCloud | ✅ [2](#user-content-fn-no-fdroid-main) | ✅ | | S3 | ✅ | ✅ | | Box.com | ❌ | ✅ | | iCloud | ❌ | ✅ | | Local device storage | ✅ | ✅ | | Spaces provided by other apps [5](#user-content-fn-file-providers) | ✅ | ✅ | | WebDAV [6](#user-content-fn-webdav-list) | ✅ | ✅ | ## Cloud Services With WebDAV Support[​](#cloud-services-with-webdav-support "Direct link to Cloud Services With WebDAV Support") The following *non-exhaustive* table lays out information about Cloud Services that can be accessed using WebDAV by both Cryptomator for Android and Cryptomator for iOS. | Cloud Service | URL | | --------------------------------------------------- | --------------------------------------------------------- | | 1&1 Online-Speicher (DSL) | `https://sd2dav.1und1.de` | | 1&1 Online-Speicher (Webhosting) | `https://webdav.office.1und1.de` | | blaucloud | `https://{username}.blaucloud.de/remote.php/webdav` | | Disroot [7](#user-content-fn-disroot) | `https://cloud.disroot.org/remote.php/webdav/` | | freenetcloud | `https://webmail.freenet.de/webdav` | | GMX MediaCenter | `https://webdav.mc.gmx.net` | | HiDrive IONOS [8](#user-content-fn-hidrive-ionos) | `https://webdav.hidrive.ionos.com` | | HiDrive Strato [9](#user-content-fn-hidrive-strato) | `https://webdav.hidrive.strato.com` | | IceDrive [10](#user-content-fn-icedrive) | `https://webdav.icedrive.io/` | | kDrive [11](#user-content-fn-kdrive) | `https://connect.drive.infomaniak.com` | | Koofr [12](#user-content-fn-koofr) | `https://app.koofr.net/dav/Koofr` | | MagentaCLOUD [13](#user-content-fn-magentacloud) | `https://magentacloud.de/remote.php/webdav` | | Mailbox.org | `https://dav.mailbox.org/servlet/webdav.infostore/` | | Mail.Ru | `https://webdav.cloud.mail.ru` | | Nextcloud [14](#user-content-fn-nextcloud) | `https://{host}/{path}/remote.php/dav/files/{username}` | | OpenCloud [15](#user-content-fn-opencloud) | `https://{host}/remote.php/dav/spaces/{space-id}` | | ownCloud [16](#user-content-fn-owncloud) | `https://{host}/{path}/remote.php/webdav` | | pCloud (EU) [17](#user-content-fn-pcloud) | `https://ewebdav.pcloud.com` | | pCloud (US) [17](#user-content-fn-pcloud) | `https://webdav.pcloud.com` | | Seafile (self-hosted) | `https://{host}/{path}/seafdav` | | STACK | `https://{username}.stackstorage.com/remote.php/webdav` | | SWITCHdrive | `https://drive.switch.ch/remote.php/dav/files/{username}` | | Syncwerk (formerly Seafile.de) | `https://app.syncwerk.com/seafdav` | | WEB.DE Online-Speicher | `https://webdav.smartdrive.web.de` | | wölkli | `https://cloud.woelkli.com/remote.php/webdav` | | Yandex.Disk [18](#user-content-fn-yandex) | `https://webdav.yandex.com` | ## Incompatible Cloud Services[​](#incompatible-cloud-services "Direct link to Incompatible Cloud Services") The Cloud Services listed in the following *non-exhaustive* table can currently **not** be used natively or via WebDAV. This applies to both Cryptomator for Android and Cryptomator for iOS. | Cloud Service | Android Feature Request | iOS Feature Request | | ------------- | ------------------------------------------------------- | ----------------------------------------------------- | | Mega | [#39](https://github.com/cryptomator/android/issues/39) | [#258](https://github.com/cryptomator/ios/issues/258) | ## Footnotes[​](#footnote-label "Direct link to Footnotes") 1. **We recommend using the** [**Google Play Store variant**](/android/setup/.md#google-play-store) **of Cryptomator for Android users** for the best experience. Please see [here](/android/setup/.md#differences-between-variants-and-how-to-choose) for more information about the different Cryptomator for Android variants and the reasoning behind those. [↩](#user-content-fnref-android-recommendation) 2. Not supported by the [Main F-Droid repo variant](/android/setup/.md#main-f-droid-repository) because this Cloud Service requires an API key. [↩](#user-content-fnref-no-fdroid-main) [↩2](#user-content-fnref-no-fdroid-main-2) [↩3](#user-content-fnref-no-fdroid-main-3) [↩4](#user-content-fnref-no-fdroid-main-4) 3. Not supported by the [Cryptomator F-Droid repo variant](/android/setup/.md#cryptomator-f-droid-repository) because this Cloud Service requires proprietary dependencies. [↩](#user-content-fnref-no-fdroid-cryptomator) 4. Not supported by the [Accrescent variant](/android/setup/.md#accrescent) because this Cloud Service requires proprietary dependencies. [↩](#user-content-fnref-no-accrescent) 5. Some Android and iOS apps integrate into the operating system's file manager with their own storage spaces to allow seamless access to their files via "File Providers." Cryptomator generally supports saving vaults in those spaces, but is dependent on those apps explicitly supporting access by other apps like Cryptomator. For more technical information about this see [here](https://github.com/cryptomator/android/issues/553) for Android and [here](https://github.com/cryptomator/ios/issues/51) for iOS. [↩](#user-content-fnref-file-providers) 6. Please see [Cloud Services with WebDAV support](#cloud-services-with-webdav-support) for a non-exhaustive list of Cloud Services and information about accessing them with WebDAV. [↩](#user-content-fnref-webdav-list) 7. Disroot: To login, you must provide your disroot username (or your email if you are using your own domain) and your password. If 2FA is enabled you will have to generate an app-specific password. [↩](#user-content-fnref-disroot) 8. HiDrive IONOS: When using 2FA WebDAV requires the OTP provided next to the password but it is only valid for 30 minutes then (see [here \[de\]](https://www.ionos.de/hilfe/hidrive/sicherheit-in-hidrive/aktivieren-der-zwei-faktor-authentifizierung/)) [↩](#user-content-fnref-hidrive-ionos) 9. HiDrive Strato: When using 2FA WebDAV requires the OTP provided next to the password but it is only valid for 60 minutes then (see [here \[de\]](https://www.strato.de/faq/cloud-speicher/2-Faktor-Authentifizierung/)) [↩](#user-content-fnref-hidrive-strato) 10. IceDrive: WebDAV requires a paid plan and a separate access key as password. (see [here](https://icedrive.net/help/account/does-icedrive-support-webdav)) [↩](#user-content-fnref-icedrive) 11. kDrive: WebDAV support is disabled for free users. [↩](#user-content-fnref-kdrive) 12. Koofr: WebDAV access requires a separate app password. [↩](#user-content-fnref-koofr) 13. MagentaCLOUD: WebDAV access requires a separate protocol password. [↩](#user-content-fnref-magentacloud) 14. Nextcloud: WebDAV requires an app-specific password when 2FA is enabled. [↩](#user-content-fnref-nextcloud) 15. OpenCloud: WebDAV requires an App Token generated from Settings > App Tokens. The `{space-id}` is obtained from the info panel of the resource in OpenCloud. [↩](#user-content-fnref-opencloud) 16. ownCloud: WebDAV requires an app-specific password when 2FA is enabled. [↩](#user-content-fnref-owncloud) 17. pCloud: WebDAV access is disabled when 2FA is enabled. Requires a paid plan. [↩](#user-content-fnref-pcloud) [↩2](#user-content-fnref-pcloud-2) 18. Yandex.Disk: WebDAV requires an app-specific password when 2FA is enabled. [↩](#user-content-fnref-yandex) --- # Vault Format History Cryptomator vaults need to adhere to a structure and format (as described in [Security Architecture](/security/architecture/.md)) that may change over time. In order to identify the correct format, the masterkey file contains a version number, which represents the vault format. ## Format 8[​](#format-8 "Direct link to Format 8") Introduced in Cryptomator 1.6.0 on 2021-10-19. The following changes are: * Decoupled vault configuration from key derivation by introducing new vault configuration file named `vault.cryptomator`. It is a JWT containing basic information about the vault and specification what key to use. * `version` inside `masterkey.cryptomator` is now deprecated. ## Format 7[​](#format-7 "Direct link to Format 7") Introduced in Cryptomator 1.5.0 on 2020-04-16. The following changes are: * Added file extension (`*.c9r` and `*.c9s`) to all encrypted files and directories. Certain cloud storage services have issues with files without an extension. * Encrypted directories are now actually directories. Directory file is now inside of that with the fixed name `dir.c9r`. * Encrypted symlinks are now directories. Symlink file is now inside of that with the fixed name `symlink.c9r`. * Files and directories with shortened filenames are now directories (identifiable by the `.c9s` suffix). Mapping file with the long filename is now inside of that with the fixed name `name.c9s`. If it's a regular file, the content file has the fixed name `contents.c9r`. * Removed directory `m` because mapping files for shortened filenames are now in `d` as well. * Filenames are encoded with base64url so that name shortenings are less likely. * Increased ciphertext filename threshold to 220 characters. This is an example of the vault structure: ``` . ├─ d │ ├─ BZ │ │ └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA │ │ ├─ 5TyvCyF255sRtfrIv__83ucADQ==.c9r # regular file │ │ ├─ FHTa55bH_sUfVDbEb0gTL9hZ8nho.c9r # irregular file... │ │ │ └─ dir.c9r # ...which is a directory │ │ ├─ gLeOGMCN358_UBf2Qk9cWCQl.c9r # irregular file... │ │ │ └─ symlink.c9r # ...which is a symlink │ │ ├─ IjTsXtReTy6bAAuxzLPV9T0k2vg=.c9s # shortened name... │ │ │ ├─ contents.c9r # ...which is a regular file │ │ │ └─ name.c9s # ...mapping to this full name │ │ ├─ q2nx5XeNCenHyQvkFD4mxYNrWpQ=.c9s # shortened name... │ │ │ ├─ dir.c9r # ...which is a directory │ │ │ └─ name.c9s # ...mapping to this full name │ │ ├─ u_JJCJE-T4IH-EBYASUp1u3p7mA=.c9s # shortened name... │ │ │ ├─ name.c9s # ...mapping to this full name │ │ │ └─ symlink.c9r # ...which is a symlink │ │ └─ ... │ └─ FC │ └─ ZKZRLZUODUUYTYA4457CSBPZXB5A77 │ └─ ... ├─ masterkey.cryptomator └─ masterkey.cryptomator.DFD9B248.bkup ``` ## Format 6[​](#format-6 "Direct link to Format 6") Introduced in Cryptomator 1.3.0 on 2017-07-01. The following changes are: * Password is normalized in NFC. ## Format 5[​](#format-5 "Direct link to Format 5") Introduced in Cryptomator 1.2.0 on 2016-09-19. The following changes are: * Dropped file size obfuscation support. File sizes can be determined in `O(1)` instead of having to read and decrypt the file header. This allows showing file sizes in the directory listing without having to download each file first. The file size in the header is now unused and filled with `0xFFFFFFFFFFFFFFFF`. ## Format 4[​](#format-4 "Direct link to Format 4") Introduced in Cryptomator 1.1.1 on 2016-07-08. The following changes are: * Directories now have `0` (zero) prefix instead of a `_` (underscore) suffix. Directories are now stored with different names to avoid conflicts with the naming scheme of certain cloud storage services in case of synchronization conflicts. This is an example of the vault structure: ``` . ├─ d │ ├─ BZ │ │ └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA │ │ ├─ 0USJ7VD36K7YU2RARYJMEFTABZOGN6LUH63VRH5MADVOZ433VZ7EPSM2PLJPHTBL6 │ │ ├─ 0YWVRCCROEC3ZECD2UTJR7BGYERU3LG6R7QODBGMZ7EQ3BXGY24====== │ │ ├─ ... │ │ ├─ YWBBP7RC6FFX6ZN4YBLN4WXD6IIBTMKXHFFDQEZNYTQLNZWOGDT22EY= │ │ └─ ZTNHMICOWU6ZSNIR72ESLQSGDMLQYQ42XEKGOWSYYX5II=== │ └─ FC │ └─ ZKZRLZUODUUYTYA4457CSBPZXB5A77 │ └─ ... ├─ m │ └─ ... ├─ masterkey.cryptomator └─ masterkey.cryptomator.bkup ``` ## Format 3[​](#format-3 "Direct link to Format 3") Introduced in Cryptomator 1.0.0 on 2016-03-09. Vault format 3 is basically the official "first" version. To be exact, it was actually introduced in Cryptomator Beta 0.11 on 2016-03-03. Vault formats 1 and 2 were only used in beta versions of Cryptomator. This is an example of the vault structure: ``` . ├─ d │ ├─ BZ │ │ └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA │ │ ├─ USJ7VD36K7YU2RARYJMEFTABZOGN6LUH63VRH5MADVOZ433VZ7EPSM2PLJPHTBL6_ │ │ ├─ YWBBP7RC6FFX6ZN4YBLN4WXD6IIBTMKXHFFDQEZNYTQLNZWOGDT22EY= │ │ ├─ ... │ │ ├─ YWVRCCROEC3ZECD2UTJR7BGYERU3LG6R7QODBGMZ7EQ3BXGY24======_ │ │ └─ ZTNHMICOWU6ZSNIR72ESLQSGDMLQYQ42XEKGOWSYYX5II=== │ └─ FC │ └─ ZKZRLZUODUUYTYA4457CSBPZXB5A77 │ └─ ... ├─ m │ └─ ... ├─ masterkey.cryptomator └─ masterkey.cryptomator.bkup ``` --- # Security Architecture ## Virtual Filesystem[​](#virtual-filesystem "Direct link to Virtual Filesystem") Cryptomator provides a virtual drive. Add, edit, remove files as you're used to with just any disk drive. Files are transparently en- and decrypted. There are no unencrypted copies on your hard disk drive. With every access on your files inside the virtual drive, Cryptomator will en- and decrypt these files on-the-fly. Currently WinFsp (on Windows) and macFUSE (on macOS) and FUSE (Linux) are our frontends of choice. If they're not available on your system, Cryptomator will fall back on WebDAV, as it is supported on every major operating system. WebDAV is an HTTP-based protocol and Cryptomator acts as a WebDAV server accepting so-called loopback connections on your local machine only. Whenever your file manager accesses files through this virtual drive, Cryptomator will process this request via the following layers. ## Vault Configuration[​](#vault-configuration "Direct link to Vault Configuration") Every vault must have a vault configuration file named `vault.cryptomator` in the root directory of the vault. It is a JWT containing basic information about the vault and specification what key to use. The JWT is signed using the 512 bit raw masterkey. This is an example of an encoded vault configuration file: ``` eyJraWQiOiJtYXN0ZXJrZXlmaWxlOm1hc3RlcmtleS5jcnlwdG9tYXRvciIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJmb3JtYXQiOjgsInNob3J0ZW5pbmdUaHJlc2hvbGQiOjIyMCwianRpIjoiY2U5NzZmN2EtN2I5Mi00Y2MwLWI0YzEtYzc0YTZhYTE3Y2Y1IiwiY2lwaGVyQ29tYm8iOiJTSVZfQ1RSTUFDIn0.IJlu4dHb3fqB2fAk9lf8G8zyEXc7OLB-5m9aNxOEXIQ ``` The decoded header: ``` { "kid": "masterkeyfile:masterkey.cryptomator", /* URI of where to get the key */ "typ": "JWT", "alg": "HS256" /* current implementations also support HS384 and HS512 */ } ``` The decoded payload: ``` { "format": 8, /* vault format for checking software compatibility */ "shorteningThreshold": 220, /* how many characters in ciphertext filenames before shortening */ "jti": "ce976f7a-7b92-4cc0-b4c1-c74a6aa17cf5", /* random UUID to uniquely identify the vault */ "cipherCombo": "SIV_GCM" /* mode of operation for the block cipher. Other possible values are "SIV_CTRMAC" */ } ``` When opening a vault, the following steps have to be followed: 1. Decode `vault.cryptomator` without verification. 2. Read `kid` header and, depending on its value, retrieve the masterkey from the specified location. 3. Verify the JWT signature using the concatenation of encryption masterkey and MAC masterkey. 4. Make sure `format` and `cipherCombo` are supported. ## Masterkey[​](#masterkey "Direct link to Masterkey") Each vault has its own 256 bit encryption as well as MAC masterkey used for encryption of file specific keys and file authentication, respectively. All key material is generated by a CSPRNG (Cryptographically secure pseudorandom number generator). * In Java (Desktop, Android App), we use [SecureRandom](https://docs.oracle.com/javase/8/docs/api/java/security/SecureRandom.html) with SHA1PRNG, seeded with 440 bits from `SecureRandom.getInstanceStrong()`. * In Javascript (Cryptomator Hub), we rely on [crypto.subtle.generateKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey). * In Swift (iOS App), we use [SecRandomCopyBytes](https://developer.apple.com/documentation/security/1399291-secrandomcopybytes) with `kSecRandomDefault`. These keys are themselves protected and can be retrieved using, either of the following methods, depending on the use case: ### Using Cryptomator Hub[​](#using-cryptomator-hub "Direct link to Using Cryptomator Hub") When using [Cryptomator Hub](/hub/introduction/.md), the encrypted raw masterkey can be retrieved from the server component. note If a vault is managed by Cryptomator Hub, the `vault.cryptomator`'s `kid` field will point to the resource URI of said vault on the corresponding Hub instance, prefixed by `hub+`. Example: `"kid": "hub+https://hub.example.com/api/vaults/bb36d67c"` Every Cryptomator Hub user who is authorized to access this vault will retrieve an individual ciphertext from the vault's `/access-token` sub-resource. This ciphertext is formatted as a [JWE](https://tools.ietf.org/html/rfc7516) and can be decrypted using [ECDH-ES](https://datatracker.ietf.org/doc/html/rfc7518#section-4.6) and the user's static private key. The JWE's decoded header looks something like this: ``` { "alg": "ECDH-ES", "enc": "A256GCM", "epk": { "crv": "P-384", "kty": "EC", "x": "p1J...g", "y": "8Il...H" } "apu": "", "apv": "" } ``` The JWE's decrypted payload holds a single value, which can then be consumed by Cryptomator to unlock the vault: ``` { "key": "H7u...o==" /* 512 bit raw masterkey */ } ``` ### Masterkey File[​](#masterkey-file "Direct link to Masterkey File") Alternatively, for normal password-protected vaults, Cryptomator will derive a 32byte long KEK (Key-encryption key) via [scrypt](https://tools.ietf.org/html/rfc7914) (non-parallel), encrypt both masterkeys using [AES Key Wrap (RFC 3394)](https://tools.ietf.org/html/rfc3394), and store the results together with the key derivation parameters in a JSON file: ``` encryptionMasterKey := createRandomBytes(32) macMasterKey := createRandomBytes(32) kek := scrypt(password, scryptSalt, scryptCostParam, scryptBlockSize) wrappedEncryptionMasterKey := aesKeyWrap(encryptionMasterKey, kek) wrappedMacMasterKey := aesKeyWrap(macMasterKey, kek) ``` ![KEK Derivation](/img/security/key-derivation.png) The wrapped keys and the parameters needed to derive the KEK are then stored as integers or Base64-encoded strings in a JSON file named `masterkey.cryptomator`, which is located in the root directory of the vault. ``` { "version": 999, /* deprecated, vault format is now specified in the vault configuration */ "scryptSalt": "QGk...jY=", "scryptCostParam": 32768, "scryptBlockSize": 8, "primaryMasterKey": "QDi...Q==", /* wrappedEncryptionMasterKey */ "hmacMasterKey": "L83...Q==", /* wrappedMacMasterKey */ "versionMac": "3/U...9Q=" /* HMAC-256 of vault version to prevent undetected downgrade attacks */ } ``` note When calculating the `versionMac`, the `version` value must be converted to a 32-bit unsigned integer and then encoded as a 4-byte big-endian representation before computing the HMAC-SHA256, regardless of the system's native byte order. When unlocking a vault the KEK is used to unwrap (i.e. decrypt) the stored masterkeys. ![Masterkey Decryption](/img/security/masterkey-decryption.png) --- # Best Practices ## Sharing of Vaults[​](#sharing-of-vaults "Direct link to Sharing of Vaults") When sharing your vault or working in a team, we strongly recommend using [Cryptomator Hub](https://cryptomator.org/for-teams/). It adds access management for your vaults and allows you to unlock vaults with your own account. Otherwise, always be careful when sharing your vault with other people. In general, keep your vault password secret. Nobody except yourself should know the vault password. Sharing your vault password should be reserved for very limited personal scenarios (for example, with your spouse) and is generally not advised. Keep in mind that other people could pass on – with or without intent – the vault password. Only share your vaults with people you trust. If you share a vault with others, do not communicate the vault password on an insecure channel. Tell the password in person, use encrypted email or messengers or other similar secure means. ## Good Passwords[​](#good-passwords "Direct link to Good Passwords") Bad passwords can be cracked easily when using computers. Plenty of recommendations exist for secure passwords. Some of these are: * A password should not contain public or personal information like the name of your pet, date of birth, or username. * A password should be long. * A password should not be an existing word or a combination of few words. It should be a combination of characters or words that is as random as possible. * For each purpose, a unique password without similarities to other passwords should be used. If you fulfill these requirements, you quickly reach a point where remembering the passwords gets impossible. Thus, we recommend using a password manager to generate and store the passwords. By doing so, you only have to remember a few or a single secure password. Otherwise, we recommend using at least 10 characters, ideally [use sentences instead of words](https://xkcd.com/936/). ### Keyboard Layouts and Special Characters[​](#keyboard-layouts-and-special-characters "Direct link to Keyboard Layouts and Special Characters") Be aware that keyboard layout differences can affect password entry. When creating a password, consider these important points: * Use the same keyboard layout when entering your password. Characters may produce different results depending on your keyboard language setting. * Some keyboard layouts use "dead keys" for accented characters. For example, pressing `'` followed by `e` might produce `é` instead of `'e`. This can cause unexpected character conversion in passwords. * Characters like `'`, `"`, `` ` ``, `^`, and `~` may behave differently across keyboard layouts and can be particularly problematic. To avoid issues: * Test your password immediately after setting it by locking and unlocking your vault. * Avoid special characters that may be affected by dead keys if you frequently switch between keyboard layouts. * If you must use different keyboard layouts, document which layout was used when creating the password. * Consider using alphanumeric characters and basic symbols that remain consistent across keyboard layouts. ## Backup Strategy[​](#backup-strategy "Direct link to Backup Strategy") Cryptomator is not a backup solution. Its primary and only purpose is client-side encryption. We strongly recommend maintaining your own backup strategy. Even with unencrypted data, regular backups are essential. Most cloud storage services offer some form of backup or file revision capabilities. Evaluate if those available measures are sufficient for your needs or consider implementing additional backup systems. --- # Cryptomator Hub Cryptomator Hub facilitates asymmetric encryption to allow sharing the key material used in Cryptomator vaults between multiple parties. ## Zero-Knowledge Data Flow[​](#zero-knowledge-data-flow "Direct link to Zero-Knowledge Data Flow") The following diagram illustrates how Cryptomator Hub maintains zero-knowledge encryption throughout the entire data flow between users sharing a vault. This architecture ensures that neither Cryptomator Hub nor your cloud storage provider ever has access to your unencrypted data. ![Hub Data Flow](/img/hub/data-flow.svg) In this architecture, each component plays a specific role while maintaining the zero-knowledge principle. User devices handle all encryption and decryption operations locally within their [virtual file systems](/security/architecture/.md#virtual-filesystem). The encrypted vault data resides in your chosen [cloud storage provider](/misc/supported-cloud-services/.md), where it remains indecipherable without the proper keys. Cryptomator Hub acts solely as a key broker, managing encrypted [access tokens](#unlock-procedure) through the [User](#user-key-pair) and [Device](#device-key-pair) Key Pairs described below. The Hub never has access to [vault keys](/security/architecture/.md#masterkey) in cleartext, ensuring that even a compromised Hub instance cannot decrypt vault contents. Keycloak handles authentication through your existing identity provider, verifying user identities before granting access to encrypted vault keys. This separation of authentication from key management adds an additional security layer while enabling seamless integration with your organization's existing infrastructure. ## Key Types[​](#key-types "Direct link to Key Types") Cryptomator Hub facilitates different keys types. Here is an overview of these types and how they are interconnected: ### User Key Pair[​](#user-key-pair "Direct link to User Key Pair") During first login, every user will generate a new EC key pair. The private key is then encrypted using both the [Account Key](#account-key) as well as the [Device Key](#device-key-pair) of every single device owned by this user. The purpose of the user key is to access secrets that have been shared with this user using [ECDH-ES-encrypted JWEs](https://datatracker.ietf.org/doc/html/rfc7518.html#section-4.6), most prominently the masterkey of shared vaults. If users wish to rotate their keys, e.g. when a device may be compromised, they can simply re-roll the key pair, re-encrypt secrets that they whish to keep access to and delete the old key pair. ### Device Key Pair[​](#device-key-pair "Direct link to Device Key Pair") Every device requires a key pair, which is generated on first use. The private key is securely stored on-device and not intended to ever leave it. For example, on web browsers the private key is [non-extractable](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey#extractable) and stored in the browser's IndexedDB. note A *device* is any client that interacts with Cryptomator Hub on behalf of a user. This definition includes the web browser used to access the Hub web interface as well as the mobile app on a user's smartphone. On multi-user systems, every user is expected to have a separate user account, in which case we're talking about multiple devices with distinct key pairs, even if they share the same hardware. The sole purpose of the device key is to decrypt the [User Key](#user-key-pair), which is stored in a device-specific [ECDH-ES-encrypted JWE](https://datatracker.ietf.org/doc/html/rfc7518.html#section-4.6). Users can invalidate devices by simply deleting the device-specific JWE and rotating their user key. ### Account Key[​](#account-key "Direct link to Account Key") When users attempt to access their account from a new device, there is no device-specific JWE yet. Instead they can then use the Account Key to decrypt the [User Key](#user-key-pair). The Account Key acts as a password to derive a key for a [PBES2-encrypted JWE](https://datatracker.ietf.org/doc/html/rfc7518.html#section-4.8). warning The Account Key needs to be kept secret, as it is the only user-facing secret that allows anyone knowing it to authorize as the corresponding user. When an Account Key is suspected of being compromised, it can and should be re-generated from the user's profile page, which will immediately invalidate any circulating copies. note The Account Key itself is stored as an [ECDH-ES-encrypted JWE](https://datatracker.ietf.org/doc/html/rfc7518.html#section-4.6), allowing its owner to view it from any authorized device. Regardless it should be securely stored independently. ## Unlock Procedure[​](#unlock-procedure "Direct link to Unlock Procedure") Vault keys are shared with users via their [User Key Pairs](#user-key-pair). Each user self-manages their devices. The [Device Key Pair](#device-key-pair) is required to decrypt the user's private key, which in turn decrypts the vault access token. ![Hub Unlock Procedure](/img/hub/unlock-procedure.svg) ### Unlock Flow[​](#unlock-flow "Direct link to Unlock Flow") The unlock procedure consists of two distinct steps that establish a key hierarchy between devices, users, and vaults: 1. The client requests the vault access token from `/api/vaults/{vaultId}/access-token`. The server returns a JWE containing the vault's raw masterkey encrypted with the [User Public Key](#user-key-pair). 2. The client requests its device-specific JWE from `/api/devices/{deviceId}`. This JWE contains the [User Private Key](#user-key-pair) encrypted with the [Device Public Key](#device-key-pair). The device uses its locally stored private key to decrypt this JWE, obtaining the user's private key, which is then used to decrypt the vault-specific JWE from step 1. This creates a cryptographic chain: Device Private Key → User Private Key → Vault Key. The intermediary user key layer allows vault keys to be encrypted once per user rather than once per device. When users add new devices, only a new device-specific JWE of the user key needs to be created, eliminating the need to re-encrypt all vault keys. ### Access States[​](#access-states "Direct link to Access States") When retrieving the vault access token from `/api/vaults/{vaultId}/access-token`: * `200 OK`: Successful retrieval of encrypted vault key * `402 Payment Required`: License needs upgrade * `403 Forbidden`: User lacks permission to access the vault * `410 Gone`: Vault has been archived * `449 Retry With`: User account exists but hasn't been properly initialized (missing key pair) When retrieving the user's encrypted private key from `/api/devices/{deviceId}`: * `200 OK`: Device is registered and authorized * `404 Not Found`: Device needs to be set up We still keep the legacy API endpoint `/api/vaults/{vaultId}/keys/{deviceId}` for compatibility reasons for a while. However, it will only work for existing data. Any newly registered device can only be unlocked using the new workflow. --- # Security Target Cryptomator was designed to solve privacy issues when saving files to cloud storages. ## What Cryptomator Is[​](#what-cryptomator-is "Direct link to What Cryptomator Is") Cryptomator is a client-side encryption tool for cloud storage services. The risk that the cloud provider or third parties access the data stored in the cloud without permission is mitigated. Only people who know the vault password are able to read the files in the vault or change the file contents undetected. This is true for file contents as well as for filenames. ## What Cryptomator Encrypts[​](#what-cryptomator-encrypts "Direct link to What Cryptomator Encrypts") Cryptomator encrypts: * file contents, * file and folder names, and * the directory structure is obfuscated. For technical details on how these elements are encrypted, see [Vault Cryptography](/security/vault/.md). ## What Cryptomator Is Not[​](#what-cryptomator-is-not "Direct link to What Cryptomator Is Not") In addition, you have to keep in mind what Cryptomator is not. Protection of the files on the local computer is not the focus of Cryptomator. Cryptomator cannot provide protection if the local computer is infected with malware which reads entered passwords and file contents (e.g., files in an unlocked vault). Cryptomator does not provide protection if programs create backup copies of the encrypted files when working with them. Such files are not detected by Cryptomator and may remain on the computer even after unlocking a vault. Cryptomator is not a complete replacement for other encryption tools based on container files if metadata (like file sizes and timestamps) should be encrypted. Cryptomator is not a [steganography tool](https://en.wikipedia.org/wiki/Steganography). It uses recognizable file extensions (`.c9r`, `.c9s`) and stores configuration files (`vault.cryptomator`, `masterkey.cryptomator`) that make it evident that data is encrypted using Cryptomator. The security of your data relies on strong encryption and a secure password, not on hiding the fact that encryption is being used. To protect against such risks, other methods, like complete disk encryption, immediate installation of system and software updates, and the use of applicable antivirus software, is required. ## What Cryptomator Does Not Encrypt[​](#what-cryptomator-does-not-encrypt "Direct link to What Cryptomator Does Not Encrypt") To allow a working synchronization with the cloud, there are some metadata that Cryptomator does not encrypt. These are: * access, modification, and creation timestamps of files and folders, * number of files and folders in a vault and in the folders, and * size of the stored files. ## Accepted Risks[​](#accepted-risks "Direct link to Accepted Risks") ### Filename Swapping Within Same Directory[​](#filename-swapping-within-same-directory "Direct link to Filename Swapping Within Same Directory") An attacker with write access to your cloud storage could swap encrypted filenames within the same directory. While the contents of the files remain secure and any tampering with file contents would be detected, the swapped filenames would not be detected. This is considered a **low risk** vulnerability because: * It requires an attacker to already have write access to your vault * File contents remain encrypted and tamper-proof * The attack only affects filename-to-content mapping within a single directory This is an accepted risk because implementing cryptographic binding between filenames and contents would significantly impact performance, especially on mobile devices and remote storage systems. For more information, see the security advisory documented in [GHSA-qwfw-w5qf-7wcj](https://github.com/cryptomator/cryptomator/security/advisories/GHSA-qwfw-w5qf-7wcj). --- # Vault Cryptography ## File Header Encryption[​](#file-header-encryption "Direct link to File Header Encryption") The file header stores certain metadata, which is needed for file content encryption. It consists of 68 bytes. * 12 bytes nonce used during header payload encryption. * 40 bytes [AES-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode) encrypted payload consisting of: * 8 bytes filled with 1 for future use (formerly used for file size) and * 32 bytes file content key. * 16 bytes tag of the encrypted payload. ``` headerNonce := createRandomBytes(12) contentKey := createRandomBytes(32) cleartextPayload := 0xFFFFFFFFFFFFFFFF . contentKey ciphertextPayload, tag := aesGcm(cleartextPayload, encryptionMasterKey, headerNonce) ``` ![File Header Encryption](/img/security/file-header-encryption.png) \*Random per file change ## File Content Encryption[​](#file-content-encryption "Direct link to File Content Encryption") This is where your actual file contents get encrypted. The cleartext is broken down into multiple chunks, each up to 32 KiB + 28 bytes consisting of: * 12 bytes nonce, * up to 32 KiB encrypted payload using AES-GCM with the file content key, and * 16 bytes tag computed by GCM with the following AAD: * chunk number as 64 bit big endian integer (to prevent undetected reordering), * file header nonce (to bind this chunk to the file header), Afterwards, the encrypted chunks are joined preserving the order of the cleartext chunks. The payload of the last chunk may be smaller than 32 KiB. ``` cleartextChunks[] := split(cleartext, 32KiB) for (int i = 0; i < length(cleartextChunks); i++) { chunkNonce := createRandomBytes(12) aad := bigEndian(i) . headerNonce ciphertextPayload, tag := aesGcm(cleartextChunks[i], contentKey, chunkNonce, aad) ciphertextChunks[i] := chunkNonce . ciphertextPayload . tag } ciphertextFileContent := join(ciphertextChunks[]) ``` ![File Content Encryption](/img/security/file-content-encryption.png) \*Random per chunk change ## Directory IDs[​](#directory-ids "Direct link to Directory IDs") Each directory has a unique ID that is required during filename encryption. For historical reasons, the directory ID is a string, even though any byte sequence would do the job. The directory ID for the root directory is the empty string. For all other directories, it is a random sequence of at most 36 ASCII chars. We recommend using random UUID (Universally unique identifier). ``` dirId := createUuid() ``` When traversing directories, the directory ID of a given subdirectory is processed in four steps to determine the storage path inside the vault: 1. Encrypting the directory ID using [AES-SIV](https://tools.ietf.org/html/rfc5297) in order to encrypt directory hierarchies. 2. Creating a SHA1 hash of the encrypted directory ID in order to get a uniform length. 3. Encoding the hash with Base32 to get a string of printable chars. 4. Constructing the directory path out of the Base32-encoded hash. ``` dirIdHash := base32(sha1(aesSiv(dirId, null, encryptionMasterKey, macMasterKey))) dirPath := vaultRoot + '/d/' + substr(dirIdHash, 0, 2) + '/' + substr(dirIdHash, 2, 30) ``` Regardless of the hierarchy of cleartext paths, ciphertext directories are always stored in a flattened structure. All directories will therefore effectively be siblings (or cousins, to be precise). ## Filename Encryption[​](#filename-encryption "Direct link to Filename Encryption") The cleartext name of a file gets encoded using UTF-8 in [Normalization Form C](https://unicode.org/reports/tr15/#Norm*Forms) to get a unique binary representation. Cryptomator uses [AES-SIV](https://tools.ietf.org/html/rfc5297) to encrypt names. The directory ID of the parent folder is passed as associated data. This prevents undetected movement of files between directories. ![Filename Encryption](/img/security/filename-encryption.png) \*Unencrypted directory ID of the parent dir [as described above](#directory-ids) ``` ciphertextName := base64url(aesSiv(cleartextName, parentDirId, encryptionMasterKey, macMasterKey)) + '.c9r' ``` Depending on the kind of node, the encrypted name is then either used to create a file or a directory. * Files are stored as files. * Non-files are stored as directories. The type of the node then depends on the directory content. * Directories are denoted by a file called `dir.c9r` containing aforementioned directory ID. * Symlinks are denoted by a file called `symlink.c9r` containing the encrypted link target. * Further types may be appended in future releases. Thus, a cleartext directory structure like this: ``` . ├─ File.txt ├─ SymlinkToFile.txt ├─ Subdirectory │ └─ ... └─ ... ``` Becomes a ciphertext directory structure like this: ``` . ├─ d │ ├─ BZ │ │ └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA │ │ ├─ 5TyvCyF255sRtfrIv**83ucADQ==.c9r # File.txt │ │ ├─ FHTa55bH*sUfVDbEb0gTL9hZ8nho.c9r # Subdirectory │ │ │ └─ dir.c9r # contains dirId │ │ └─ gLeOGMCN358*UBf2Qk9cWCQl.c9r # SymlinkToFile.txt │ │ └─ symlink.c9r # contains link target │ └─ FC │ └─ ZKZRLZUODUUYTYA4457CSBPZXB5A77 # contains contents of Subdirectory │ └─ ... ├─ masterkey.cryptomator ├─ masterkey.cryptomator.DFD9B248.bkup └─ vault.cryptomator ``` ## Name Shortening[​](#name-shortening "Direct link to Name Shortening") note This layer doesn't provide any additional security. Its sole purpose is to maximize compatibility. To maximize compatibility, we need to make sure the ciphertext names don't exceed a length of 255 chars. As some cloud sync services might want to add a suffix to a file in case of conflicts, we decided to use at most 220 chars. If an encrypted name (including its `.c9r` extension) exceeds these 220 chars, we will instead create a directory named after its much shorter SHA-1 hash and the `.c9s` extension. Additionally we will create a reverse-mapping file named `name.c9s` containing the original file inside of this directory. ``` if (length(ciphertextName) > 220) { deflatedName := base64url(sha1(ciphertextName)) + '.c9s' inflatedNameFilePath := deflatedName + '/name.c9s' fileContentsPath := deflatedName + '/contents.c9r' symlinkFilePath := deflatedName + '/symlink.c9r' dirIdFilePath := deflatedName + '/dir.c9r' } ``` Again, we have to distinguish the kind of a node. * Non-files (such as symlinks or directories) are stored as a directory anyway. Nothing changes for them. * Files, on the other hand, need a different place to store their contents. Therefore, we introduce the `contents.c9r` file inside the `.c9s` directory. A vault containing several nodes with very long names might result in a ciphertext structure like this: ``` . ├─ d │ ├─ BZ │ │ └─ R4VZSS5PEF7TU3PMFIMON5GJRNBDWA │ │ ├─ 5TyvCyF255sRtfrIv**83ucADQ==.c9r │ │ ├─ FHTa55bH*sUfVDbEb0gTL9hZ8nho.c9r │ │ │ └─ dir.c9r │ │ ├─ gLeOGMCN358*UBf2Qk9cWCQl.c9r │ │ │ └─ symlink.c9r │ │ ├─ IjTsXtReTy6bAAuxzLPV9T0k2vg=.c9s # shortened name... │ │ │ ├─ contents.c9r # ...node is a regular file │ │ │ └─ name.c9s # ...mapping to this full name │ │ ├─ q2nx5XeNCenHyQvkFD4mxYNrWpQ=.c9s # shortened name... │ │ │ ├─ dir.c9r # ...node is a directory │ │ │ └─ name.c9s # ...mapping to this full name │ │ └─ u*JJCJE-T4IH-EBYASUp1u3p7mA=.c9s # shortened name... │ │ ├─ name.c9s # ...mapping to this full name │ │ └─ symlink.c9r # ...node is a symlink │ └─ FC │ └─ ZKZRLZUODUUYTYA4457CSBPZXB5A77 │ └─ ... ├─ masterkey.cryptomator ├─ masterkey.cryptomator.DFD9B248.bkup └─ vault.cryptomator ``` ## Backup Directory IDs[​](#backup-directory-ids "Direct link to Backup Directory IDs") note This layer is optional and not required for a complete implementation of the Cryptomator Encryption Scheme. It doesn't provide any additional security. Its sole purpose is to increase data recoverability in case of missing or damaged directory files. By obfuscating the hierarchy of cleartext paths using `dir.c9r` files, which contain [directory IDs](#directory-ids), the directory structure is more vulnerable to problems like incomplete synchronization or bit rotting. When a directory file is missing or damaged, the `dirPath` cannot be computed, which effectively makes the directory content inaccessible in the [virtual filesystem](/security/architecture/.md#virtual-filesystem). In theory, the contents of the encrypted content of these files can be recovered. But since the [filename encryption](#filename-encryption) is dependent on the directory ID of the parent folder, which is only stored in the directory file, names of all items (files, directories, or symlinks) are lost. To alleviate this issue, a backup directory file will be stored during the creation of a directory. Inside the ciphertext directory, a file named `dirid.c9r` will be created, which contains the directory ID of its parent folder. It is [encrypted](#file-content-encryption) like a regular ciphertext file. --- # Verify Installer Signatures If you are not sure whether an alleged Cryptomator installer is legitimate, you can verify its authenticity and integrity. ## GPG Signature[​](#gpg-signature "Direct link to GPG Signature") All Cryptomator release artifacts include a `.asc` signature file that you can use to verify authenticity and integrity using GPG. This method works on Windows, Linux, and macOS (with GPG installed). Download both the installer and the corresponding `.asc` signature file, then verify in the following steps: ![How to verify GPG signatures](/img/security/verify-gpg-signature.png) 1. Use `gpg --list-keys --fingerprint 58117AFA1F85B3EEC154677D615D449FE6E6A235` to make sure you have loaded the GPG key. If it is not available, download it from a keyserver e.g.: `gpg --keyserver keys.gnupg.net --recv-keys 58117AFA1F85B3EEC154677D615D449FE6E6A235` or another trusted source like from Cryptobot using Github `curl -sSL https://github.com/cryptobot.gpg | gpg --import -`. 2. Use `gpg --verify .asc ` to execute the verification process (replace `` with the actual filename of your downloaded installer). The message should say: 3. `gpg: Good signature from "Cryptobot "` 4. `Primary key fingerprint: 5811 7AFA 1F85 B3EE C154 677D 615D 449F E6E6 A235` If shown, you can ignore the following warning: `gpg: WARNING: This key is not certified with a trusted signature!` ## Windows (exe, msi)[​](#windows "Direct link to Windows (exe, msi)") Our Windows installers are signed using a code signing certificate. You can verify the signature in three simple steps: 1. Open Terminal or PowerShell (found in Windows Start menu). 2. Run either of the following commands to check the signature of the corresponding file: ``` Get-AuthenticodeSignature -FilePath "~\Downloads\Cryptomator-*.msi" Get-AuthenticodeSignature -FilePath "~\Downloads\Cryptomator-*.exe" ``` 3. Verify that the output includes: * Column `SignerCertificate` with value `F255C2D35DDB45D20CE854EBF393A266DB16736C`(\*) * Column `Status` with value `Valid` * no errors \*for older releases, see [below](#windows-all-versions). If the installer is properly signed, you should see output similar to: ``` SignerCertificate Status StatusMessage Path ----------------- ------ ------------- ---- BB0E... Valid Signature verified. Cryptomator-1.19.1-x64.msi ``` You can also inspect the certificate manually: 1. Right-click on the cryptomator installer file and click on Properties. 2. Select the Digital Signatures tab: It should show one or more signatures by `Skymatic GmbH` under Embedded Signatures. * For releases since 1.18.0, the `exe` release artifact will have two signatures, and the `msi` release artifact will have one signature. 3. Click on the first signature, and then click Details. 4. Click on View Certificates and select the field `Thumbprint`. ![How to check the code signing certificate on Windows](/img/security/verify-win-installer.png) ### Certificate thumbprints for all Cryptomator versions[​](#windows-all-versions "Direct link to Certificate thumbprints for all Cryptomator versions") Every Cryptomator installer is signed with a certificate. A certificate is identified by its thumbprint. The signing certificate changed over time and the following table shows for each version the certificate thumbprint: | Version(s) | Certificate Thumbprint | | ---------------- | ------------------------------------------ | | 1.19.3 | `F255C2D35DDB45D20CE854EBF393A266DB16736C` | | 1.19.2 | `20F30D7C5B1AB3ACAFA4AB27874ACBC4B47B0697` | | 1.19.1 | `BB0EEBF8E92E4584DF4B6AE4F9577B60BEB5DF4C` | | 1.19.0 | `14524B1F8A3A1CA8B24B769C7C6DC92851120B22` | | 1.18.1 | `53FA929F6D50D5E2AE59A7C9A9750D373AFF7D40` | | 1.18.0 | `4DC9A70B94F731562A9C37B4391C4FD5BEC72C94` | | 1.6.11 to 1.17.1 | `5FC94CE149E5B511E621F53A060AC67CBD446B3A` | | 1.4.12 to 1.6.10 | `FF52240075AD7D14AF25629FDF69635357C7D14B` | | up to 1.4.11 | `6FDEC9DFCFE59E6BAEE64B7ED97F00E120E70D97` | ## macOS (app)[​](#macos "Direct link to macOS (app)") On macOS, you can verify the code signature of the Cryptomator app using the built-in `codesign` utility. This verification confirms the app's authenticity and integrity: 1. Open Terminal (found in Applications > Utilities). 2. Run either of the following commands to check the signature of the corresponding file: ``` codesign -dv ~/Downloads/Cryptomator-*.dmg codesign -dv /Applications/Cryptomator.app ``` 3. Verify that the output includes: * `TeamIdentifier=YZQJQUHA3L` * The signature should be valid with no errors If the app is properly signed, you should see output similar to: ``` Executable=/Applications/Cryptomator.app/Contents/MacOS/Cryptomator Identifier=org.cryptomator ... TeamIdentifier=YZQJQUHA3L ``` ---