This app provides all the necessary APIs to implement End-to-End encryption on the client side and in the browser.
Found under Personal settings -> Security:
When the E2EE server app has been successfully enabled and the client app awaits initial setup:
Personal -> Security
Administration settings -> Security
Here you can find the API documentation. Also some typical client operations and how to use the API to perform them are documented too.
The end-to-end encryption implemented by the Nextcloud sync and mobile clients, as well as the functionality provided by this app to facilitate it, is based on the approach documented in the RFC repository.
Security relevant actions, like storing or deleting encryption keys, are recorded in the audit log when the admin_audit app is enabled. All recorded actions and their stable operation identifiers are listed in the audit log actions documentation.
- Make sure the Server-Side Encryption app is disabled (or uninstalled)
- Install then enable the End-to-End Encryption app on your server. No configuration is required on the server other than this.
- Trigger the "Setup end-to-end encryption" under settings within your favorite client app (all official clients support E2EE).
- Carefully note your mnemonic (encryption passphrase) generated by your first client. The mnemonic is needed to: recover access to your data (i.e. if your device is lost or you need to reinstall the app) as well as to setup additional clients.
Caution
The mnenomnic is not recoverable by a server administrator. If you lose your mnemonic you will lose access to your encrypted data.
Caution
When the web interface is used for end-to-end encryption then chunked uploads have to be disabled!
Encryption must be actively enabled for folders. This can be done in any of the officially supported client apps (desktop, Android, iOS).
In the desktop client, the option to encrypt can be found in the context menu (right click) of subfolders of a folder synchronization. Please note that it's neither possible to encrypt the root folder of a folder synchronization, nor to encrypt a subfolder with existing content.
- Since all encryption is handled by the clients, it is important that all client versions in-use be kept relatively aligned (in terms of release version/period) to maintain end-to-end compatibility.
- Since most operations are performed by the clients, in most cases potential bugs will need to be addressed in the clients (though sometimes in coordination with development occurring here with the server app).
- Be careful not to configure different mnemonics across your devices. They must all share the same mnemonic (created on the first device you provision E2EE on) or undefined behavior will occur.
- Keep in mind that using end-to-end encryption has trade-offs. Some functions will never be supported because they are inherently incompatible with the threat model of E2EE. In other cases, functionality may not yet be implemented in your favorite client (in this case you're encouraged to visit the Issues of your respective client and upvote the existing enhancement idea and/or submit your own where one does not already exist).
- E2EE files can currently only be read (using the viewer app) and downloaded from the Nextcloud Web UI (client).
- E2EE focuses on protecting your file-based data, but not other application data (e.g. calendars).
The default user agent configuration is reasonable for all current official stable client releases, but sometimes needs to be adjusted when running custom or development client builds.
// config/config.php
...,
// Allow to configure which client are supported (e.g. custom clients)
'end_to_end_encryption.supported-user-agents' => [
'/^Mozilla\/5\.0 \(Android\) Nextcloud\-android\/(?<version>(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)).*$/' => '3.13.0',
'/^Mozilla\/5\.0 \([A-Za-z ]+\) (mirall|csyncoC)\/(?<version>(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)).*$/' => '3.0.0',
'/^Mozilla\/5\.0 \(iOS\) Nextcloud\-iOS\/(?<version>(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)).*$/' => '3.0.5',
]There are various recovery scenarios where it may be useful to access (decrypt) your files independent of your Nextcloud installation. A separate set of tools called the encryption-recovery-tools can be used for this.
Encrypted folders created with older clients may still use the legacy v1 metadata format. Support for v1 metadata will be dropped soon, after which these folders can no longer be accessed. Affected users need to open their encrypted folders with an up-to-date desktop client, which migrates them to the current v2 metadata format.
The app adds a setup check to the administration overview (Administration settings -> Overview) that warns if v1 metadata is still in use and lists the affected accounts.
To get a detailed list of all affected folders use the end_to_end_encryption:list-v1-metadata occ command:
# List all folders with v1 metadata (owner, file ID, path and metadata version)
occ end_to_end_encryption:list-v1-metadata
# Only list the affected accounts
occ end_to_end_encryption:list-v1-metadata --users-only
# Output as JSON (can be combined with --users-only)
occ end_to_end_encryption:list-v1-metadata --jsonEntries with an unknown owner usually belong to metadata of folders that have already been deleted.
Metadata stored in the very old path-based layout is reported with the version legacy.
There are many ways to contribute, of which development is only one! Find out how to get involved, including as a translator, designer, tester, helping others, and much more! 😍
Specific to this app we summarize the basic steps how to get involved below.
This is is built using PHP on the backend side as well as Typescript and Vue.js on the frontend side.
For building the frontend you need to install the currently active Node.js version (see engines in the package.json).
To built the app from a fresh checkout of the repository run:
npm cito install the frontend dependenciesnpm run buildto build the frontend
When developing there are some more commands which might be useful for you:
npm run devto build the frontend in development mode enabling support for the Vue devtools.npm run watchsimilar todevbut rebuilds as soon as there are code changes in the sources.npm run lintto check for linting issues (e.g. code style). Always check this before contributing code.npm run stylelintsimilar aslintbut for the<style>section of our Vue files.npm run testto run our frontend unit tests.
All contributions to this repository are considered to be licensed under the AGPLv3 or any later version.
Nextcloud doesn't require a CLA (Contributor License Agreement). The copyright belongs to all the individual contributors. Therefore we recommend that every contributor adds the following line to the AUTHORS file if they made substantial changes to the code:
- <your name> <your email address>
We can only accept contributions from authors that agree on the Developer Certificate of Origin!
For this please make sure to sign-off your commits if you want to contribute code (git commit -s).
Please read the Code of Conduct. This document offers some guidance to ensure Nextcloud participants can cooperate effectively in a positive and inspiring atmosphere and to explain how together we can strengthen and support each other.
Before Nextcloud 33 each we published one app version per Nextcloud version
and maintained a branch per Nextcloud versions like stable32 for Nextcloud 32.
Since Nextcloud 33 we switched to a versions based branch process,
where we will keep support of multiple Nextcloud versions within a single app version.
So the new naming schema is e.g. stable-2 for the v2.x series of this app.