From bd2e4c0ad737d2cf45d945ce492d4a2e25faf4cd Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Mon, 7 Jul 2025 17:49:08 +0200 Subject: [PATCH 1/5] add section about storing passwords --- docs/desktop/password-and-recovery-key.md | 78 +++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/docs/desktop/password-and-recovery-key.md b/docs/desktop/password-and-recovery-key.md index ae442db..51132f7 100644 --- a/docs/desktop/password-and-recovery-key.md +++ b/docs/desktop/password-and-recovery-key.md @@ -54,6 +54,84 @@ The password is used to derive a [KEK](https://en.wikipedia.org/wiki/Glossary_of 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} + +:::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 keychain you are using. +::: + +By default Cryptomator does not store your vault's password on your hard drive. +It is only used to unlock the vault and destroyed afterwards. + +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`. + +This will store the password 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 accessing 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 created. +
+
+ 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 created. +
+ + ## Show Recovery Key {#show-recovery-key} You can derive a recovery key during vault creation or even later as long as you know your vault's password. From 432ae98d23d3119b771d6c6a6aef232c2cbdd419 Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Tue, 8 Jul 2025 15:05:51 +0200 Subject: [PATCH 2/5] fix minor text issues --- docs/desktop/password-and-recovery-key.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/desktop/password-and-recovery-key.md b/docs/desktop/password-and-recovery-key.md index 51132f7..c1bb15f 100644 --- a/docs/desktop/password-and-recovery-key.md +++ b/docs/desktop/password-and-recovery-key.md @@ -57,11 +57,12 @@ If you like to encrypt your vault files with a new, stronger password, you need ## Storing Passwords {#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 keychain you are using. +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 destroyed afterwards. +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 afterwards. 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. @@ -79,7 +80,7 @@ To store a password for a vault: 2. Tick the box `Remember Password` in the unlock dialog. 3. Enter the vault's password and click on `Unlock`. -This will store the password in the selected keychain, allowing you to unlock the vault without entering the password again. +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`. @@ -95,7 +96,7 @@ Available keychains are:
Touch ID (macOS) - Uses the built-in macOS keychain, but requires authentication with Touch ID before accessing the password. + 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. @@ -120,7 +121,7 @@ Available keychains are: 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 created. + Requires GNOME keyring to be installed and running on your Linux system, with the default keyring present.
KDE Wallet (Linux) @@ -128,7 +129,7 @@ Available keychains are: 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 created. + Requires KDE Wallet to be installed and running on your Linux system, with the default wallet present.
From 349f5629fd4d14e27ff2d705a672c31b0cde52df Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Tue, 8 Jul 2025 15:07:02 +0200 Subject: [PATCH 3/5] cross link section and dedup doc --- docs/desktop/accessing-vaults.md | 25 ++++++++++------------- docs/desktop/password-and-recovery-key.md | 5 +++++ 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/desktop/accessing-vaults.md b/docs/desktop/accessing-vaults.md index 908398f..ccf357b 100644 --- a/docs/desktop/accessing-vaults.md +++ b/docs/desktop/accessing-vaults.md @@ -12,29 +12,26 @@ You can only access decrypted files of a vault if you can unlock it. Unlocking a ## Unlocking a Vault {#unlocking-a-vault} -1. Select the vault you wish to unlock. -2. Click on the large `Unlock` button located at the center of the Cryptomator window. +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. - -A confirmation will be displayed if your password is correct. -You can either close the confirmation window by clicking `Done` or click on `Reveal Vault` to show your unlocked vault in your file manager. +4. Click the `Unlock` button. Vault unlock dialog :::note -You can store the password in your operating system's keychain by checking the "Save Password" checkbox. There are also plug-ins available for Cryptomator, that allow you to store Cryptomator's vault passwords in third party 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 - -With a saved password, you can unlock your vaults without typing a password on every unlock. It's faster. -::: +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](/docs/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 the computer with stored passwords will be able to unlock your vault, and in some cases, even find your password. +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 password. ::: +If your password is correct, a success message will be displayed, and the vault will be unlocked. +You can either close the success window by clicking `Done` or click on `Reveal Vault` to show your unlocked vault in the file manager. + Vault unlock success dialog ## Locking a Vault {#locking-a-vault} diff --git a/docs/desktop/password-and-recovery-key.md b/docs/desktop/password-and-recovery-key.md index c1bb15f..ff23e7d 100644 --- a/docs/desktop/password-and-recovery-key.md +++ b/docs/desktop/password-and-recovery-key.md @@ -132,6 +132,11 @@ Available keychains are: Requires KDE Wallet to be installed and running on your Linux system, with the default wallet present. + There are also third-party plug-ins available for Cryptomator, that allow you to store Cryptomator's vault passwords in third-party 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} From 007db06a41deff708385080825150a11defb3207 Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Tue, 8 Jul 2025 15:16:42 +0200 Subject: [PATCH 4/5] more text adjustments --- docs/desktop/accessing-vaults.md | 2 +- docs/desktop/password-and-recovery-key.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/desktop/accessing-vaults.md b/docs/desktop/accessing-vaults.md index ccf357b..6157708 100644 --- a/docs/desktop/accessing-vaults.md +++ b/docs/desktop/accessing-vaults.md @@ -30,7 +30,7 @@ Anyone with access to these devices will be able to unlock your vault, and in so ::: If your password is correct, a success message will be displayed, and the vault will be unlocked. -You can either close the success window by clicking `Done` or click on `Reveal Vault` to show your unlocked vault in the file manager. +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 diff --git a/docs/desktop/password-and-recovery-key.md b/docs/desktop/password-and-recovery-key.md index ff23e7d..c4f7f2f 100644 --- a/docs/desktop/password-and-recovery-key.md +++ b/docs/desktop/password-and-recovery-key.md @@ -62,14 +62,14 @@ 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 afterwards. +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). +1. 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. @@ -77,8 +77,8 @@ Not all keychains are supported on all platforms. For example, macOS Keychain is 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`. +1. Tick the box `Remember Password` in the unlock dialog. +1. 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. @@ -132,10 +132,10 @@ Available keychains are: Requires KDE Wallet to be installed and running on your Linux system, with the default wallet present. - There are also third-party plug-ins available for Cryptomator, that allow you to store Cryptomator's vault passwords in third-party password managers: + 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 +- [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} From 8b1e00d7f67c387848ad6b9b27403d20d5ae826d Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Tue, 8 Jul 2025 15:30:14 +0200 Subject: [PATCH 5/5] final adjustments --- docs/desktop/accessing-vaults.md | 2 +- docs/desktop/password-and-recovery-key.md | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/desktop/accessing-vaults.md b/docs/desktop/accessing-vaults.md index 6157708..70c5968 100644 --- a/docs/desktop/accessing-vaults.md +++ b/docs/desktop/accessing-vaults.md @@ -26,7 +26,7 @@ For more information, see the [Storing Passwords](/docs/desktop/password-and-rec :::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 password. +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. diff --git a/docs/desktop/password-and-recovery-key.md b/docs/desktop/password-and-recovery-key.md index c4f7f2f..7dd38d5 100644 --- a/docs/desktop/password-and-recovery-key.md +++ b/docs/desktop/password-and-recovery-key.md @@ -63,7 +63,6 @@ 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. @@ -77,7 +76,7 @@ Not all keychains are supported on all platforms. For example, macOS Keychain is To store a password for a vault: 1. Start the unlocking process by selecting the vault and clicking on `Unlock` in the main window. -1. Tick the box `Remember Password` in the unlock dialog. +1. Tick the box `Remember password` in the unlock dialog. 1. 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.