diff --git a/doc/conf.py b/doc/conf.py index 831488d4..408fd203 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -59,7 +59,7 @@ rst_prolog = """ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx.ext.autodoc", "docstring"] +extensions = ["sphinx.ext.autodoc", "docstring", "sphinxcontrib.autodoc_pydantic"] # Add any paths that contain templates here, relative to this directory. templates_path = [".templates"] @@ -193,3 +193,11 @@ epub_exclude_files = ["search.html"] # -- Extension configuration ------------------------------------------------- + +## autodoc_pydantic + +autodoc_pydantic_settings_show_config_summary = False +autodoc_pydantic_settings_show_json = False +autodoc_pydantic_settings_show_field_summary = False +autodoc_pydantic_settings_member_order = "bysource" +autodoc_pydantic_field_signature_prefix = "" diff --git a/doc/index.rst b/doc/index.rst index a1764045..cb07b970 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -28,6 +28,7 @@ You can follow this documentation to learn more on it, or join our official XMPP overview.rst configuration.rst encryption.rst + tor.rst components.rst developer.rst /libervia-cli/index.rst diff --git a/doc/libervia-cli/info.rst b/doc/libervia-cli/info.rst index fadd33db..7e4601df 100644 --- a/doc/libervia-cli/info.rst +++ b/doc/libervia-cli/info.rst @@ -51,7 +51,7 @@ Check version of a server:: $ li info version example.org session -------- +======= Give information about the session of the given profile. You'll get the full jid currently used on the server, and the time when the session was started (which may not be the same @@ -65,7 +65,7 @@ Get session informations:: $ li info session devices -------- +======= List known devices for an entity. You'll get resource name, and data such as presence data, and identities (i.e. name and type of the client used). @@ -82,3 +82,18 @@ List known devices of Louise:: Check if we have other devices connected:: $ li info devices + +.. _libervia-cli_info_tor: +tor +=== + +Show information about the running Tor daemon (if any and if it is activated for the +profile), and about the circuit used to connect to the XMPP server. + +example +------- + +Get information on Tor state and the circuit used for Louise to connect to her XMPP +server:: + + $ li info tor diff --git a/doc/tor.rst b/doc/tor.rst new file mode 100644 index 00000000..011cde7b --- /dev/null +++ b/doc/tor.rst @@ -0,0 +1,89 @@ +.. _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 `. diff --git a/pyproject.toml b/pyproject.toml index b52084f8..adf7fa67 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -112,6 +112,7 @@ tests = [ docs = [ "sphinx ~= 9.0", + "autodoc_pydantic ~= 2.2" ] dev = [