Mercurial > libervia-backend

comparison doc/encryption.rst @ 3950:8f87ff449a34

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: new doc giving an overview on how e2ee is working in Libervia/XMPP: the doc explain pubsub e2ee for now rel 380
author Goffi <goffi@goffi.org>
date Sat, 15 Oct 2022 20:38:33 +0200
parents
children 9f85369294f3
comparison
equal deleted inserted replaced
3949:f7ff893b536e 3950:8f87ff449a34
1 .. _encryption:
2
3 ===========================
4 Encryption in Libervia/XMPP
5 ===========================
6
7 Libervia being an XMPP client, it handles encryption between client and server, then the
8 message is encrypted between servers, and finally to deliver to target client(s).
9
10 This avoid the communication to be accessible from people having access to the network,
11 but the communications are available to server administrators, or administrators of
12 services that you may use (e.g. pubsub service).
13
14 To make your communications inaccessible to anybody but your recipient(s), end-to-end
15 encryption (or e2ee) may be used. This page aims to explain roughly how it is done in
16 Libervia and XMPP so end-user can understand and exploit it correctly.
17
18 .. note::
19
20 this page is work in progress, it will be completed over time to explain the whole
21 machanism. Is something is not clear, please contact the development team at the XMPP
22 room `libervia@chat.jabberfr.org <xmpp:libervia@chat.jabberfr.org?join>`__ to get
23 details and help to improve this documentation.
24
25
26 .. _pubsub-encryption:
27
28 Pubsub Encryption
29 =================
30
31 By default, pubsub items are in plain text (i.e. not encrypted, beside the normal
32 encryption between client and server, and between servers). This is often the desired
33 behaviour as pubsub is often used for public matters (public blogs, events, or other kind
34 of data).
35
36 However, pubsub may also be used for private matters, to keep safe some of your own data,
37 or to uses all other kind of features privately (private blog, event organization, etc).
38
39 To make private pubsub node, in addition to the access model which restrict entities which
40 can retrieve its item, it is possible to use end-to-end encryption.
41
42 Pubsub is not encrypted the same way as messages, because you generally need to access all
43 items of a pubsub node, even if you get access to the node once items have already been
44 published.
45
46 E2ee is currently done using `OpenPGP`_ (or OX for PubSub: OXPS). Each item is encrypted
47 using a **symmetric** encryption, which mean that the same key (called "shared secret") is
48 used both to encrypt and decrypt an item, and is shared between all people who must access
49 or publish to the pubsub node (i.e. blog, event calendar, etc). This is done this way to
50 make it easy to add a new members, who can then access all archives of the node, but this
51 also means that if the shared secret is compromised (i.e. somebody who should not has
52 obtained a copy), all items made with this secret are accessible to the persons in
53 possession of the secret.
54
55 .. note::
56
57 OXPS specification is not currently an official XEP (XMPP Extension Protocol), it is
58 about to be examinated by "XMPP council". This documentation will be updated with the
59 evolution of the situation. You can read current specification proposal at
60 https://xmpp.org/extensions/inbox/pubsub-encryption.html (which is inaccessible due to
61 a 404 error at the time of writting, this should be fixed hopefully when you read this
62 documentation).
63
64 To make an encrypted pubsub node accessible to somebody, you need to share the secret with
65 them.
66
67 You can see that as the key of a house: everybody who has a copy of the key can go inside
68 the house, and bring something or take pictures. Sharing the secret is like making
69 a copy of the key and giving it to the person.
70
71 If you think that your shared secret is compromised (obtained by somebody who shouldn't),
72 or if you want to remove access to somebody, you can "rotate" the secret, which means that
73 every existing key is revoked (flagged as "you should not use it anymore to write
74 something", but you can still use it to read archives), and a new one is created (to write
75 new items).
76
77 With the house analogy, it's like changing the locks, and giving new keys to trusted
78 people: people with the older keys can't go inside the house anymore, but if they have
79 taken pictures before the key has been changed, theirs pictures is still in their
80 possession.
81
82 .. attention::
83
84 If you rotate the shared secret, new items are using the new secret, but all items
85 which were existing before the secret rotation stay accessible to people who had access
86 to former secrets (the pubsub node can refuse access to them though). If malicious
87 people had access to items before, they could have made copy anytime, thus there is
88 little point in reencrypting everything.
89
90 To handle encrypted pubsub node shared secrets from command line, you may use
91 :ref:`libervia-cli_pubsub_secret`.
92
93 .. _OpenPGP: https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP
94