Mercurial > libervia-backend

comparison doc/jp/encryption.rst @ 3041:72583524cfd3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (jp): jp commands are now fully documented: rel 232
author Goffi <goffi@goffi.org>
date Tue, 01 Oct 2019 22:49:06 +0200
parents
children 92f8baec5e4f
comparison
equal deleted inserted replaced
3040:fee60f17ebac 3041:72583524cfd3
1 ========================================
2 encryption: encryption sessions handling
3 ========================================
4
5 Salut à Toi being an XMPP client does encryption by default between client and server. In
6 addition, SàT is also capable of doing end-to-end (e2e) encryption, meaning that the
7 payload of messages are encrypted to be hidden from the servers (and their
8 administrators). The ``encryption`` commands are here to handle those e2e encryption
9 sessions and algorithms.
10
11 .. note::
12
13 For the moment, only one 2 one chat messages can be e2e encrypted
14
15 algorithms
16 ==========
17
18 Display e2e encryption algorithms available in this instance of Salut à Toi.
19
20 example
21 -------
22
23 Show available e2e algorithms::
24
25 $ jp encryption algorithms
26
27 get
28 ===
29
30 Display which encryption session is currently active with the given entity.
31
32 The only required argument is the JID of the entity.
33
34 If not e2e encryption session exist, a message will be displayed and jp will exit with a
35 non zero code: this means that the messages are in clear in the XMPP servers, but normal
36 XMPP encryption is not affected (message should still be encrypted between client and
37 server and between servers).
38
39 If an e2e encryption session exist, you'll see the algorithm name and its namespace. In
40 case of e2e encryption which only works from device to device (e.g. it's the case with
41 ``OTR`` which doesn't support multiple devices), you'll also see the resources of the
42 devices where the encryption is active in ``directed_devices``
43
44 example
45 -------
46
47 Check if session is encrypted with Louise::
48
49 $ jp encryption get louise@example.org
50
51 start
52 =====
53
54 Start e2e session with an entity.
55
56 You need to specify the JID of the entity you want to start a session with as a positional
57 argument.
58
59 By default, SàT will select itself the algorithm to use among those available, but you can
60 specify one using either its name with ``-n NAME, --name NAME`` or its namespace using
61 ``-N NAMESPACE, --namespace``. ``NAME`` is the short name of the algorithm, e.g. ``omemo``
62 while the namespace is the longer (e.g. ``urn:xmpp:otr:0``).
63
64 If an encryption session is started but one with an other algorithm was already there, the
65 original session will be stopped and replaced by one with the new requested algorithm. You
66 can change this behaviour by using ``--encrypt-noreplace``: in this case the command will
67 fail in case of conflict (e2e encryption is requested with a new algorithm while an e2e
68 encryption session was already started with an other algorithm), and return a non-zero
69 code. If an e2e encryption session was already started with the requested algorithm, the
70 command will succeed in all cases an nothing will be changed.
71
72 examples
73 --------
74
75 Start e2e encryption with Pierre, using the algorithm selected by SàT::
76
77 $ jp encryption start louise@example.net
78
79 Start an OMEMO session with Louise::
80
81 $ jp encryption start -n omemo louise@example.org
82
83 stop
84 ====
85
86 Terminate an e2e session with given entity. The entity must be specified as positional
87 argument.
88
89 After this command is run, the messages with specified entity will not be e2e encrypted
90 anymore (but this won't affect encryption between SàT and XMPP server and between XMPP
91 servers).
92
93 example
94 -------
95
96 Stop the e2e encryption session with Pierre::
97
98 $ jp encryption stop pierre@example.net
99
100 trust ui
101 ========
102
103 Run the user interface to handle trust with given entity and given algorithm. The user
104 interface depends of the algorithm used, but it generally shows you the fingerprints
105 associated with your contact or contact devices, and asks you if you trust them or not.
106
107 The only mandatory argument is the jid of your contact.
108
109 By default the currently active encryption session algorithm is used, but you may manage
110 trust for an other algorithm by using ``-n NAME, --name NAME`` or ``-N NAMESPACE,
111 --namespace NAMESPACE``.
112
113 .. note::
114
115 Trusting a contact or a device means that you certify that this contact or device is
116 the one you want to talk too. You should not trust a device if you have not verified by
117 an external channel (i.e. not XMPP) the fingerprint. The best way is to verify the
118 fingerprint physically if possible (i.e. in front of your contact, not with computer
119 networks in the middle).
120
121 example
122 -------
123
124 Manage ``OMEMO`` trust with Louise devices::
125
126 $ jp encryption trust ui -n omemo louise@example.org