diff --git a/doc/encryption.rst b/doc/encryption.rst index 5dad7908..78686434 100644 --- a/doc/encryption.rst +++ b/doc/encryption.rst @@ -15,13 +15,6 @@ To make your communications inaccessible to anybody but your recipient(s), end-t encryption (or e2ee) may be used. This page aims to explain roughly how it is done in Libervia and XMPP so end-user can understand and exploit it correctly. -.. note:: - - this page is work in progress, it will be completed over time to explain the whole - machanism. Is something is not clear, please contact the development team at the XMPP - room `libervia@chat.jabberfr.org `__ to get - details and help to improve this documentation. - .. _pubsub-encryption: @@ -43,14 +36,14 @@ Pubsub is not encrypted the same way as messages, because you generally need to items of a pubsub node, even if you get access to the node once items have already been published. -E2ee is currently done using `OpenPGP`_ (`XEP-0473: OpenPGP for XMPP Pubsub`_). Each item is encrypted -using a **symmetric** encryption, which mean that the same key (called "shared secret") is -used both to encrypt and decrypt an item, and is shared between all people who must access -or publish to the pubsub node (i.e. blog, event calendar, etc). This is done this way to -make it easy to add a new members, who can then access all archives of the node, but this -also means that if the shared secret is compromised (i.e. somebody who should not has -obtained a copy), all items made with this secret are accessible to the persons in -possession of the secret. +E2ee is currently done using `OpenPGP`_ (`XEP-0473: OpenPGP for XMPP Pubsub`_). Each item +is encrypted using a **symmetric** encryption, which mean that the same key (called +"shared secret") is used both to encrypt and decrypt an item, and is shared between all +people who must access or publish to the pubsub node (i.e. blog, event calendar, etc). +This is done this way to make it easy to add a new members, who can then access all +archives of the node, but this also means that if the shared secret is compromised (i.e. +somebody who should not has obtained a copy), all items made with this secret are +accessible to the persons in possession of the secret. To make an encrypted pubsub node accessible to somebody, you need to share the secret with them. @@ -98,13 +91,10 @@ On the other hand, you have all the properties of the algorithm used (for now, o 2 is supported), which means that you can have `Perfect Forward Secrecy`_ for algorithms supporting it (it's the case for OMEMO.) -.. note:: - - Pubsub Targeted Encryption(PTE) specification is not currently an official XEP (XMPP - Extension Protocol), it is about to be examinated by "XMPP council". This documentation - will be updated with the evolution of the situation. +Pubsub Target Encryption (PTE) is using `XEP-0477`_ .. _Perfect Forward Secrecy: https://en.wikipedia.org/wiki/Forward_secrecy +.. _XEP-0477: https://xmpp.org/extensions/xep-0477.html Pubsub Signature ================ @@ -114,7 +104,10 @@ may be specified by the pubsub service (using the `"publisher" attribute`_), but attribute is not set by all pubsub services, and it can be spoofed by the service or the XMPP server. -To strongly authenticate the publisher of a pubsub item, it is possible to cryptographically sign an item. This can work with any pubsub item, encrypted or not, and it can be done after the item has been published. The process use `XEP-0476: Pubsub Signing: OpenPGP Profile`_. +To strongly authenticate the publisher of a pubsub item, it is possible to +cryptographically sign an item. This can work with any pubsub item, encrypted or not, and +it can be done after the item has been published. The process use `XEP-0476: Pubsub +Signing: OpenPGP Profile`_. .. attention:: @@ -136,10 +129,18 @@ To handle pubsub signatures from command line, you may use E2EE with Email Gateway ======================= -For compatible gateways, Libervia supports "Relayed" encryption, which is a method for using end-to-end encryption (E2EE). This feature is currently experimental and only works for emails. +For compatible gateways, Libervia supports "Relayed" encryption, which is a method for +using end-to-end encryption (E2EE). This feature is currently experimental and only works +for emails. -If no key is known for an email recipient, Libervia uses Autocrypt. Autocrypt automatically exchanges encryption keys to enable what's called "opportunistic" encryption. While the security isn't as robust as proper key management and peer authentication, it still offers better protection than having no E2EE at all. Autocrypt is only used when a recipient’s key is not known by other, more secure means. +If no key is known for an email recipient, Libervia uses Autocrypt. Autocrypt +automatically exchanges encryption keys to enable what's called "opportunistic" +encryption. While the security isn't as robust as proper key management and peer +authentication, it still offers better protection than having no E2EE at all. Autocrypt is +only used when a recipient’s key is not known by other, more secure means. -For more information about Autocrypt and its security model, please refer to `Wikipedia's Autocrypt page`_. +For more information about Autocrypt and its security model, please refer to `Wikipedia's +Autocrypt page`_. .. _Wikipedia's Autocrypt page: https://en.wikipedia.org/wiki/Autocrypt + diff --git a/libervia/backend/plugins/plugin_sec_oxps.py b/libervia/backend/plugins/plugin_xep_0473.py similarity index 99% rename from libervia/backend/plugins/plugin_sec_oxps.py rename to libervia/backend/plugins/plugin_xep_0473.py index 355140f0..009f72d4 100644 --- a/libervia/backend/plugins/plugin_sec_oxps.py +++ b/libervia/backend/plugins/plugin_xep_0473.py @@ -20,7 +20,7 @@ import base64 import dataclasses import secrets import time -from typing import Any, Dict, Iterable, List, Optional, Set, Tuple, Union +from typing import Any, Dict, Iterable, List, Optional, Set, Tuple from collections import OrderedDict import shortuuid @@ -41,14 +41,13 @@ from libervia.backend.tools import utils from libervia.backend.tools import xml_tools from libervia.backend.tools.common import data_format from libervia.backend.tools.common import uri -from libervia.backend.tools.common.async_utils import async_lru from .plugin_xep_0373 import NS_OX, get_gpg_provider log = getLogger(__name__) -IMPORT_NAME = "OXPS" +IMPORT_NAME = "XEP-0473" PLUGIN_INFO = { C.PI_NAME: "OpenPGP for XMPP Pubsub", @@ -57,7 +56,7 @@ PLUGIN_INFO = { C.PI_MODES: C.PLUG_MODE_BOTH, C.PI_PROTOCOLS: [], C.PI_DEPENDENCIES: ["XEP-0060", "XEP-0334", "XEP-0373"], - C.PI_MAIN: "PubsubEncryption", + C.PI_MAIN: "XEP_0473", C.PI_HANDLER: "yes", C.PI_DESCRIPTION: _("""Pubsub e2e encryption via OpenPGP"""), } @@ -78,7 +77,7 @@ class SharedSecret: shared_with: Set[jid.JID] = dataclasses.field(default_factory=set) -class PubsubEncryption: +class XEP_0473: namespace = NS_OXPS def __init__(self, host): diff --git a/libervia/backend/plugins/plugin_sec_pubsub_signing.py b/libervia/backend/plugins/plugin_xep_0475.py similarity index 99% rename from libervia/backend/plugins/plugin_sec_pubsub_signing.py rename to libervia/backend/plugins/plugin_xep_0475.py index 1e3fda16..c50d2bb8 100644 --- a/libervia/backend/plugins/plugin_sec_pubsub_signing.py +++ b/libervia/backend/plugins/plugin_xep_0475.py @@ -42,16 +42,16 @@ from .plugin_xep_0373.exceptions import VerificationFailed log = getLogger(__name__) -IMPORT_NAME = "pubsub-signing" +IMPORT_NAME = "XEP-0475" PLUGIN_INFO = { C.PI_NAME: "Pubsub Signing", C.PI_IMPORT_NAME: IMPORT_NAME, C.PI_TYPE: C.PLUG_TYPE_XEP, C.PI_MODES: C.PLUG_MODE_BOTH, - C.PI_PROTOCOLS: [], + C.PI_PROTOCOLS: ["XEP-0475", "XEP-0476"], C.PI_DEPENDENCIES: ["XEP-0060", "XEP-0373", "XEP-0470"], - C.PI_MAIN: "PubsubSigning", + C.PI_MAIN: "XEP_0475", C.PI_HANDLER: "yes", C.PI_DESCRIPTION: _( """Pubsub Signature can be used to strongly authenticate a pubsub item""" @@ -61,7 +61,7 @@ NS_PUBSUB_SIGNING = "urn:xmpp:pubsub-signing:0" NS_PUBSUB_SIGNING_OPENPGP = "urn:xmpp:pubsub-signing:openpgp:0" -class PubsubSigning: +class XEP_0475: namespace = NS_PUBSUB_SIGNING def __init__(self, host): diff --git a/libervia/backend/plugins/plugin_sec_pte.py b/libervia/backend/plugins/plugin_xep_0477.py similarity index 97% rename from libervia/backend/plugins/plugin_sec_pte.py rename to libervia/backend/plugins/plugin_xep_0477.py index c06a5bb1..2ba774c0 100644 --- a/libervia/backend/plugins/plugin_sec_pte.py +++ b/libervia/backend/plugins/plugin_xep_0477.py @@ -34,7 +34,7 @@ from libervia.backend.core.log import getLogger log = getLogger(__name__) -IMPORT_NAME = "PTE" +IMPORT_NAME = "XEP-0477" PLUGIN_INFO = { C.PI_NAME: "Pubsub Targeted Encryption", @@ -43,14 +43,14 @@ PLUGIN_INFO = { C.PI_MODES: C.PLUG_MODE_BOTH, C.PI_PROTOCOLS: [], C.PI_DEPENDENCIES: ["XEP-0060", "XEP-0384"], - C.PI_MAIN: "PTE", + C.PI_MAIN: "XEP_0477", C.PI_HANDLER: "yes", C.PI_DESCRIPTION: _("""Encrypt some items to specific entities"""), } NS_PTE = "urn:xmpp:pte:0" -class PTE: +class XEP_0477: namespace = NS_PTE def __init__(self, host): @@ -62,7 +62,7 @@ class PTE: host.trigger.add("XEP-0060_items", self._items_trigger) def get_handler(self, client): - return PTE_Handler() + return XEP_0477_Handler() async def _publish_trigger( self, @@ -165,7 +165,7 @@ class PTE: @implementer(iwokkel.IDisco) -class PTE_Handler(xmlstream.XMPPHandler): +class XEP_0477_Handler(xmlstream.XMPPHandler): def getDiscoInfo(self, requestor, service, nodeIdentifier=""): return [disco.DiscoFeature(NS_PTE)]