# HG changeset patch # User Goffi # Date 1665859113 -7200 # Node ID 8f87ff449a3457df54c182feed5872be77e43182 # Parent f7ff893b536eb059ab3a160ff4281ddeb6b6d5c5 doc: new doc giving an overview on how e2ee is working in Libervia/XMPP: the doc explain pubsub e2ee for now rel 380 diff -r f7ff893b536e -r 8f87ff449a34 doc/encryption.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/encryption.rst Sat Oct 15 20:38:33 2022 +0200 @@ -0,0 +1,94 @@ +.. _encryption: + +=========================== +Encryption in Libervia/XMPP +=========================== + +Libervia being an XMPP client, it handles encryption between client and server, then the +message is encrypted between servers, and finally to deliver to target client(s). + +This avoid the communication to be accessible from people having access to the network, +but the communications are available to server administrators, or administrators of +services that you may use (e.g. pubsub service). + +To make your communications inaccessible to anybody but your recipient(s), end-to-end +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: + +Pubsub Encryption +================= + +By default, pubsub items are in plain text (i.e. not encrypted, beside the normal +encryption between client and server, and between servers). This is often the desired +behaviour as pubsub is often used for public matters (public blogs, events, or other kind +of data). + +However, pubsub may also be used for private matters, to keep safe some of your own data, +or to uses all other kind of features privately (private blog, event organization, etc). + +To make private pubsub node, in addition to the access model which restrict entities which +can retrieve its item, it is possible to use end-to-end encryption. + +Pubsub is not encrypted the same way as messages, because you generally need to access all +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`_ (or OX for PubSub: OXPS). 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. + +.. note:: + + OXPS 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. You can read current specification proposal at + https://xmpp.org/extensions/inbox/pubsub-encryption.html (which is inaccessible due to + a 404 error at the time of writting, this should be fixed hopefully when you read this + documentation). + +To make an encrypted pubsub node accessible to somebody, you need to share the secret with +them. + +You can see that as the key of a house: everybody who has a copy of the key can go inside +the house, and bring something or take pictures. Sharing the secret is like making +a copy of the key and giving it to the person. + +If you think that your shared secret is compromised (obtained by somebody who shouldn't), +or if you want to remove access to somebody, you can "rotate" the secret, which means that +every existing key is revoked (flagged as "you should not use it anymore to write +something", but you can still use it to read archives), and a new one is created (to write +new items). + +With the house analogy, it's like changing the locks, and giving new keys to trusted +people: people with the older keys can't go inside the house anymore, but if they have +taken pictures before the key has been changed, theirs pictures is still in their +possession. + +.. attention:: + + If you rotate the shared secret, new items are using the new secret, but all items + which were existing before the secret rotation stay accessible to people who had access + to former secrets (the pubsub node can refuse access to them though). If malicious + people had access to items before, they could have made copy anytime, thus there is + little point in reencrypting everything. + +To handle encrypted pubsub node shared secrets from command line, you may use +:ref:`libervia-cli_pubsub_secret`. + +.. _OpenPGP: https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP + diff -r f7ff893b536e -r 8f87ff449a34 doc/index.rst --- a/doc/index.rst Sat Oct 15 20:38:33 2022 +0200 +++ b/doc/index.rst Sat Oct 15 20:38:33 2022 +0200 @@ -26,6 +26,7 @@ installation.rst overview.rst configuration.rst + encryption.rst components.rst developer.rst /libervia-cli/index.rst