mod_e2e_policy/README.markdown

## Introduction ##

This module was written to encourage or enforce usage of end-to-end encryption.
It will warn senders of messages without acceptable E2EE through a chosen
warning mechanism and outright block messages when using the "required" policy.

Policies can be escalated from `optional` to `required` per user with a
configurable grace period.

Whitelisting of user and MUC JIDs is also supported, so administrators can
for example enable users having E2EE issues to contact support contacts or MUCS.


## Configuration ##

Enable the module as any other:

    modules_enabled = {
      "e2e_policy";
    }

You can then set some options to configure your desired policy:

| Option                                                | Default               | Description                                                                                       |
|-------------------------------------------------------|-----------------------|---------------------------------------------------------------------------------------------------|
| e2e\_policy\_accepted\_schemes                        | `{"omemo", "pgp"}`    | List of acceptable E2EE schemes. Possible values: `"omemo"`, `"pgp"`, `"pgp_legacy"` and `"otr"`. |
| e2e\_policy\_direct                                   | `"optional"`          | Policy for direct messages. Possible values: `"none"`, `"optional"` and `"required"`.             |
| e2e\_policy\_group                                    | `"optional"`          | Policy for group messages. Possible values: `"none"`, `"optional"` and `"required"`.              |
| e2e\_policy\_warn\_mechanism                          | `"message"`           | Mechanism to use to communicate lack of E2EE with. Possible values: `"message"` and `"error"`.    |
| e2e\_policy\_whitelist                                | `{ }`                 | Make this module ignore messages sent to and from these JIDs. Can include MUCs.                   |
| e2e\_policy\_message\_plain\_optional\_direct         |                       | See [custom messages](#custom-messages).                                                          |
| e2e\_policy\_message\_plain\_required\_direct         |                       | See [custom messages](#custom-messages).                                                          |
| e2e\_policy\_message\_unacceptable\_optional\_direct  |                       | See [custom messages](#custom-messages).                                                          |
| e2e\_policy\_message\_unacceptable\_required\_direct  |                       | See [custom messages](#custom-messages).                                                          |
| e2e\_policy\_message\_plain\_optional\_group          |                       | See [custom messages](#custom-messages).                                                          |
| e2e\_policy\_message\_plain\_required\_group          |                       | See [custom messages](#custom-messages).                                                          |
| e2e\_policy\_message\_unacceptable\_optional\_group   |                       | See [custom messages](#custom-messages).                                                          |
| e2e\_policy\_message\_unacceptable\_required\_group   |                       | See [custom messages](#custom-messages).                                                          |
| e2e\_policy\_message\_graceperiod                     |                       | See [custom messages](#custom-messages).                                                          |

Some examples:

    e2e_policy_accepted_schemes = {"omemo", "otr", "pgp", "pgp_legacy"}
    e2e_policy_direct = "required"
    e2e_policy_group = "optional"
    e2e_policy_warn_mechanism = "error"
    e2e_policy_whitelist = { "admin@example.com", "prosody@conference.prosody.im" }


## Recognized E2EE schemes ##

* `"omemo"`: [XEP-0384]
* `"otr"`: [XEP-0364]
* `"pgp"`: [XEP-0373]
* `"pgp_legacy"`: [XEP-0027]

[XEP-0384]: https://xmpp.org/extensions/xep-0384.html
[XEP-0364]: https://xmpp.org/extensions/xep-0364.html
[XEP-0027]: https://xmpp.org/extensions/xep-0027.html
[XEP-0373]: https://xmpp.org/extensions/xep-0373.html


## A word on warning mechanisms ##

Depending on the value of `e2e_policy_warn_mechanism`, warnings are sent either
as `<message>` stanzas of type `error` or as normal messages from the servers'
own JID.

Error messages should™ be shown directly in the affected conversations by
clients and as such are the superior mechanism – the problem is just that
some contemporary clients don't honor them. This is why `"message"` is
currently the default.


## Custom messages{#custom-messages}

The `e2e_policy_message_*` options can be used to set custom messages to be sent to users on policy violations.  
The names for these are built like this: `e2e_policy_message_<reason>_<policy>_<chat-type>`.

The variable parts are as follows:

* `<reason>`: Whether this warning is caused by plaintext communication (`plain`) or an `unacceptable` E2EE scheme being used.
* `<policy>`: What policy this warning is sent for, `optional` or `required`.
* `<chat-type>`: The type of chat this warning is for, either `direct` or `group`.

Unless otherwise configured, the messages for `<chat-type>` `group` are inherited from the corresponding messages for `direct` chats.

Additionally, the following interpolation patterns are available to inject some contextual information:

* `{recipient}`: The JID the message was supposed to go to.
* `{scheme}`: The E2EE scheme used in the offending message, or `"none"`.
* `{accepted_schemes}`: A stringified list of accepted E2EE schemes.
* `{graceperiod_remaining}`: A pretty representation of the remaining time until the grace period is over. Only available in `e2e_policy_message_graceperiod`.

`e2e_policy_message_graceperiod` is automatically appended to the selected warning message when it applies (i.e. when a grace period is active and not expired).

### Default messages ###

| Option                                            | Value                                                                                                                                                                         
|---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `e2e_policy_message_plain_optional_direct`        | `"Your message to {recipient} was not end-to-end encrypted. For security reasons, using one of the following E2EE schemes is *STRONGLY* recommended: {accepted_schemes} "`                        |
| `e2e_policy_message_plain_required_direct`        | `"Your message to {recipient} was not end-to-end encrypted. For security reasons, using one of the following E2EE schemes is *REQUIRED* for conversations on this server: {accepted_schemes} "`   |
| `e2e_policy_message_unacceptable_optional_direct` | `"Your message to {recipient} was end-to-end encrypted using the {scheme} scheme, but we recommend using one of the following instead: {accepted_schemes} "`                                      |
| `e2e_policy_message_unacceptable_required_direct` | `"Your message to {recipient} was end-to-end encrypted using the {scheme} scheme, but this server *REQUIRES* one of these: {accepted_schemes} "`                                                  |
| `e2e_policy_message_plain_optional_group`         | `e2e_policy_message_plain_optional_direct`                                                                                                                                                        |
| `e2e_policy_message_plain_required_group`         | `e2e_policy_message_plain_required_direct`                                                                                                                                                        |
| `e2e_policy_message_unacceptable_optional_group`  | `e2e_policy_message_unacceptable_optional_direct`                                                                                                                                                 |
| `e2e_policy_message_unacceptable_required_group`  | `e2e_policy_message_unacceptable_required_direct`                                                                                                                                                 |
| `e2e_policy_message_graceperiod`                  | `"You have {graceperiod_remaining} left before this will be enforced and messages without acceptable E2EE will be discarded."`                                                                    |


## Compatibility ##

| Version | State       |
|---------|-------------|
| trunk   | Should work |
| 0.11    | Works       |
| 0.10    | Should work |
| 0.9     | Should work |


## Contributors ##

This module was initially written by Michel Le Bihan.
It was later greatly extended by phryk.