Mercurial > libervia-backend

annotate doc/encryption.rst @ 3958:e2a5f2f5e57b

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