diff --git a/mkdocs.yml b/mkdocs.yml index 80d31e28..4b097e4d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -84,7 +84,6 @@ nav: - Block personal user creation: understand/block-user-creation.md - Classified Domains: understand/classified-domains.md - Federation: understand/configure-federation.md - - Installing and setting up Legal Hold: understand/legalhold.md - Messaging Layer Security (MLS): understand/mls.md - User Searchability: understand/searchability.md - Server and team feature settings: understand/team-feature-settings.md @@ -121,7 +120,6 @@ nav: - SCIM tokens: developer/reference/provisioning/scim-token.md - RabbitMQ Consumer: developer/reference/rabbitmq-consumer.md - Spar braindump: developer/reference/spar-braindump.md - - Legal hold: developer/reference/team/legalhold.md - User Activation: developer/reference/user/activation.md - Connection: developer/reference/user/connection.md - User Registration: developer/reference/user/registration.md diff --git a/src/developer/README.md b/src/developer/README.md index 2c705085..1eea82cf 100644 --- a/src/developer/README.md +++ b/src/developer/README.md @@ -41,7 +41,6 @@ help you. - [SCIM tokens](reference/provisioning/scim-token.md) - [RabbitMQ Consumer](reference/rabbitmq-consumer.md) - [Spar braindump](reference/spar-braindump.md) - - [Legal hold](reference/team/legalhold.md) - [User Activation](reference/user/activation.md) - [Connection](reference/user/connection.md) - [Connection backend internals](reference/user/connection.md#connection-backend-internals) diff --git a/src/developer/developer/features.md b/src/developer/developer/features.md index 32c3672e..60e8e597 100644 --- a/src/developer/developer/features.md +++ b/src/developer/developer/features.md @@ -2,7 +2,7 @@ Wire has multiple features (or feature flags) that affect the behaviour of backend and clients, e.g. `sso`, `searchVisibility`, `digitalSignatures`, -`appLock`, `legalhold`, `fileSharing`. +`appLock`, `fileSharing`. Features cannot by configured by the users themselves, which distinguishes features from user properties. Who can configure a feature depends on the diff --git a/src/developer/reference/README.md b/src/developer/reference/README.md index e70812a0..52290bf6 100644 --- a/src/developer/reference/README.md +++ b/src/developer/reference/README.md @@ -10,7 +10,6 @@ - [SCIM tokens](provisioning/scim-token.md) - [RabbitMQ Consumer](rabbitmq-consumer.md) - [Spar braindump](spar-braindump.md) - - [Legal hold](team/legalhold.md) - [User Activation](user/activation.md) - [Connection](user/connection.md) - [Connection backend internals](user/connection.md#connection-backend-internals) diff --git a/src/developer/reference/team/legalhold.md b/src/developer/reference/team/legalhold.md deleted file mode 100644 index 44dfec3e..00000000 --- a/src/developer/reference/team/legalhold.md +++ /dev/null @@ -1,187 +0,0 @@ -# Legal hold - -*Author: Tiago Loureiro* - ---- - -Legal hold introduces a new type of device, named *legal hold device*, for the sake of satisfying corporate compliance rules without sacrificing end to end encryption with full transparency. - -A *legal hold device* is a device bound to a team user account but managed outside of the user’s control - this is managed by the Legal hold service. The management/operation of said Legal hold service is of the responsibility of the team. - -This Backend service makes this type of device available for clients that are visually distinguishable, for full transparency, with a clear, constant indication on the UI. There can be only one such device per user account and they can only be added to the user’s device list with the user’s consent and confirmed with a password prompt (if they have one - there can be exceptions such as SSO users). - -A team admin may ask members of the team to be put under [legal hold](https://en.wikipedia.org/wiki/Legal_hold). Once a person is prompted, they should then verify that the presented signature matches the one generated by the legalhold service to avoid any potential [MITM attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). - -Conceptually, there are the following actors in this use case: - -* A team admin - someone who requests legal hold for a specific user -* A team member - the user who will be put under legal hold -* Backend - serves as intermediary between team members/admin and the Legal hold Service -* Legal hold service - stores users’ Legal hold devices on customers’ premises -* Legal hold device - a user’s device that is managed by customers - -Once a user accepts the legal hold request, then a device is added to that user’s account. This device, also known as legal hold device, is managed by the Legal hold service - only team admins can remove that device from a user’s account. - -Note that every user talking to someone under legal hold (including, of course, the *self* user) is made aware by means of displaying a red dot on the user’s profile. - -## API and flows - -Legal hold flow (client perspective) - -Request (by admin) for a user to be put under legalhold - -```default -POST /teams/{tid}/legalhold/{uid} -``` - -```default -201 Created -``` - -Approval by the user - -```default -PUT /teams/{tid}/legalhold/{uid}/approve -{ - "password": # optional if the user has no set password -} -``` - -```default -200 OK -``` - -Deletion by an admin - -```default -DELETE /teams/{tid}/legalhold/{uid} -{ - "password": # optional if the admin has no set password -} -``` - -```default -200 OK -``` - -Get Legal hold status for team members - -```default -GET /team/{tid}/members -``` - -```default -200 OK -... -{ - "members": [{ - "user": member used id, - ... - "legalhold_status": "disabled" | "enabled", <-- new field - ... - } -} -``` - -![LHFlow](https://user-images.githubusercontent.com/1105323/61390098-6bf34800-a8ba-11e9-8ba7-e0759b22a773.png) - -
-title: Legal Hold Flow (client perspective) -=: Activation - -Admin Panel -> Backend: Activate LH for Alice - -Backend -> LegalHold Service: Request to create Cryptobox for Alice (does NOT include scoped token) - -LegalHold Service –> Backend: Respond with Public Key etc. for Device - -Backend -> Admin Panel: LH for Alice is PENDING -Backend –> Alice’s Client: (Async) Request Approval for LH (includes device fingerprint) - -Alice’s Client -> Backend: Alice APPROVES LH - -Backend -> LegalHold Service: Send scoped access_token -Backend -> Backend: Add Compliance Device to Alice -Backend -> Admin Panel: LH for Alice is ACTIVE - -=: Deactivation - -Admin Panel -> Backend: Deactivate LH for Alice -Backend -> Backend: Remove Compliance Device from Alice; revoke access token. - -
- -## Events - -New legalhold request event: - -```default -{ "type": "user.legalhold-request" -, "id": UserID of the one for whom LH is being requested -, "last_prekey": Last-prekey of the legal hold device -, "client": {"id": Client ID of the legalhold device} -} -``` - -New legalhold enabled event: - -```default -{ "type": "user.legalhold-enable" -, "id": UserID for whom LH was enabled -} -``` - -New legalhold disabled event: - -```default -{ "type": "user.legalhold-disable" -, "id": UserID for whom LH was disabled -} -``` - -These events are sent to the user, all team members (including admins) and connections. - -## Whitelisting and implicit consent - -This release introduces a notion of intial “consent” to legalhold -(LH): In addition to the popup before getting exposed to LH devices -(either by getting assigned one or by entering a conversation or -connection with one present), users needs to grant their consent to -even have the option of being exposed. Until they do, they may be -blocked from using wire by their team admin (if they are a team user), -but they cannot be assigned a LH device, and they cannot enter -conversations with LH devices present. - -For now, there isn’t any UI for the user to grant their initial consent. -Instead, an “implict consent” can be given by the site operator by setting - -```yaml - featureFlags: - # [...] - legalhold: whitelist-teams-and-implicit-consent -``` - -in galley’s config and then using non-exposed, internal endpoints on the galley -pod to update the set of teams whose users are considered to have given their -initial consent: - -- `put /i/legalhold/whitelisted-teams/:team-id` - Add team -- `delete /i/legalhold/whitelisted-teams/:team-id` - Remove team -- `get /i/legalhold/whitelisted-teams` - List all teams - -Since consent is required for LH to work, users in teams that are not -whitelisted cannot be assigned LH devices (pull request #1502), and -they are blocked or removed from conversations that are exposed to LH -devices (#1507, #1595). - -### Implementation status and future work - -The notion of consent is introduced to make it explicit, ie. users -would have UI components to grant consent themselves, and there would -be clear feedback in situations where communication is blocked for -lack of consent, so that these situations can be resolved offline. - -Whitelisting and implicit consent is a short cut. The server side -already implements granting explicit consent, but until the UI is -ready, site operators have the option of allowing LH to function on a -fixed set of teams. diff --git a/src/understand/README.md b/src/understand/README.md index 22a96133..2ae5a002 100644 --- a/src/understand/README.md +++ b/src/understand/README.md @@ -82,12 +82,6 @@ - [Applying all configuration changes](configure-federation.md#applying-all-configuration-changes) - [Manually test that your configurations work as expected](configure-federation.md#manually-test-that-your-configurations-work-as-expected) -## 12. Legal Hold Setup -- [Installing and setting up Legal Hold](legalhold.md) - - [Introduction](legalhold.md#introduction) - - [Installing Legal Hold](legalhold.md#installing-legal-hold) - - [Configuring Team Settings to use Legal Hold](legalhold.md#configuring-team-settings-to-use-legal-hold) - ## 13. Security and Messaging - [Messaging Layer Security (MLS)](mls.md) diff --git a/src/understand/img/legalhold-screencast.gif b/src/understand/img/legalhold-screencast.gif deleted file mode 100644 index 24b90bb6..00000000 Binary files a/src/understand/img/legalhold-screencast.gif and /dev/null differ diff --git a/src/understand/img/legalhold-step01-click-customization.png b/src/understand/img/legalhold-step01-click-customization.png deleted file mode 100644 index 62325be4..00000000 Binary files a/src/understand/img/legalhold-step01-click-customization.png and /dev/null differ diff --git a/src/understand/img/legalhold-step02-goto-legalhold.png b/src/understand/img/legalhold-step02-goto-legalhold.png deleted file mode 100644 index 5b9630bf..00000000 Binary files a/src/understand/img/legalhold-step02-goto-legalhold.png and /dev/null differ diff --git a/src/understand/img/legalhold-step03-click-arrow.png b/src/understand/img/legalhold-step03-click-arrow.png deleted file mode 100644 index 403c65b4..00000000 Binary files a/src/understand/img/legalhold-step03-click-arrow.png and /dev/null differ diff --git a/src/understand/img/legalhold-step04-click-manage-configuration.png b/src/understand/img/legalhold-step04-click-manage-configuration.png deleted file mode 100644 index 48e100fc..00000000 Binary files a/src/understand/img/legalhold-step04-click-manage-configuration.png and /dev/null differ diff --git a/src/understand/img/legalhold-step05-fill-info.png b/src/understand/img/legalhold-step05-fill-info.png deleted file mode 100644 index b252fbf1..00000000 Binary files a/src/understand/img/legalhold-step05-fill-info.png and /dev/null differ diff --git a/src/understand/legalhold.md b/src/understand/legalhold.md deleted file mode 100644 index e6ca79c7..00000000 --- a/src/understand/legalhold.md +++ /dev/null @@ -1,143 +0,0 @@ -# Installing and setting up Legal Hold - -## Introduction - -Legal Hold is a service allowing for all communications of specific users of a Wire installation to be recorded in a secure vault, typically for legal reasons. - -The Legal Hold service is composed of three different sub-services: - -* Collector, which collects the conversations from individual users -* Exporter, which exports the conversations for storage -* Hold, which holds the conversation after Collector collects them, and before Exporter exports them - -A typical installation of Legal Hold looks like this: - -1. The Legal Hold service/container is installed and run on a server -2. The Teams Settings for the team that will use Legal Hold is configured to use this service -3. Specific users in that team are selected to have Legal Hold activated -4. These users are asked to confirm that they are aware of the information collection. Once they do, Legal Hold is active for their account. -5. Information starts being collected by the Collector service and stored by the Hold service - -## Installing Legal Hold - -To install and run Legal Hold, you need a server dedicated to the service. - -Here we will use Ubuntu 18.04 as it is the system wire-server is installed on, but other systems should be possible. - -First, we need to install postgreSQL: - -```bash - sudo apt update - sudo apt install postgresql -``` - -You then need to change the password to the database. First enter the PostgreSQL console: - -```bash - sudo -u postgres psql -``` - -Then use this command to change the password: - -```sql - ALTER USER postgres PASSWORD ''; -``` - -Also create a `legalhold` database: - -```sql - CREATE DATABASE legalhold; -``` - -Now that we have a working PostgreSQL database, we need to install the actual legalhold services. - -First install Git and Docker: - -```bash - sudo apt update - sudo apt install docker.io -``` - -Generate a random secret (`SERVICE_TOKEN`) to use as your service token. This will be used in the Team Settings step later when entering configuration. - -Here we will use `secr3t` as an example, however you can for example use this command to generate one: - -```bash - openssl rand -hex 20 -``` - -Finally, run the actual Docker container for the LegalHold service: - -```bash - docker run \ - -e DB_URL='jdbc:postgresql://localhost/legalhold' \ - -e DB_USER='postgres' \ - -e DB_PASSWORD='your-postgresql-password' \ - -e SERVICE_TOKEN='secr3t' \ - -p 80:8080 \ - --name secure-hold --rm quay.io/wire/legalhold:1.0.4 -``` - -* `DB_URL` is the URL of your PostgreSQL database. - -Now that the legalhold service is running, you need to configure the DNS for your domain so that `legal.` redirects to this service. - -Make sure you implement/enable HTTPS, and remember your TLS public key (in PEM format) as it will be necessary in the Team Settings configuration. - -## Configuring Team Settings to use Legal Hold - -The next step is to configure the Wire Team, in the Team Settings interface, to interface with the newly installed Legal Hold service. - -To do this, first go to `teams.`. - -Once in the interface, select `Customization` in the menu on the left: - -
- -![Customization](img/legalhold-step01-click-customization.png) - -
- -On the customization page, go to `Legal Hold`: - -
- -![Legal Hold](img/legalhold-step02-goto-legalhold.png) - -
- -Under the Legal Hold section, click the small down-pointing blue arrow: - -
- -![Arrow](img/legalhold-step03-click-arrow.png) - -
- -In the extended Legal Hold section, click on `Manage Configuration`: - -
- -![Manage Configuration](img/legalhold-step04-click-manage-configuration.png) - -
- -From here, you can fill in the required configuration info: - -
- -![Fill in configuration](img/legalhold-step05-fill-info.png) - -
- -Here, fill in the different fields: - -* `Service URL` is the domain you set up in the first step: `https://legal.` -* `Authentication token` is the token you created in first step, we used `secr3t` as an example, but you might have generated a random token with `openssl rand -hex 20` -* `Public Key` is the TLS public key (in PEM format) for the certificate you generated when implementing HTTPS in the first step. - -Finally, click on `Save`. - -Here is the entire process animated: - -![Animated](img/legalhold-screencast.gif)