Mercurial > libervia-backend
annotate doc/jp/encryption.rst @ 3254:6cf4bd6972c2
core, frontends: avatar refactoring:
/!\ huge commit
Avatar logic has been reworked around the IDENTITY plugin: plugins able to handle avatar
or other identity related metadata (like nicknames) register to IDENTITY plugin in the
same way as for other features like download/upload. Once registered, IDENTITY plugin will
call them when suitable in order of priority, and handle caching.
Methods to manage those metadata from frontend now use serialised data.
For now `avatar` and `nicknames` are handled:
- `avatar` is now a dict with `path` + metadata like `media_type`, instead of just a string
path
- `nicknames` is now a list of nicknames in order of priority. This list is never empty,
and `nicknames[0]` should be the preferred nickname to use by frontends in most cases.
In addition to contact specified nicknames, user set nickname (the one set in roster) is
used in priority when available.
Among the side changes done with this commit, there are:
- a new `contactGet` bridge method to get roster metadata for a single contact
- SatPresenceProtocol.send returns a Deferred to check when it has actually been sent
- memory's methods to handle entities data now use `client` as first argument
- metadata filter can be specified with `getIdentity`
- `getAvatar` and `setAvatar` are now part of the IDENTITY plugin instead of XEP-0054 (and
there signature has changed)
- `isRoom` and `getBareOrFull` are now part of XEP-0045 plugin
- jp avatar/get command uses `xdg-open` first when available for `--show` flag
- `--no-cache` has been added to jp avatar/get and identity/get
- jp identity/set has been simplified, explicit options (`--nickname` only for now) are
used instead of `--field`. `--field` may come back in the future if necessary for extra
data.
- QuickContactList `SetContact` now handle None as a value, and doesn't use it to delete the
metadata anymore
- improved cache handling for `metadata` and `nicknames` in quick frontend
- new `default` argument in QuickContactList `getCache`
author | Goffi <goffi@goffi.org> |
---|---|
date | Tue, 14 Apr 2020 21:00:33 +0200 |
parents | 92f8baec5e4f |
children |
rev | line source |
---|---|
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
1 ======================================== |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
2 encryption: encryption sessions handling |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
3 ======================================== |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
4 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
5 Salut à Toi being an XMPP client does encryption by default between client and server. In |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
6 addition, SàT is also capable of doing end-to-end (e2e) encryption, meaning that the |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
7 payload of messages are encrypted to be hidden from the servers (and their |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
8 administrators). The ``encryption`` commands are here to handle those e2e encryption |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
9 sessions and algorithms. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
10 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
11 .. note:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
12 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
13 For the moment, only one 2 one chat messages can be e2e encrypted |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
14 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
15 algorithms |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
16 ========== |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
17 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
18 Display e2e encryption algorithms available in this instance of Salut à Toi. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
19 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
20 example |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
21 ------- |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
22 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
23 Show available e2e algorithms:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
24 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
25 $ jp encryption algorithms |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
26 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
27 get |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
28 === |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
29 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
30 Display which encryption session is currently active with the given entity. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
31 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
32 The only required argument is the JID of the entity. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
33 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
34 If not e2e encryption session exist, a message will be displayed and jp will exit with a |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
35 non zero code: this means that the messages are in clear in the XMPP servers, but normal |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
36 XMPP encryption is not affected (message should still be encrypted between client and |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
37 server and between servers). |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
38 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
39 If an e2e encryption session exist, you'll see the algorithm name and its namespace. In |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
40 case of e2e encryption which only works from device to device (e.g. it's the case with |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
41 ``OTR`` which doesn't support multiple devices), you'll also see the resources of the |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
42 devices where the encryption is active in ``directed_devices`` |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
43 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
44 example |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
45 ------- |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
46 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
47 Check if session is encrypted with Louise:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
48 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
49 $ jp encryption get louise@example.org |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
50 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
51 start |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
52 ===== |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
53 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
54 Start e2e session with an entity. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
55 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
56 You need to specify the JID of the entity you want to start a session with as a positional |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
57 argument. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
58 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
59 By default, SàT will select itself the algorithm to use among those available, but you can |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
60 specify one using either its name with ``-n NAME, --name NAME`` or its namespace using |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
61 ``-N NAMESPACE, --namespace``. ``NAME`` is the short name of the algorithm, e.g. ``omemo`` |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
62 while the namespace is the longer (e.g. ``urn:xmpp:otr:0``). |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
63 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
64 If an encryption session is started but one with an other algorithm was already there, the |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
65 original session will be stopped and replaced by one with the new requested algorithm. You |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
66 can change this behaviour by using ``--encrypt-noreplace``: in this case the command will |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
67 fail in case of conflict (e2e encryption is requested with a new algorithm while an e2e |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
68 encryption session was already started with an other algorithm), and return a non-zero |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
69 code. If an e2e encryption session was already started with the requested algorithm, the |
3054 | 70 command will succeed in all cases and nothing will be changed. |
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
71 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
72 examples |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
73 -------- |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
74 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
75 Start e2e encryption with Pierre, using the algorithm selected by SàT:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
76 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
77 $ jp encryption start louise@example.net |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
78 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
79 Start an OMEMO session with Louise:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
80 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
81 $ jp encryption start -n omemo louise@example.org |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
82 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
83 stop |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
84 ==== |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
85 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
86 Terminate an e2e session with given entity. The entity must be specified as positional |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
87 argument. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
88 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
89 After this command is run, the messages with specified entity will not be e2e encrypted |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
90 anymore (but this won't affect encryption between SàT and XMPP server and between XMPP |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
91 servers). |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
92 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
93 example |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
94 ------- |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
95 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
96 Stop the e2e encryption session with Pierre:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
97 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
98 $ jp encryption stop pierre@example.net |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
99 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
100 trust ui |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
101 ======== |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
102 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
103 Run the user interface to handle trust with given entity and given algorithm. The user |
3054 | 104 interface depends on the algorithm used, but it generally shows you the fingerprints |
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
105 associated with your contact or contact devices, and asks you if you trust them or not. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
106 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
107 The only mandatory argument is the jid of your contact. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
108 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
109 By default the currently active encryption session algorithm is used, but you may manage |
3054 | 110 trust for another algorithm by using ``-n NAME, --name NAME`` or ``-N NAMESPACE, |
3041
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
111 --namespace NAMESPACE``. |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
112 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
113 .. note:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
114 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
115 Trusting a contact or a device means that you certify that this contact or device is |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
116 the one you want to talk too. You should not trust a device if you have not verified by |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
117 an external channel (i.e. not XMPP) the fingerprint. The best way is to verify the |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
118 fingerprint physically if possible (i.e. in front of your contact, not with computer |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
119 networks in the middle). |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
120 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
121 example |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
122 ------- |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
123 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
124 Manage ``OMEMO`` trust with Louise devices:: |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
125 |
72583524cfd3
doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents:
diff
changeset
|
126 $ jp encryption trust ui -n omemo louise@example.org |