.. _libervia_over_tor:

=======================
Using Libervia over Tor
=======================

Libervia can be used over `Tor`_ to reduce metadata exposure by hiding your IP address,
and to connect to hidden `.onion` services or clearnet XMPP servers.

.. warning::

   Keep in mind that Libervia is currently a solo developer project and has not been
   extensively audited for security. It's a complex software, and there may be bugs or
   incomplete implementations that could lead to leaking your identity, IP address, or
   other personal information.

   DO NOT USE THIS SOFTWARE IF YOUR LIFE DEPENDS ON BEING ANONYMOUS, OR IF YOU ARE AT RISK
   OF ANY KIND OF DANGER.

   Also, it’s not a good idea to rely solely on Tor with just one software on your
   machine. Instead, use well-established projects such as `Tails`_, which is built from
   the ground up with anonymity and security in mind. Even then, be cautious and consult
   trusted people who know what they’re doing.

   Tor integration in Libervia is provided as a convenience and to reduce metadata
   exposure, BUT IT IS NOT SAFE ENOUGH for life-threatening or dangerous situations.

   This may change in the future if the Libervia ecosystem grows enough to attract many
   expert eyes to analyze, test, and fix it; if we have full-time security experts working
   on the project; and when external, extensive security audits are performed.

.. _Tor: https://www.torproject.org
.. _Tails: https://tails.net/

Prerequisites
=============

To use Tor with Libervia, you need to have installed ``txtorcon``, which should be done if
you used the ``tor`` or ``all`` extras during Libervia installation.

You'll also need a correctly configured and running Tor daemon.

Tor Daemon
==========

To connect over Tor, the Tor daemon must be running. Check your operating system’s
documentation for instructions on how to do this.

Libervia connects to Tor via its "Control" protocol, using "Cookie" authentication.

.. note::

  Only Cookie authentication is implemented so far. If there is demand for password
  authentication, it may be added in the future.

You probably need these configuration lines in your Tor configuration (usually in
``/etc/tor/torrc``)::

  CookieAuthentication 1
  CookieAuthFile /var/lib/tor/control_auth_cookie
  CookieAuthFileGroupReadable 1
  DataDirectoryGroupReadable 1

Don't forget to restart your daemon if you have updated your configuration (usually done
with ``sudo systemctl restart tor``).

Libervia Settings
=================

Tor settings are configured in the ``[tor]`` section. Here are the options you can use:

.. autopydantic_settings:: libervia.backend.tools.config.TorSettings

If you want to use Tor for all connections, set ``enabled = true``.

Tor will also be automatically activated if you're connecting to a ``.onion`` XMPP domain.

.. note::

  When Tor is activated, WebRTC is disabled due to IP leak risks. While this behavior may
  change in the future perhaps by forcing Tor relay usage for features like file transfer,
  the combination of slow connection speeds and high latency introduced by Tor will likely
  make audio/video calling completely impractical.

Getting Information
===================

To get information about the state of the Tor daemon and the circuit you are using, you
can use :ref:`libervia-cli info tor <libervia-cli_info_tor>`.