--- /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 <xmpp:libervia@chat.jabberfr.org?join>`__ 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
+

--- 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