From d6828a7b7184e13cec7cd8ae442fee0af32d4e8f Mon Sep 17 00:00:00 2001 From: Josh Date: Sun, 5 Oct 2025 13:23:08 -0400 Subject: [PATCH 1/6] refactor(admin): Rewrite Server-Side Encryption chapter Updated the server-side encryption documentation. - Reorganized and streamlined - Improved clarity throughout - Fixed a few outdated comments/notes - Additional reference links - Added context of "encryption" to help reader understand SSE in the context of other encryption solutions (both within Nextcloud and provided by their OS/etc) - Expanded/clarified key management modes and encryption methods a bit Signed-off-by: Josh --- .../encryption_configuration.rst | 546 +++++++++--------- 1 file changed, 259 insertions(+), 287 deletions(-) diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index 92c219cd75f..c26ff08b4d0 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -1,358 +1,330 @@ -==================================== -Server-side encryption configuration -==================================== - -The primary purpose of the Nextcloud server-side encryption is to protect users' -files on remote storage, such as Dropbox and Google Drive, and to do it easily -and seamlessly from within Nextcloud. - -Server-side encryption separates encryption of local and remote storage. -This allows you to encrypt remote storage, such as Dropbox and -Google, without having to also encrypt your home storage on your Nextcloud -server (en- or disable the checkbox "enabling encryption on your home -storage" in the **Server-side encryption** section of your Admin page.) - -.. note:: Nextcloud supports Authenticated Encryption for all - newly encrypted files. See https://hackerone.com/reports/108082 for more - technical information about the impact. - - For maximum security make sure to configure external storage with "Check for - changes: Never". This will let Nextcloud ignore new files not added via Nextcloud, - so a malicious external storage administrator could not add new files to the - storage without your knowledge. Of course, this is not wise if your external - storage is subject to legitimate external changes. - -Nextcloud server-side encryption encrypts files stored on the Nextcloud server, -and files on remote storage that is connected to your Nextcloud server. -Encryption and decryption are performed on the Nextcloud server. All files sent -to remote storage will be encrypted by the Nextcloud server, and upon retrieval, -decrypted before serving them to you and anyone you have shared them with. - -.. note:: Encryption files generate a slight overhead in size by ~1% (35% before Nextcloud 25). - User's quotas are based on the unencrypted file size, and not the encrypted file size. - -When files on external storage are encrypted in Nextcloud, you cannot share them -directly from the external storage services, but only through Nextcloud sharing -because the key to decrypt the data never leaves the Nextcloud server. - -Nextcloud's server-side encryption generates a strong encryption key, which is -unlocked by user's passwords. Your users don't need to track an extra -password, but simply log in as they normally do. It encrypts only the contents -of files, and not filenames and directory structures. - -You should regularly backup all encryption keys to prevent permanent data loss. -The encryption keys are stored in the following directories: - -``data//files_encryption`` - Users' private keys and all other keys necessary to decrypt the users' files -``data/files_encryption`` - private keys and all other keys necessary to decrypt the files stored on a - system wide external storage - -When encryption is enabled, all files are encrypted and decrypted by the -Nextcloud application, and stored encrypted on your remote storage. -This protects your data on externally hosted storage. The Nextcloud -admin and the storage admin will see only encrypted files when browsing backend -storage. - -.. warning:: Encryption keys are stored only on the Nextcloud server, eliminating - exposure of your data to third-party storage providers. The encryption app - does **not** protect your data if your Nextcloud server is compromised, and it - does not prevent Nextcloud administrators from reading user's files. This - would require client-side encryption, which this app does not provide. If - your Nextcloud server is not connected to any external storage services then - it is better to use other encryption tools, such as file-level or - whole-disk encryption. - - Note also that SSL terminates at or before Apache on the Nextcloud server, and - all files will exist in an unencrypted state between the SSL connection - termination and the Nextcloud code that encrypts and decrypts files. This is - also potentially exploitable by anyone with administrator access to your - server. Read `How Nextcloud uses encryption to protect your data - `_ for more information. - -Before enabling encryption --------------------------- - -Plan very carefully before enabling encryption because it is not reversible via -the Nextcloud Web interface. If you lose your encryption keys your files are not -recoverable. Always have backups of your encryption keys stored in a safe -location, and consider enabling all recovery options. - -There are two encryption mode, `master key` and `user keys`. By default, `master key` is used. - -If you do not want to use a master key setup, but wish to use user key encryption -instead, please run the following command before enabling the encryption:: - - occ encryption:disable-master-key - -You have more options via the ``occ`` command (see :ref:`occ_encryption_label`). - -.. _enable_encryption_label: - -Enabling encryption -------------------- - -Nextcloud encryption consists of two parts. The base encryption system is -enabled and disabled on your Admin page. First you must enable this, and then -select an encryption module to load. Currently the only available encryption -module is the Nextcloud Default Encryption Module. - -First go to the **Server-side encryption** section of your Admin page and check -**Enable server-side encryption**. You have one last chance to change your mind. - -.. figure:: images/encryption3.png - -After clicking the **Enable Encryption** button you see the message "No -encryption module loaded, please load a encryption module in the app menu", so -go to your Apps page to enable the Nextcloud Default Encryption Module. - -.. figure:: images/encryption1.png - -Return to your Admin page to see the Nextcloud Default Encryption -Module added to the module selector, and automatically selected. Now you must -log out and then log back in to initialize your encryption keys. - -.. figure:: images/encryption14.png +====================== +Server-side Encryption +====================== + +Overview +-------- + +Nextcloud provides several encryption methods to protect your data. These work at +different layers of the system and address different security needs. This guide +focuses on Nextcloud's built-in Server-Side Encryption (SSE). + +.. note:: + Encryption and risk management is a complex and nuanced topic. Unless you are + already an expert, it is recommended to consult a professional or perform a + deep dive to ensure your approach targets your specific concerns. + You may also find this Nextcloud Blog post helpful: + `Data encryption methods in Nextcloud `_. + It provides a solid high-level overview of the different approaches commonly + considered when using Nextcloud. + +Definitions +----------- + +- **Server-Side Encryption (SSE):** Performed by the Nextcloud server, protecting + files at rest on local and external storage. Encryption keys are stored on the server. +- **End-to-End Encryption (E2EE):** Performed by Nextcloud desktop or mobile clients + before uploading files. Only the client can decrypt, making data inaccessible to + server administrators and external storage providers. +- **Master Key:** A central key controlled by the server, used to encrypt all files. +- **User Keys:** Each user has their own key, protected by their password, to encrypt + their files. +- **Recovery Key:** An admin-defined key to recover files if users lose their passwords. + +Encryption Method Comparison +---------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 20 25 35 + + * - Method + - Encryption Location + - Who Can Decrypt? + - Protects Against + * - SSE (Master Key) + - Server + - Admins & users + - External storage providers + * - SSE (User Keys) + - Server + - Users & malicious admins + - External storage providers + * - SSE (User Keys w/ Recovery) + - Server + - Users & admins with recovery key + - External storage providers + * - E2EE + - Client + - Users only + - Admins, external storage providers + * - Disk/Block Encryption + - Server + - OS admin + - Physical tampering, theft + +Key Points & Limitations +------------------------ + +- Encryption methods are not interchangeable; each is designed for specific risks. +- SSE is mainly for protecting files on external, third-party storage. +- E2EE is for scenarios where server administrators must not access data. +- SSE does **not** encrypt filenames or folder structures, only file contents. +- SSE does not protect data from a compromised Nextcloud server or malicious administrator. + Use E2EE for this threat. +- Server-Side Encryption cannot be reversed via the Nextcloud Web interface. +- Troubleshooting SSE matters generally requires ``occ`` command access. Make sure you have + it before enabling SSE! +- Losing encryption keys or your instance secret results in permanent data loss. +- Nextcloud quotas are based on unencrypted file size; encrypted files may be ~1% larger + (was 35% before Nextcloud 25). +- SSL/TLS (HTTPS) terminates before files are encrypted, so files may be exposed in memory + between SSL/TLS and Nextcloud’s encryption code. +- When files on external storage are encrypted in Nextcloud, you cannot share them directly + from the external storage provider; sharing is only possible via Nextcloud, since the + decryption key never leaves the Nextcloud server. +- For local storage, it may be better to use other encryption tools, such as disk/block device + encryption (e.g., LUKS) provided by your operating system. This protects against other concerns, + such as theft of your physical server, which is not SSE's goal. + +.. note:: + Don't confuse Nextcloud's SSE with S3 SSE-C (also supported). + +.. note:: + Nextcloud (since v9.0.0) supports Authenticated Encryption for all newly encrypted files. + See https://hackerone.com/reports/108082 for technical details. + +.. note:: + For maximum security, configure external storage with "Check for changes: Never". + This causes Nextcloud to ignore new files not added via Nextcloud, preventing unauthorized + additions by external storage admins. Do not use this if your storage is subject to legitimate + external changes. + +Before You Enable Encryption +---------------------------- + +1. Read this guide fully and understand the risks. +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). + +Key Management Modes +-------------------- -When you log back in, there is a checkbox for enabling encryption on your home -storage. This is checked by default. Un-check to avoid encrypting your home -storage. +**Master Key (default):** -.. figure:: images/encryption15.png +- 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. -Encrypting external mountpoints -------------------------------- +**User Keys:** -You and your users can encrypt individual external mountpoints. You must have -external storage enabled on your Admin page, and enabled for your users. +- 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. -Encryption settings can be configured in the mount options for an external -storage mount, see :ref:`external_storage_mount_options_label` -(:doc:`external_storage_configuration_gui`) +**How to choose:** +- If you trust your server administrators, use master key mode. +- If you need to prevent admins from accessing files, use E2EE. +- User key mode offers some protection against malicious server administrators, but has limitations. -Encrypting team folders ------------------------ +**To select user key mode:** -By default team folder are not encrypted. If you want to encrypt your team folders -as well you need to run following occ command: +Run: - occ config:app:set groupfolders enable_encryption --value=true +.. code-block:: bash -Like for all other files and server-side-encryption in general, this will not encrypt -already existing files in team folders but only new or updated files after -the occ command was executed. + occ encryption:disable-master-key -.. _occ_encryption_label: +before enabling encryption. -occ encryption commands ------------------------ -If you have shell access you may use the ``occ`` command to perform encryption -operations, and you have additional options such as decryption and creating a -single master encryption key. See :ref:`encryption_label` for detailed -instructions on using ``occ``. +Enabling Encryption (Step-by-Step) +---------------------------------- -Get the current status of encryption and the loaded encryption module:: +1. Go to the **Server-side encryption** section of your Admin page. +2. Check **Enable server-side encryption**. +3. You’ll see a message: "No encryption module loaded." + Go to your Apps page and enable the Nextcloud Default Encryption Module. +4. Return to your Admin page. The module will appear and be auto-selected. +5. Log out and log back in to initialize your encryption keys. +6. Optional: Un-check the box for encrypting home storage if you wish to keep local files unencrypted. - occ encryption:status - - enabled: false - - defaultModule: OC_DEFAULT_MODULE +.. figure:: images/encryption3.png -This is equivalent to checking **Enable server-side encryption** on your Admin -page:: +.. figure:: images/encryption14.png - occ encryption:enable - Encryption enabled +.. figure:: images/encryption15.png - Default module: OC_DEFAULT_MODULE +Backups +------- -List the available encryption modules:: +Encryption keys are stored in: - occ encryption:list-modules - - OC_DEFAULT_MODULE: Default encryption module [default*] +- ``data//files_encryption`` (per-user keys) +- ``data/files_encryption`` (system-wide/external storage keys) -Select a different default Encryption module (currently the only available -module is OC_DEFAULT_MODULE):: +Encrypting External Mountpoints and Team Folders +------------------------------------------------ - occ encryption:set-default-module [Module ID]. +- You and your users can encrypt external mountpoints. -The [module ID] is taken from the ``encryption:list-modules`` command. + - Set encryption options in the mount configuration for each external storage. + - See :ref:`external_storage_mount_options_label` in :doc:`external_storage_configuration_gui`. -Encrypt all data files for all users. For performance reasons, when you enable -encryption on a Nextcloud server only new and changed files are encrypted. This -command gives you the option to encrypt all files. +- To encrypt Team Folders, run: -Run ``occ``:: +.. code-block:: bash - occ encryption:encrypt-all + occ config:app:set groupfolders enable_encryption --value=true - You are about to start to encrypt all files stored in your Nextcloud. - It will depend on the encryption module you use which files get encrypted. - Depending on the number and size of your files this can take some time. - Please make sure that no users access their files during this process! +.. note:: + Only new or updated files in team folders will be encrypted. - Do you really want to continue? (y/n) +Managing Encryption via occ Commands +------------------------------------ -When you type ``y`` it creates a key pair for each of your users, and then -encrypts their files, displaying progress until all user files are encrypted. +Here is a reference table for common occ commands: -Decrypt all user data files, or optionally a single user:: +.. list-table:: + :header-rows: 1 + :widths: 35 65 - occ encryption:decrypt-all [username] + * - Command + - Description + * - occ encryption:status + - Show encryption status and module + * - occ encryption:enable + - Enable server-side encryption + * - occ encryption:list-modules + - List available encryption modules + * - occ encryption:set-default-module [Module ID] + - Select default encryption module + * - occ encryption:encrypt-all + - Encrypt all files for all users + * - occ encryption:decrypt-all [user] + - Decrypt all files (or for one user) + * - occ encryption:show-key-storage-root + - Show key storage location + * - occ encryption:change-key-storage-root [dir] + - Move key storage directory + * - occ encryption:enable-master-key + - Enable master key mode + * - occ encryption:disable-master-key + - Enable user key mode + * - occ encryption:fix-encrypted-version + - Fix bad signature errors + * - occ encryption:fix-key-location [user] + - Fix key not found errors -View current location of keys:: +**Example: Move keys to a new directory (Ubuntu Linux):** - occ encryption:show-key-storage-root - Current key storage root: default storage location (data/) +.. code-block:: bash -Move keys to a different folder, either locally or on a different server. -The folder must already exist, be owned by root and your HTTP group, and be -restricted to root and your HTTP group. Further the folder needs to be located -somewhere in your Nextcloud data folder, either physically, or as a mount. -This example is for Ubuntu Linux. Note that the new folder is relative to your ``occ`` directory:: + cd /your/nextcloud/data + mkdir keys + chown -R root:www-data keys + chmod -R 0770 keys + occ encryption:change-key-storage-root keys - cd /your/nextcloud/data - mkdir keys - chown -R root:www-data keys - chmod -R 0770 keys - occ encryption:change-key-storage-root keys - Start to move keys: - 4 [============================] - Key storage root successfully changed to keys +Encrypting All Files +-------------------- -Create a new master key. Use this when you have a single-sign on -infrastructure. Use this only on fresh installations with no existing data, or -on systems where encryption has not already been enabled. It is not possible to -disable it:: +By default, only new and changed files are encrypted when you enable SSE. +To encrypt all files for all users run: - occ encryption:enable-master-key +.. code-block:: bash -Fix Bad signature errors:: + occ encryption:encrypt-all - occ encryption:fix-encrypted-version --all - occ encryption:fix-encrypted-version - occ encryption:fix-encrypted-version -p +- **Make sure you have backups before running.** +- The command creates a key pair for each user and encrypts their files. +- Progress is displayed until all files are encrypted. +- **Make sure no users access files during this process.** -Fix key not found errors:: +Decrypting Files / Disabling Encryption +--------------------------------------- - occ encryption:fix-key-location +- Only possible via occ. +- First, decrypt all files: -.. _occ_disable_encryption_label: +.. code-block:: bash -Disabling encryption --------------------- + occ encryption:decrypt-all -You may disable encryption only with ``occ``. Make sure you have backups of all -encryption keys, including users'. -Disable your encryption module with this command:: +- **Make sure you have backups before running.** +- Server enters maintenance mode. If interrupted, rerun until complete. +- If some files remain encrypted, rerun the command after resolving issues. +- **Warning:** Disabling encryption without decrypting all files will cause unpredictable errors. - occ encryption:decrypt-all +You can decrypt for individual users: -It will put your server into maintenance mode and back. -It also takes care of disabling encryption when all files have been decrypted. -If the command is aborted some files have been decrypted and others are still encrypted. -In this case the command will keep the encryption turned on -and Nextcloud can handle this situation fine. -You can proceed decrypting the remaining files by calling the command again -once the problems that caused the abortion have been resolved. +.. code-block:: bash -.. warning:: Disabling encryption without decrypting all the files will lead to decryption errors in the future as this state causes unpredictable behaviors. -.. note:: The ``occ encryption:decrypt-all`` can take a lot of time. You can run one user at a time like so: ``occ encryption:decrypt-all ``. + occ encryption:decrypt-all -Files not encrypted +Data Not Encrypted ------------------- -Only the data in the files in ``data/user/files`` are encrypted, and not the -filenames or folder structures. These files are never encrypted: - -- Existing files in the trash bin & Versions. Only new and changed files after - encryption is enabled are encrypted. -- Existing files in Versions -- Image thumbnails from the Gallery app -- Previews from the Files app -- The search index from the full text search app -- Third-party app data - -There may be other files that are not encrypted; only files that are exposed to -third-party storage providers are guaranteed to be encrypted. +Only file contents is encrypted. The following are **not** encrypted: +.. list-table:: + :header-rows: 1 -Using user keys ---------------- - -If you disabled master key and are using user keys instead, mind the following information: + * - Not Encrypted + * - Filenames and folder structures + * - Existing trash bin files + * - Existing historical file versions + * - Image thumbnails + * - Image previews + * - Full text search index + * - Application data that isn't file-based (e.g., Deck, Tables) -Sharing encrypted files -^^^^^^^^^^^^^^^^^^^^^^^ +User Keys: Sharing & Recovery +----------------------------- -After encryption is enabled your users must also log out and log back in to -generate their personal encryption keys. They will see a yellow warning banner -that says "Encryption App is enabled but your keys are not initialized, please -log-out and log-in again." +**Sharing encrypted files:** -Share owners may need to re-share files after encryption is enabled; users -trying to access the share will see a message advising them to ask the share -owner to re-share the file with them. For individual shares, un-share and -re-share the file. For group shares, share with any individuals who can't access -the share. This updates the encryption, and then the share owner can remove the -individual shares. +- After enabling user key mode, users must log out and log in to generate keys. +- Users who see "Encryption App is enabled but your keys are not initialized..." must log out and back in. +- Shared files may need to be re-shared after encryption is enabled. + - For individual shares: un-share and re-share the file. + - For group shares: share with any individuals who cannot access the share, then remove their individual shares. .. figure:: images/encryption9.png -.. _enable-file-recovery-key: +**Enabling file recovery keys:** -Enabling users file recovery keys -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you lose your Nextcloud password, then you lose access to your encrypted -files. If one of your users loses their Nextcloud password their files are -unrecoverable. You cannot reset their password in the normal way; you'll see a -yellow banner warning "Please provide an admin recovery password, otherwise all -user data will be lost". - -To avoid all this, create a Recovery Key. Go to the Encryption section of your -Admin page and set a recovery key password. +- 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. +- 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. .. figure:: images/encryption10.png - -Then your users have the option of enabling password recovery on their Personal -pages. If they do not do this, then the Recovery Key won't work for them. - .. figure:: images/encryption7.png - -For users who have enabled password recovery, give them a new password and -recover access to their encrypted files by supplying the Recovery Key on the -Users page. - .. figure:: images/encryption8.png - -You may change your Recovery Key password. - .. figure:: images/encryption12.png -Please check the various key types in detail `here `_ - -LDAP and other external user back-ends -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +LDAP and External User Backends +------------------------------- -If you use an external user back-end, such as an LDAP or Samba server, and you -change a user's password on the back-end, the user will be prompted to change -their Nextcloud login to match on their next Nextcloud login. The user will need -both their old and new passwords to do this. If you have enabled the Recovery -Key then you can change a user's password in the Nextcloud Users panel to match -their back-end password, and then, of course, notify the user and give them -their new password. +- If using LDAP/Samba and changing passwords on the backend, users will need both their old and new passwords on next login. +- If recovery key is enabled, admins can reset the password via Nextcloud and notify users. Troubleshooting --------------- -Invalid private key for encryption app -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- **Invalid private key for encryption app:** + See `GitHub Issue #8546 `_ and + `workaround `_. + +Further Reading +--------------- -This `issue `_ is being worked -on. In the meantime there is a -`workaround `_ -which unfortunately is only suitable for administrators comfortable with the -command line. +- `How Nextcloud uses encryption to protect your data `_ +- `Technical impact of Authenticated Encryption `_ +- `Nextcloud SSE Implementation Details `_ +- `Nextcloud Encryption (SSE & E2EE) Recovery Tools `_ +- `Nextcloud E2EE Server API App (required for E2EE usage) `_ From c70973951a5915322e047682390aa7aff4a3d8fb Mon Sep 17 00:00:00 2001 From: Josh Date: Sun, 5 Oct 2025 13:34:05 -0400 Subject: [PATCH 2/6] chore: add back referenced label Signed-off-by: Josh --- admin_manual/configuration_files/encryption_configuration.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index c26ff08b4d0..3d9df21b656 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -243,6 +243,8 @@ To encrypt all files for all users run: - Progress is displayed until all files are encrypted. - **Make sure no users access files during this process.** +.. _occ_disable_encryption_label: + Decrypting Files / Disabling Encryption --------------------------------------- From f17e3ddf0659cef80b457f65f668c6a17acc78d8 Mon Sep 17 00:00:00 2001 From: Josh Date: Thu, 9 Oct 2025 08:24:38 -0400 Subject: [PATCH 3/6] fix: additional clarification within Limitations section Signed-off-by: Josh --- .../encryption_configuration.rst | 27 ++++++++++++------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index 3d9df21b656..4b9b577c54f 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -30,6 +30,10 @@ Definitions - **User Keys:** Each user has their own key, protected by their password, to encrypt their files. - **Recovery Key:** An admin-defined key to recover files if users lose their passwords. +- **Disk/Block Device Encryption:** A method of securing all data stored on a physical + storage device by encrypting it at the hardware or filesystem level - typically using + tools such as LUKS on Linux - so that data is only accessible after the device is + unlocked with the correct key or password. Encryption Method Comparison ---------------------------- @@ -67,34 +71,37 @@ Key Points & Limitations ------------------------ - Encryption methods are not interchangeable; each is designed for specific risks. -- SSE is mainly for protecting files on external, third-party storage. -- E2EE is for scenarios where server administrators must not access data. +- **Server-Side Encryption (SSE)** is mainly for protecting files on external, third-party storage. +- **End-to-End Encryption (E2EE)** is for scenarios where server administrators must not access data. - SSE does **not** encrypt filenames or folder structures, only file contents. - SSE does not protect data from a compromised Nextcloud server or malicious administrator. Use E2EE for this threat. -- Server-Side Encryption cannot be reversed via the Nextcloud Web interface. -- Troubleshooting SSE matters generally requires ``occ`` command access. Make sure you have - it before enabling SSE! +- SSE cannot be reversed via the Nextcloud Web interface. +- Troubleshooting SSE generally requires ``occ`` command access. Make sure you have + this before enabling SSE! - Losing encryption keys or your instance secret results in permanent data loss. -- Nextcloud quotas are based on unencrypted file size; encrypted files may be ~1% larger +- Nextcloud quotas are based on unencrypted file size; files encrypted with SSE may be ~1% larger (was 35% before Nextcloud 25). - SSL/TLS (HTTPS) terminates before files are encrypted, so files may be exposed in memory - between SSL/TLS and Nextcloud’s encryption code. -- When files on external storage are encrypted in Nextcloud, you cannot share them directly + between SSL/TLS and Nextcloud’s SSE encryption code. +- When files on external storage are encrypted with SSE, you cannot share them directly from the external storage provider; sharing is only possible via Nextcloud, since the decryption key never leaves the Nextcloud server. - For local storage, it may be better to use other encryption tools, such as disk/block device encryption (e.g., LUKS) provided by your operating system. This protects against other concerns, such as theft of your physical server, which is not SSE's goal. +.. warning:: + SSE does **not** encrypt filenames or folder structures, only file contents. + .. note:: Don't confuse Nextcloud's SSE with S3 SSE-C (also supported). -.. note:: +.. versionchanged:: 9.0.0 Nextcloud (since v9.0.0) supports Authenticated Encryption for all newly encrypted files. See https://hackerone.com/reports/108082 for technical details. -.. note:: +.. tip:: For maximum security, configure external storage with "Check for changes: Never". This causes Nextcloud to ignore new files not added via Nextcloud, preventing unauthorized additions by external storage admins. Do not use this if your storage is subject to legitimate From 99c7075bf621eca0fcb0290514842f4aaebee682 Mon Sep 17 00:00:00 2001 From: Josh Date: Thu, 9 Oct 2025 08:58:22 -0400 Subject: [PATCH 4/6] docs(encryption): Add links to `occ encryption` in cmd ref guide Added a tip for further encryption command examples and details. Signed-off-by: Josh --- admin_manual/configuration_files/encryption_configuration.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index 4b9b577c54f..c356e67a31e 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -225,6 +225,9 @@ Here is a reference table for common occ commands: * - occ encryption:fix-key-location [user] - Fix key not found errors +.. tip:: + See the :ref:`encryption_label` section of the ``occ`` reference guide for further ``encryption`` command examples and details. + **Example: Move keys to a new directory (Ubuntu Linux):** .. code-block:: bash @@ -332,6 +335,7 @@ Troubleshooting Further Reading --------------- +- :ref:`occ Command Reference: Encryption ` - `How Nextcloud uses encryption to protect your data `_ - `Technical impact of Authenticated Encryption `_ - `Nextcloud SSE Implementation Details `_ From 17b8cf121a66b2373e6fdd1ec10f9e1e4a17e3d5 Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 10 Oct 2025 13:20:08 -0400 Subject: [PATCH 5/6] refactor: Integrate encryption troubleshooting sections Moved them all to the Encryption chapter rather than having them split between there and the general troubleshooting chapter. And cleaned up some grammar and typos. Signed-off-by: Josh --- .../encryption_configuration.rst | 59 +++++++++++++++++-- 1 file changed, 55 insertions(+), 4 deletions(-) diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index c356e67a31e..0ca99e78751 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -279,7 +279,7 @@ You can decrypt for individual users: Data Not Encrypted ------------------- -Only file contents is encrypted. The following are **not** encrypted: +Only file contents are encrypted. The following are **not** encrypted: .. list-table:: :header-rows: 1 @@ -328,9 +328,60 @@ LDAP and External User Backends Troubleshooting --------------- -- **Invalid private key for encryption app:** - See `GitHub Issue #8546 `_ and - `workaround `_. +Invalid private key for encryption app +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +See `GitHub Issue #8546 `_ and +`workaround `_. + +Bad signature error +^^^^^^^^^^^^^^^^^^^ + +In some rare cases, encrypted files cannot be downloaded and return a "500 Internal Server Error." If the Nextcloud log contains an error about "Bad Signature," run the following command to repair affected files:: + + occ encryption:fix-encrypted-version userId --path=/path/to/broken/file.txt + +Replace "userId" and the path accordingly. +The command will perform a test decryption for all files and automatically repair those with a signature error. + +.. _troubleshooting_encryption_key_not_found: + +Encryption key cannot be found +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the logs contain an error stating that the encryption key cannot be found, you can manually search the data directory for a folder that has the same name as the file name. +For example, if a file "example.md" cannot be decrypted, run:: + + find path/to/datadir -name example.md -type d + +Then check the results located in the ``files_encryption`` folder. +If the key folder is in the wrong location, move it to the correct folder and try again. + +The ``data/files_encryption`` folder contains encryption keys for group folders and system-wide external storages, +while ``data/$userid/files_encryption`` contains the keys for specific user storage files. + +.. note:: + + This can happen if encryption was disabled at some point but the :ref:`occ command for decrypt-all` was not run. + If someone then moved the files to another location, the keys did not get moved. + +Encryption key cannot be found with external storage or group folders +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To resolve this issue, run the following command:: + + sudo -E -u www-data php occ encryption:fix-key-location + +This will attempt to recover keys that were not moved properly. + +If this doesn't resolve the problem, refer to the section :ref:`Encryption key cannot be found` for a manual procedure. + +.. note:: + + There were two known issues where: + + - moving files between an encrypted and non-encrypted storage like external storage or group folder `would not move the keys with the files `_. + - putting files on system-wide external storage would store the keys in the `wrong location `_. Further Reading --------------- From 9a30dfbeb81db4ab572ce61ee01470f2f0f43ea0 Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 10 Oct 2025 13:29:26 -0400 Subject: [PATCH 6/6] reactor: consolidate encryption troubleshooting into enc. chapter Signed-off-by: Josh --- .../issues/general_troubleshooting.rst | 56 ++----------------- 1 file changed, 4 insertions(+), 52 deletions(-) diff --git a/admin_manual/issues/general_troubleshooting.rst b/admin_manual/issues/general_troubleshooting.rst index afd8e48c4c3..688d76e7c6a 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -448,59 +448,11 @@ You can run the following SQL query to reset those after **backing up the databa UPDATE oc_filecache SET unencrypted_size=0 WHERE encrypted=0; -Troubleshooting downloading or decrypting files ------------------------------------------------ +Troubleshooting encrypted files +------------------------------- -Bad signature error -^^^^^^^^^^^^^^^^^^^ - -In some rare cases it can happen that encrypted files cannot be downloaded -and return a "500 Internal Server Error". If the Nextcloud log contains an error about -"Bad Signature", then the following command can be used to repair affected files:: - - occ encryption:fix-encrypted-version userId --path=/path/to/broken/file.txt - -Replace "userId" and the path accordingly. -The command will do a test decryption for all files and automatically repair the ones with a signature error. - -.. _troubleshooting_encryption_key_not_found: - -Encryption key cannot be found -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If the logs contain an error stating that the encryption key cannot be found, you can manually search the data directory for a folder that has the same name as the file name. -For example if a file "example.md" cannot be decrypted, run:: - - find path/to/datadir -name example.md -type d - -Then check the results located in the ``files_encryption`` folder. -If the key folder is in the wrong location, you can move it to the correct folder and try again. - -The ``data/files_encryption`` folder contains encryption keys for group folders and system-wide external storages -while ``data/$userid/files_encryption`` contains the keys for specific user storage files. - -.. note:: - - This can happen if encryption was disabled at some point but the :ref:`occ command for decrypt-all` was not run, and - then someone moved the files to another location. Since encryption was disabled, the keys did not get moved. - -Encryption key cannot be found with external storage or group folders -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To resolve this issue, please run the following command:: - - sudo -E -u www-data php occ encryption:fix-key-location - -This will attempt to recover keys that were not moved properly. - -If this doesn't resolve the problem, please refer to the section :ref:`Encryption key cannot be found` for a manual procedure. - -.. note:: - - There were two known issues where: - - - moving files between an encrypted and non-encrypted storage like external storage or group folder `would not move the keys with the files `_. - - putting files on system-wide external storage would store the keys in the `wrong location `_. +.. tip:: + Please also refer to the troubleshooting section in the encryption chapter: :doc:`../configuration_files/encryption_configuration`. Fair Use Policy ---------------