========================================
encryption: encryption sessions handling
========================================

Libervia being an XMPP client does encryption by default between client and server. In
addition, SàT 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, SàT 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 SàT::

  $ 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 SàT 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