From d2f12ce1afe3be66535b50e9d70e5995276f4326 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 7 May 2026 10:45:52 +0200 Subject: [PATCH 1/3] docs: clarify recovery key documentation for master key vs. per-user key modes Fix issue #1340: recovery key field documentation was confusing since it only applies to per-user key mode, not the default master key mode introduced in Nextcloud 13. Changes: - Update Key Management Modes section to explicitly state recovery key availability - Add reference label for cross-linking - Add caution box in 'Enabling file recovery keys' subsection explaining the limitation - Add troubleshooting entry: 'Why don't I see the recovery key option in Encryption settings?' - Link to server issue #8283 for technical context - Clarify that master key mode is recommended for most deployments Fixes the confusion reported in: - GitHub issue #1340 - Help forum: https://help.nextcloud.com/t/recovery-key-field-missing/50590 - Server issue #8283 Relates to: #1340 Signed-off-by: skjnldsv --- .../encryption_configuration.rst | 40 +++++++++++++++++-- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index 7282aa2c6c3..2e94fa0469a 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -114,6 +114,8 @@ Before You Enable Encryption 2. Back up your instance configuration and all encryption keys in a safe location before proceeding. 3. Decide which key management mode suits your needs (see below). +.. _encryption_configuration_key_management_modes: + Key Management Modes -------------------- @@ -122,13 +124,16 @@ Key Management Modes - All files are encrypted with a central server-controlled key. - Admins can decrypt any user’s files. - Offers better performance and compatibility with more login/authentication modes. -- Best for organizations that need to recover files if users forget their passwords. +- **Recovery keys are not available in master key mode.** If a user forgets their password, admins can reset it and files remain accessible (protected by the master key, not the user password). +- Recommended for most deployments due to improved performance and compatibility. **User Keys:** - Each user’s files are encrypted with a password-protected key. - Admins cannot (readily) decrypt files without the user's password, unless a recovery key is defined. +- **Recovery keys are available in user key mode** as an optional safeguard: if a user forgets their password, admins can use the recovery key to reset access. - If a user forgets their password and no recovery key exists, their files are lost. +- This mode requires more resources and does not work with all authentication methods (e.g., app passwords, single sign-on). **How to choose:** @@ -308,9 +313,16 @@ User Keys: Sharing & Recovery **Enabling file recovery keys:** +.. caution:: + Recovery keys are **only available in per-user key mode**, not in the default master key mode. + If you do not see recovery key options in your Admin Encryption settings, your instance is using + master key mode (the default and recommended mode). To use recovery keys, you must first switch + to per-user key mode by running ``occ encryption:disable-master-key`` on a fresh installation + (before any files are encrypted). + - If you lose your Nextcloud password, you lose access to your encrypted files. -- If a user loses their password, their files are unrecoverable unless a recovery key is enabled. -- To enable recovery, go to Encryption in Admin page and set a recovery key password. +- If a user loses their password, their files are unrecoverable unless a recovery key is enabled (per-user key mode only). +- To enable recovery (in per-user key mode), go to Encryption in Admin page and set a recovery key password. - Users must enable password recovery in their Personal settings for the Recovery Key to work. - For users who have enabled password recovery, admins can reset passwords and recover files using the Recovery Key. @@ -328,6 +340,28 @@ LDAP and External User Backends Troubleshooting --------------- +Why don't I see the recovery key option in the Encryption settings? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Recovery keys are **only available in per-user key mode**. Since Nextcloud 13, the default +encryption mode uses **master keys** (system-wide encryption), which offer better performance +and compatibility. Master key mode does not expose recovery key options in the Admin settings +because recovery keys are not needed—admins can reset user passwords and files remain accessible. + +If you need recovery key functionality, you must switch to per-user key mode before encrypting +any files:: + + occ encryption:disable-master-key + +This command only works on fresh installations without existing encrypted data. + +For most use cases, **master key mode is recommended**. Recovery keys add complexity and are only +needed in edge cases where per-user key encryption is required. See :ref:`Key Management Modes +` for guidance on choosing the right mode. + +See also `GitHub Issue #8283 `_ for technical +context on this design decision. + Invalid private key for encryption app ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 048dab76259c8229a4f1c990f9d80df6e5256368 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Thu, 7 May 2026 14:18:02 +0200 Subject: [PATCH 2/3] docs: address review feedback on recovery key documentation Implement suggestions from @artonge and @schiessle to reduce verbosity and avoid encouraging unnecessary migration to per-user key mode: Changes: - Remove vague 'performance and compatibility' claims from master key section - Simplify recovery key descriptions to avoid encouraging adoption - Delete duplicate caution box before recovery keys section - Remove instructions on switching to per-user key mode - Reframe per-user keys as compatibility option for legacy/older setups - Add warning about recovery process being slow and resource-intensive - Clarify that master key mode is the default and recommended approach Key changes respond to review feedback: - Avoid 'generating a need' for recovery keys when they're not needed in default mode - Position per-user keys as historical compatibility option, not new choice - Reduce overall verbosity while keeping core clarification of issue #1340 Addresses review comments on PR #14791 Signed-off-by: skjnldsv --- .../encryption_configuration.rst | 45 ++++++++----------- 1 file changed, 18 insertions(+), 27 deletions(-) diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index 2e94fa0469a..0053612c431 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -123,17 +123,15 @@ Key Management Modes - All files are encrypted with a central server-controlled key. - Admins can decrypt any user’s files. -- Offers better performance and compatibility with more login/authentication modes. -- **Recovery keys are not available in master key mode.** If a user forgets their password, admins can reset it and files remain accessible (protected by the master key, not the user password). -- Recommended for most deployments due to improved performance and compatibility. +- **Recovery keys are not available in master key mode.** Files remain accessible if a user forgets their password, as they are encrypted by the master key, not the user password. +- Recommended for most deployments. **User Keys:** - Each user’s files are encrypted with a password-protected key. - Admins cannot (readily) decrypt files without the user's password, unless a recovery key is defined. -- **Recovery keys are available in user key mode** as an optional safeguard: if a user forgets their password, admins can use the recovery key to reset access. - If a user forgets their password and no recovery key exists, their files are lost. -- This mode requires more resources and does not work with all authentication methods (e.g., app passwords, single sign-on). +- This mode does not work with all authentication methods (e.g., app passwords, single sign-on) and is only recommended for compatibility with older setups. **How to choose:** @@ -313,12 +311,7 @@ User Keys: Sharing & Recovery **Enabling file recovery keys:** -.. caution:: - Recovery keys are **only available in per-user key mode**, not in the default master key mode. - If you do not see recovery key options in your Admin Encryption settings, your instance is using - master key mode (the default and recommended mode). To use recovery keys, you must first switch - to per-user key mode by running ``occ encryption:disable-master-key`` on a fresh installation - (before any files are encrypted). +Recovery keys are only available in per-user key mode (not the default master key mode). - If you lose your Nextcloud password, you lose access to your encrypted files. - If a user loses their password, their files are unrecoverable unless a recovery key is enabled (per-user key mode only). @@ -326,6 +319,10 @@ User Keys: Sharing & Recovery - Users must enable password recovery in their Personal settings for the Recovery Key to work. - For users who have enabled password recovery, admins can reset passwords and recover files using the Recovery Key. +.. warning:: + The recovery process can be slow and resource-intensive, especially for instances with large amounts of encrypted data. + Test recovery procedures before relying on them in production. + .. figure:: images/encryption10.png .. figure:: images/encryption7.png .. figure:: images/encryption8.png @@ -343,24 +340,18 @@ Troubleshooting Why don't I see the recovery key option in the Encryption settings? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Recovery keys are **only available in per-user key mode**. Since Nextcloud 13, the default -encryption mode uses **master keys** (system-wide encryption), which offer better performance -and compatibility. Master key mode does not expose recovery key options in the Admin settings -because recovery keys are not needed—admins can reset user passwords and files remain accessible. - -If you need recovery key functionality, you must switch to per-user key mode before encrypting -any files:: - - occ encryption:disable-master-key - -This command only works on fresh installations without existing encrypted data. +Recovery keys are only available in per-user key mode. Since Nextcloud 13, the default +encryption mode uses master keys (system-wide encryption). Master key mode does not expose +recovery key options in the Admin settings because recovery keys are not needed—admins can +reset user passwords and files remain accessible. -For most use cases, **master key mode is recommended**. Recovery keys add complexity and are only -needed in edge cases where per-user key encryption is required. See :ref:`Key Management Modes -` for guidance on choosing the right mode. +If you are using master key mode (the default and recommended mode), you do not need recovery +keys. Recovery keys are only relevant for per-user key setups, which are maintained for +compatibility with older deployments. -See also `GitHub Issue #8283 `_ for technical -context on this design decision. +See :ref:`Key Management Modes ` for guidance +on the differences between master key and per-user key modes, and `GitHub Issue #8283 +`_ for technical context on this design decision. Invalid private key for encryption app ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 706f924a2de057fede140cdfa1312bbf4d96acdb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?John=20Molakvo=C3=A6?= Date: Thu, 7 May 2026 16:08:28 +0200 Subject: [PATCH 3/3] fix(admin): underline too short MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: John Molakvoæ --- admin_manual/configuration_files/encryption_configuration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index 0053612c431..84f89f7c0c2 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -338,7 +338,7 @@ Troubleshooting --------------- Why don't I see the recovery key option in the Encryption settings? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Recovery keys are only available in per-user key mode. Since Nextcloud 13, the default encryption mode uses master keys (system-wide encryption). Master key mode does not expose