126 lines
8.9 KiB
Markdown
126 lines
8.9 KiB
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.
|