126 lines
4.3 KiB
ReStructuredText
126 lines
4.3 KiB
ReStructuredText
========================================
|
|
encryption: encryption sessions handling
|
|
========================================
|
|
|
|
Libervia being an XMPP client does encryption by default between client and server. In
|
|
addition, Libervia is also capable of doing end-to-end (e2e) encryption, meaning that the
|
|
payload of messages are encrypted to be hidden from the servers (and their
|
|
administrators). The ``encryption`` commands are here to handle those e2e encryption
|
|
sessions and algorithms.
|
|
|
|
.. note::
|
|
|
|
For the moment, only one 2 one chat messages can be e2e encrypted
|
|
|
|
algorithms
|
|
==========
|
|
|
|
Display e2e encryption algorithms available in this instance of Libervia.
|
|
|
|
example
|
|
-------
|
|
|
|
Show available e2e algorithms::
|
|
|
|
$ li encryption algorithms
|
|
|
|
get
|
|
===
|
|
|
|
Display which encryption session is currently active with the given entity.
|
|
|
|
The only required argument is the JID of the entity.
|
|
|
|
If not e2e encryption session exist, a message will be displayed and li will exit with a
|
|
non zero code: this means that the messages are in clear in the XMPP servers, but normal
|
|
XMPP encryption is not affected (message should still be encrypted between client and
|
|
server and between servers).
|
|
|
|
If an e2e encryption session exist, you'll see the algorithm name and its namespace. In
|
|
case of e2e encryption which only works from device to device (e.g. it's the case with
|
|
``OTR`` which doesn't support multiple devices), you'll also see the resources of the
|
|
devices where the encryption is active in ``directed_devices``
|
|
|
|
example
|
|
-------
|
|
|
|
Check if session is encrypted with Louise::
|
|
|
|
$ li encryption get louise@example.org
|
|
|
|
start
|
|
=====
|
|
|
|
Start e2e session with an entity.
|
|
|
|
You need to specify the JID of the entity you want to start a session with as a positional
|
|
argument.
|
|
|
|
By default, Libervia will select itself the algorithm to use among those available, but you can
|
|
specify one using either its name with ``-n NAME, --name NAME`` or its namespace using
|
|
``-N NAMESPACE, --namespace``. ``NAME`` is the short name of the algorithm, e.g. ``omemo``
|
|
while the namespace is the longer (e.g. ``urn:xmpp:otr:0``).
|
|
|
|
If an encryption session is started but one with an other algorithm was already there, the
|
|
original session will be stopped and replaced by one with the new requested algorithm. You
|
|
can change this behaviour by using ``--encrypt-noreplace``: in this case the command will
|
|
fail in case of conflict (e2e encryption is requested with a new algorithm while an e2e
|
|
encryption session was already started with an other algorithm), and return a non-zero
|
|
code. If an e2e encryption session was already started with the requested algorithm, the
|
|
command will succeed in all cases and nothing will be changed.
|
|
|
|
examples
|
|
--------
|
|
|
|
Start e2e encryption with Pierre, using the algorithm selected by Libervia::
|
|
|
|
$ li encryption start louise@example.net
|
|
|
|
Start an OMEMO session with Louise::
|
|
|
|
$ li encryption start -n omemo louise@example.org
|
|
|
|
stop
|
|
====
|
|
|
|
Terminate an e2e session with given entity. The entity must be specified as positional
|
|
argument.
|
|
|
|
After this command is run, the messages with specified entity will not be e2e encrypted
|
|
anymore (but this won't affect encryption between Libervia and XMPP server and between XMPP
|
|
servers).
|
|
|
|
example
|
|
-------
|
|
|
|
Stop the e2e encryption session with Pierre::
|
|
|
|
$ li encryption stop pierre@example.net
|
|
|
|
trust ui
|
|
========
|
|
|
|
Run the user interface to handle trust with given entity and given algorithm. The user
|
|
interface depends on the algorithm used, but it generally shows you the fingerprints
|
|
associated with your contact or contact devices, and asks you if you trust them or not.
|
|
|
|
The only mandatory argument is the jid of your contact.
|
|
|
|
By default the currently active encryption session algorithm is used, but you may manage
|
|
trust for another algorithm by using ``-n NAME, --name NAME`` or ``-N NAMESPACE,
|
|
--namespace NAMESPACE``.
|
|
|
|
.. note::
|
|
|
|
Trusting a contact or a device means that you certify that this contact or device is
|
|
the one you want to talk too. You should not trust a device if you have not verified by
|
|
an external channel (i.e. not XMPP) the fingerprint. The best way is to verify the
|
|
fingerprint physically if possible (i.e. in front of your contact, not with computer
|
|
networks in the middle).
|
|
|
|
example
|
|
-------
|
|
|
|
Manage ``OMEMO`` trust with Louise devices::
|
|
|
|
$ li encryption trust ui -n omemo louise@example.org
|