Merge pull request #14791 from nextcloud/fix/recovery-key-documentation-1340

docs: Clarify recovery key documentation for master key vs. per-user key modes

Author: skjnldsv

admin_manual/configuration_files/encryption_configuration.rst

@@ -114,21 +114,24 @@ 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
 --------------------
 
 **Master Key (default):**
 
 - 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.** 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.
 - If a user forgets their password and no recovery key exists, their files are lost.
+- 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:**
 
@@ -308,12 +311,18 @@ User Keys: Sharing & Recovery
 
 **Enabling file recovery keys:**
 
+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.
-- 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.
 
+.. 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
@@ -328,6 +337,22 @@ 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). 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 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 :ref:`Key Management Modes <encryption_configuration_key_management_modes>` for guidance
+on the differences between master key and per-user key modes, and `GitHub Issue #8283
+<https://github.com/nextcloud/server/issues/8283>`_ for technical context on this design decision.
+
 Invalid private key for encryption app
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^