diff --git a/conf.py b/conf.py index e020831a848939a4e212af190ed3096e0cd4f074..7a45d8e90ba9e66396f4ce2357ab1a7c88038262 100644 --- a/conf.py +++ b/conf.py @@ -22,7 +22,8 @@ copyright = '2018-2022 Savoir-faire Linux Inc. and contributors' author = 'Savoir-faire Linux Inc. and contributors' extensions = [ - 'myst_parser' + 'myst_parser', + 'sphinx.ext.autosectionlabel', ] source_suffix = { @@ -30,6 +31,9 @@ source_suffix = { '.md': 'markdown', } +autosectionlabel_prefix_document = True +autosectionlabel_maxdepth = 4 + templates_path = ['_templates'] exclude_patterns = ['_build'] diff --git a/general/faq.rst b/general/faq.rst new file mode 100644 index 0000000000000000000000000000000000000000..a2d7795057b7debd43da33af2a69cf4af7c3cb9f --- /dev/null +++ b/general/faq.rst @@ -0,0 +1,669 @@ +FAQ +=== + +This is an exhaustive list of frequently asked questions, including +some technical questions. + +.. contents:: + :local: + :depth: 3 + + +Basics +------ + +What is Jami? +~~~~~~~~~~~~~ + +See the :doc:`Introduction <introduction>`. + +What does Jami mean? +~~~~~~~~~~~~~~~~~~~~ + +The choice of the name Jami was inspired by the Swahili word `jamii` +which means `community` as a noun and `together` as an adverb. It was +chosen as it reflects the vision for the project: a free/libre program +available to all that helps bring communities together, is community +supported, and respects the freedom and privacy of the users. + +How can I make a bug report? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Please see the :doc:`../guides/how-to-report-bugs` guide. + +What makes Jami different from other communication platforms? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Jami doesn't work like most communication platforms because it is +*distributed*: + +.. image:: ../media/distributed-network-topo.png + +Some of the consequences may seem surprising. For instance, since +accounts are stored on your device, passwords are optional. However, +the most significant practical differences are that you have more +*freedom* and *privacy*. + +TODO: expand on this + +What do the red/green status circles next to avatars mean? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On your own account, a red circle means that you aren't connected to +the DHT. You may need to check your connection or restart the app. + +On other contacts, a red circle means that they are not online, and a +green circle means they are online and you should be able to message +them. + +Note that a green circle only means that the contact has announced +their presence on the DHT. It does not indicate a direct connection +to their device. In some cases, a contact may be able to send and +receive messages but cannot make calls or file transfers because of +their firewall. + +Why is a feature missing on my client? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Not every client implements all features; check the list :doc:`here +<all-features-by-client>` to see if your client is missing the +feature. + +You can make feature requests at https://git.jami.net. + +Does Jami support read receipts? Can I turn them on or off? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can enable or disable read receipts on Android. Other platforms +may still be working on this feature. Please see :doc:`All Features +by Client <all-features-by-client>` for the current status. + +Does Jami support typing notifications? Can I turn them on or off? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Most of the client support sending and receiving typing notifications. +You can enable/disable them in the general settings. + +Can I share my screen? +~~~~~~~~~~~~~~~~~~~~~~ + +Yes, on all platforms except for iOS. Search for a dedicated "Share +screen" button while you are in a video call. + + +Can I make group conference calls? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes. You can add Jami contacts to existing calls (audio or video) by +clicking the "Add participant" button. + +Does Jami have group chats? +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Not yet, but they are :ref:`coming soon <technical-overview:Swarms>`. + + +Why is my contact not seeing my avatar? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Due to technical limitation, avatars are only transfered to your +contacts during a voice or video call. This limitation will disappear +when :ref:`group chats <technical-overview:swarms>` are released. + +Why aren't my sent messages showing up on all linked devices? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All of your devices receive the same messages from your contacts, but +*sent* messages will not show up on all of your devices. + +The :ref:`swarm <technical-overview:swarms>` update will introduce +full conversation sync between linked devices for all conversations +(including one-on-one conversations). + +Can I message offline contacts? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Jami does not yet have offline/persistent messages because of its +distributed nature. + +Your messages can't be queued on a central server so both contacts +must be online to message each other. If you send a message to an +offline contact, Jami will save the message on your device and send it +to them when they come online. + +There are some possible future solutions to this issue, including +:ref:`swarms <technical-overview:swarms>`, which will allow users to +set up their own "server" node to receive messages for them. + +Where are the configuration files located? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Jami saves its configuration (account, certificates, history) at +different locations depending on the platform. + +- **GNU/Linux**: global configuration is under + ``~/.config/jami/dring.yml``, and account-specific files are under + ``~/.local/share/jami/``. Finally, there is a cache directory at + ``~/.cache/jami/``. + +- **macOS**: the full configuration is under + ``~/Library/Application Support/Jami/`` if installed via + https://jami.net. The app store version uses + ``~/Library/Containers/com.savoirfairelinux.ring.macos/Data/Library/Application Support/jami/``. + +- **Android**: the full configuration is under ``/data/data/cx.ring/`` + (may require root privileges to view or change from outside Jami). + +- **Windows**: global configuration is under + ``%AppData%/Local/jami/dring.yml``, and account-specific files are + under ``%AppData%/Local/jami/``. Finally, there is a cache + directory at ``%USERPROFILE%/.cache/jami/``. + +Note: audio and video messages are recorded in the local-data in the +folder: ``sent_data`` + +TODO: check this ^^^ and add note about file downloads (like images) + +How much bandwidth do I need for calls? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For audio calls, Jami uses about 100 Kbps. For a video call, you need +about 2 Mbit/s for medium quality. If your connection is slower, the +bitrate will be automatically reduced. + +If you are hosting a video conference, you will approximately need an +additional 2 Mbps per participant. So, for example for a conference +with 10 participants, each participant will need 2 Mbps up & down and +the host will need 20 Mbps up and down. + +Auto-adaptation is done between a minimum of 200 Kbit/s and maximum of +6 Mbit/s. + +TODO: ^^^^^^^^^^^^^ What does this last line mean? + +TODO: How can SFL afford to give Jami away for free? How does/will SFL make money off Jami? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Summary: ethical company, they will make money supporting managed Jami +solutions for organizations; their main source of income is elsewhere; +all Jami code is GPLv3+; etc. etc. + + +Account management +------------------ + +What is a Jami account? +~~~~~~~~~~~~~~~~~~~~~~~ + +A Jami account is an `asymmetric encryption key +<https://en.wikipedia.org/wiki/Public-key_cryptography>`_. +Your account is identified by a Jami ID, which is a `fingerprint +<https://en.wikipedia.org/wiki/Public_key_fingerprint>`_ of your +public key. + +What information do I need to provide to create a Jami account? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you create a new Jami account, you don't have to provide any +private information like an email, address, or phone number. + +This is the information you can provide if you choose (it's all +optional): + +1. An avatar. +2. A display name, which is the name that clients will display for + your contact. It can contain special characters. +3. An optional username, which is a unique identifier that is directly + associated with your Jami ID. This username->Jami ID mapping is + stored on a server (``ns.jami.net`` by default, but you can host + your own). +4. A password. This password is used to protect the account archive + in your device. + +More information about Jami accounts is available in the +:ref:`Technical Overview <technical-overview:jami account>`. + +Where is my Jami ID? +~~~~~~~~~~~~~~~~~~~~ + +Your Jami ID should be displayed prominently in whichever app you're +using. It looks like a long string of letters and numbers; for +example: ``f2c815f5554bcc22689ce84d45aefdda1bce9146``. + +Why don't I have to use a password? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You are not forced to have a password on your account. On a +centralized system you would use your password to authenticate with a +public server where your account is stored. Someone who knows your +password could steal your identity. + +With Jami, your account is stored in a :ref:`folder <general/faq:Where +are the configuration files located?>` on your device. **The password +is only used to encrypt your account in order to protect you from +someone who has physical access to your device.** + +If your device is encrypted, you may not want or need to use a +password, and indeed recent versions of Jami don't ask for an account +encryption password by default when creating new accounts. + +Why don't I have to register a username? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The most permanent, secure identifier is your :ref:`Jami ID +<general/faq:Where is my Jami ID?>`, but since these are difficult to +use for some people, you also have the option of registering a +username. Username registration requires a name server, such as +Jami's default one at ``ns.jami.net``. + +If you don't register a username, you can still choose to register one +later at any time. + +Can I change my username? +~~~~~~~~~~~~~~~~~~~~~~~~~ + +With the default nameserver (``ns.jami.net``) you cannot change your +username. + +What is the difference between a username and a display name? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use your username as an identifier. The username points to +your :ref:`Jami ID <general/faq:Where is my Jami ID?>`, which is your +permanent, secure identifier. Two people cannot have the same +username. + +A display name allows you to choose another name that identifies you +to your contacts. Display names can be edited or changed at any time +and only your contacts can see them. + +How can I back up my account? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are two ways to back up your account: + +1. Link another device to your account so your account will be on two + devices. You can find this option in the account settings page. +2. Back up the :ref:`account archive <technical-overview:Account + storage and backup>`. This file can be found in the account files + :ref:`folder <general/faq:Where are the configuration files + located?>`. In some clients, you can export this archive from the + account settings. + +Can I retrieve my username without my keys? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you used the default name server at ``ns.jami.net``, **you can't**. +There is no way to prove it's your username without your key. + +If you use a different name server, there may be a way to move a +username to a new Jami ID at the discretion of the administrator of +that name server. + +For more information about name servers, see :ref:`the Technical +Overview <technical-overview:Name servers and ns.jami.net>`. + +Can I recover my account if I forget my password? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +No. There can't be a traditional account recovery process; you are +the only person with access to your data. If you are worried about +forgetting your password, please use a password manager. + +What happens when I delete my account? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Your account is only stored on your own devices. If you delete your +account from each device, the account is gone and you cannot get it +back (unless you already made a backup of it earlier). Nobody else +can use your account after that. + +Your contacts will still have the messages you sent them, but all +public record of your account on the DHT will eventually disappear +due to absence and lack of activity. + +.. warning:: The default ``ns.jami.net`` name server **does not** + delete any registered usernames -- other name servers might (not + recommended), at their administrator's discretion. So, if you have + an account with a username registered on the default name server + and you delete or lose your account, and did not back up your + account earlier, nobody (including you) will be able to register a + new account with that username again, thus nobody can reach you at + that username anymore. + + To avoid losing your account **please** :ref:`back it up + <general/faq:How can I back up my account?>`! + +What happens when I link a new device? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you link a device to your account, your :ref:`account archive +<technical-overview:account storage and backup>` is put on the Jami +network for a few minutes. It is protected by a password Jami gives +you. + +The new device receives your full account certificate with the master +RSA keys, but it generates a new device key for signing/encrypting +messages. + + +Advanced +-------- + +What protocol does Jami use for the end-to-end encryption? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We use TLS 1.3 with a perfect forward secrecy requirement for the +negotiated ciphers for calls and file transfers. Messages are +encrypted with an RSA key. + + +What data passes through my machine when I participate in the Jami network? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**All these data are encrypted**. There is: + +- ICE descriptors of other Jami users (ICE is a protocol that helps + establishing communication between two computers); +- certain text messages; and +- accounts currently being linked to a new device, as explained above. + +Audio/video streams and some text messages pass through the VOIP +protocol. Text messages can be sent either via VOIP or DHT (the +distributed network) depending on whether a VOIP communication channel +is already open or not. + +Why am I able to communicate with myself? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Many users use Jami to transfer data from one machine to another. + +Should I enable push notifications? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Push notifications allow Jami to operate in a way more adapted to the +context of mobility (energy consumption, data, ...). However, for the +moment, notifications go through Google's servers, via the Firebase +service. Only one identifier is transferred and it is unusable for +anyone who does not have access to your account. + +What is a bootstrap server? +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +TODO + +What is a TURN server? What is STUN? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +TODO + +What is DHT proxy? +~~~~~~~~~~~~~~~~~~ + +The DHT proxy is a server that registers on the DHT for you and relays +your information to you. Thus, it is the server that will be active +on the DHT and will participate in the network, and no longer the +target device. Multiple devices can register on the same DHT proxy. + +How does the username registration service work? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With the default name server (``ns.jami.net``), the usernames are +registered on an Ethereum blockchain. If you are a developer, you can +build your own name server with the underlying data storage technology +of your choice (e.g. you could use a SQL database rather than using a +blockchain). + +With the default name server, you can look up usernames at +``https://ns.jami.net/name/test``, where ``test`` is a username +for which we are looking for a matching :doc:`Infohash +<../guidelines/Identifiers>`. Once registered, this name server +**does not** provide any way to remove the mapping. + +Read more about the Jami :doc:`../technical/Name-Server-Protocol`. + +How can I change the timeout for a call? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the ``dring.yml`` file (see :ref:`general/faq:Where are the +configuration files located?`), you can change the ``ringingTimeout`` +(in seconds). + +How to back up and reimport conversations and accounts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: This is only for clients based on LRC (desktop ones). + +First you will need to export all your accounts (For GNU/Linux: +``Settings`` => ``Account`` => ``Export account``). Then you will +need to copy the database (in ``~/.local/share/jami/`` for example). + +Then on the new device, when you will open Jami for the first time, you +have to re-import your accounts via the archive previously saved. This +will re-import your settings and contacts (with empty conversations). +Then close the client and replace the database with the one previously +saved. That's all! + +How secure are you? +~~~~~~~~~~~~~~~~~~~ + +**We use TLS/SRTP to secure connection and communications over the +network.** + +We implement SRTP over SIP using recommendations described in the +following two RFCs: + +- `RFC 3711 <https://tools.ietf.org/html/rfc3711>`_ +- `RFC 4568 <https://tools.ietf.org/html/rfc4568>`_ + +Typically 2 kinds of sockets are negotiated. One for the control +socket, the other for the media sockets. + +Typical control session will use the following cipher suite:: + + (TLS1.3)-(ECDHE-SECP384R1)-(RSA-PSS-RSAE-SHA384)-(AES-256-GCM) + (TLS_ECDHE_RSA_AES_256_GCM_SHA384) + +DTLS (fallback) supported:: + + "SECURE192:-KX-ALL:+ANON-ECDH:+ANON-DH:+SECURE192:-VERS-TLS-ALL:+VERS-DTLS-ALL:-RSA:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION" + +TLS:: + + "SECURE192:-KX-ALL:+ANON-ECDH:+ANON-DH:+SECURE192:-RSA:-GROUP-FFDHE4096:-GROUP-FFDHE6144:-GROUP-FFDHE8192:+GROUP-X25519:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION" + +Supported crypto suite for the media session are: + +- ``AES_CM_128_HMAC_SHA1_80 / SRTP_AES128_CM_HMAC_SHA1_80`` +- ``AES_CM_128_HMAC_SHA1_32 / SRTP_AES128_CM_HMAC_SHA1_32`` + +When do public IPs get exposed? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We can consider three main connectivity scenarios: (1) a classic +configuration, (2) behind a VPN, (3) via Tor. As Jami is a p2p +application, the reader would probably know that (2) or (3) is a bit +mandatory to avoid IP leaking. + +Moreover, even if it's my answer, you can choose to not trust my +answer and check the code, or use wireshark or other tools. +Generally, I (and as far as I know most other Jami developers) use the +first scenario (sometimes the second one), and we surely can't test +all the possible networks configurations we would like to, so if you +discover a bug, please :doc:`open an issue +<../guides/how-to-report-bugs>`. + +Anyway, in these 3 scenarios, there are 3 main actions: + +- sending a message (this will use the DHT); +- sending a file (TCP ICE connection as described here: + https://git.jami.net/savoirfairelinux/jami-project/wikis/technical/2.5.%20File%20transfer); + and +- placing a call (TCP + UDP ICE connection as described here: + https://git.jami.net/savoirfairelinux/jami-project/wikis/technical/2.4.%20Let’s%20do%20a%20call). + +Classic config +^^^^^^^^^^^^^^ + +- Send a message + +The Jami application is running a DHT (https://opendht.net) node on your +device. So every operations on the DHT will use your ips. This is why +Jami has the option to use a dhtproxy (eg dhtproxy.jami.net), this will +avoid to use your node, but will use another node on the network (which +will see your ip). Note that your message is not sent directly to the +other device. In fact your message is sent on some nodes of the DHT and +your contact will retrieve the message on this node. So, your contact +don't see your IP at this step, but the node who get the message will +(or they will see the IP of the proxy). + +- Send a file + +As described in the docs, you will send a message with all the IP you +know that your peer can contact in an encrypted packet. So, if your peer +send you a file or you send a file, your addresses will appear in the +ICE message. + +- Calls + +Same as above, the IP is present in the ICE. + +Behind a VPN +^^^^^^^^^^^^ + +- Send a message + +The IP of your VPN will be used by the DHT node. If you want a proof, +you can compile dhtnode and run the ``la`` command to get your public +detected address. This is what I got: + +:: + + ./tools/dhtnode -b bootstrap.jami.net + Bootstrap: bootstrap.jami.net:4222 + OpenDHT node be58fdc9f782269bfc0bbfc21a60bca5f02cb881 running on port 54299 + (type 'h' or 'help' for a list of possible commands) + + >> la + Reported public addresses: + IPs OF MY VPN + +So, if you don't use a proxy, your VPN addresses will be used for using +the DHT. If you use a dhtproxy, the dhtproxy will see your VPN addresses + +- Send a file + +Same as above, the ICE will contains: + addresses from your LAN + public +address of your VPN + TURN address if TURN is enabled + +- Do a call + +Same as above, your public address is replaced by your VPN +address. You can see it in the logs from daemon. +See :ref:`guides/how-to-report-bugs:logs`. + +Tor +^^^ + +- Send a message + +Tor basically doesn't supports UDP. This means that you can't use your +DHT node locally, you MUST use a DHTProxy. That proxy will see the Exit +node. + +- Send a file + +I prefer a proof that any description. So, I did a file transfer with +Jami + TOR. This is what I see in the logs for the remote: + +:: + + [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a8c801 1 TCP 2130706431 192.168.200.1 33293 typ host tcptype passive + [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a8c801 1 TCP 2130706431 192.168.200.1 9 typ host tcptype active + [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a80103 1 TCP 2130706431 192.168.1.3 33293 typ host tcptype passive + [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a80103 1 TCP 2130706431 192.168.1.3 9 typ host tcptype active + [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: R33fe279d 1 TCP 16777215 51.254.39.157 27427 typ relay tcptype passive + [1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Sc0a8c801 1 TCP 1694498815 185.220.101.24 33293 typ srflx tcptype passive + +The first ones are some 192.168.x.x so we don't care. 51.254.39.157 is +the TURN address in France (my device is in the Canada). 185.220.101.24 +is the Tor exit node: + +:: + + inetnum: 185.220.101.0 - 185.220.101.127 + netname: MK-TOR-EXIT + +- Do a call + +This will not work (actually, you can create the SIP control connection +because it's a TCP connection), but medias are negotiated in UDP, so +this will fail. + +What ports does Jami use? +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Jami works as a server and gets new ports for each connections (randomly +bound). These are the ranges that can be used for each component: + +- dht: UDP [4000, 8888] +- audio: UDP [16384-32766] +- video: UDP [49152-65534] +- SIP Control: UDP/TCP randomly bound + +Note: if UDP is blocked, a dhtproxy can be used to use TCP instead. +Note that medias will not work cause it only supports UDP. + +So for ufw, we recommend running ``sudo ufw default allow outgoing``. + +For now, you can't specify a specific range to configure ports used by +Jami. The inbound traffic can be controlled without issue, Jami should +work and can use a TURN server if needed. + +If you run your own proxy or nameserver: + +- dhtproxy, nameserver: TCP [80-100], 443 + +If you run your own TURN server: + +- TURN/STUN: TCP+UDP 3478, 5349 + +How can I configure the codecs even more? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Codecs can be configured via a file. In the configurations files, you +can create a file called ``encoder.json`` like this: + +:: + + { + "libx264": { + "profile": 100, + "level": 42, + "crf": 20, + "preset": "ultrafast" + }, + "h264_vaapi": { + "low_power": 1 + }, + "libopus": { + "application": "voip" + } + } + +or: + +:: + + { + "libopus": { + "bit_rate": 128000 + } + } + +This file is :ref:`located in the same directory <general/faq:Where +are the configuration files located?>` as ``dring.yml``. + +To check which options are supported, use the command ``ffmpeg -h +encoder=[encoder_name]``, where ``encoder_name`` can be any of +``libx264``, ``libvpx``, ``mpeg4``, ``h263``, ``libopus``, +``libspeex``, ``g722``, ``pcm_alaw``, or ``pcm_mulaw`` (the FFmpeg +names for all of Jami's supported encoders). diff --git a/general/index.rst b/general/index.rst index 67e480b550b3d0d0bebc5fbcd8ef08ca7b86abf3..42c5ee7db8616d2cacf343bb1026a120386bb300 100644 --- a/general/index.rst +++ b/general/index.rst @@ -9,3 +9,4 @@ questions. :maxdepth: 1 introduction + faq diff --git a/tutorials/Frequently-Asked-Questions.md b/tutorials/Frequently-Asked-Questions.md deleted file mode 100644 index 823c813d8497932325b30c05acdb95c85293013a..0000000000000000000000000000000000000000 --- a/tutorials/Frequently-Asked-Questions.md +++ /dev/null @@ -1,442 +0,0 @@ -# Jami FAQ - -## Basics - -- [What is Jami?](#basics-1) -- [It misses a feature!](#basics-2) -- [Jami just crashed / have a bug. What can I do?](#basics-3) -- [There's a orange / red exclamation side by my avatar. What does it mean?](#basics-4) -- [Where are the configuration files located](#basics-5) - -## Account management - -- [What is a Jami account?](#account-1) -- [No password?](#account-2) -- [No usernames?](#account-3) -- [How can I back-up my account?](#account-4) -- [How can I retrieve my username without my keys?](#account-5) -- [I forgot my password, what can I do?](#account-6) -- [What is the PIN when I want to link my account to another device](#account-7) -- [How to delete my account?](#account-8) -- [What happens when I bind my account to a new device?](#account-9) -- [My contact is not seeing my avatar](#account-10) - -## Audio / video - -- [How to configure echo cancellation?](#media-1) -- [Video is laggy](#media-2) -- [I can't see myself](#media-3) -- [Others can't ear me](#media-4) -- [I have no sound](#media-5) -- [How much bandwidth do I need?](#media-6) - -## Advanced - -- [What data passes through my machine when I participate in the Jami network?](#advanced-1) -- [Why am I able to communicate with myself?](#advanced-2) -- [Should I enable push notifications?](#advanced-3) -- [What is DHT proxy?](#advanced-4) -- [How the username registration service work?](#advanced-5) -- [How can I change the timeout for a call?](#advanced-6) -- [How to back up and reimport conversations and accounts](#advanced-7) -- [How secure are you?](#advanced-8) -- [When do public IPs get exposed?](#advanced-9) -- [What ports does Jami use?](#advanced-10) -- [How can I configure the codecs even more?](#advanced-11) - -This page aims to gather as many resources as possible (technical or not) and -condense them to create concise documentation. Then, this can then be -integrated into a tutorial or a help page on the website or in the clients. - -Resources : - -- From ring.cx (legacy): - - <https://web.archive.org/web/20181226012503/https://ring.cx/en/documentation/faq> - - <https://web.archive.org/web/20181226012541/https://ring.cx/en/about/privacy-and-anonymity> - - <https://web.archive.org/web/20180224163130/https://ring.cx/en/about/practical> -- Old wiki: <https://tuleap.ring.cx/plugins/mediawiki/wiki/ring/index.php?title=Special:AllPages> - -## Basics - -### <a name="basics-1">What is Jami?</a> - -Jami is an innovative communication system. It doesn't work like other solutions since its designed to protect user's freedom. - -The Jami network is [distributed](https://git.jami.net/savoirfairelinux/ring-project/uploads/9b725e440c2705a2a3c4d0a3df092066/Network-topo.png), hence, you may be invited to perform some actions that are considered bad practices on centralized or decentralized systems, but that are totally acceptable with Jami. - -- Jami is fundamentally different from other communication tools -- Jami protects the privacy of its users -- A Jami account is stored on the device, it must be saved - -### <a name="basics-2">It misses a feature!</a> - -Not all features are implemented in all clients yet. -Check list at: <https://git.jami.net/savoirfairelinux/ring-project/wikis/features/All-features-by-client> -Contributions to this document are greatly appreciated! - -If you can't wait to have this feature, you can try another client. - -### <a name="basics-3">Jami just crashed / have a bug. What can I do?</a> - -- A bug report. This is a very useful way to contribute to Jami. Please have a look at <https://git.jami.net/savoirfairelinux/ring-project/wikis/tutorials/Bug-report-guide> and <https://git.jami.net/savoirfairelinux/ring-project/wikis/tutorials/Reporting-bugs>. -- If you can, try another client - -### <a name="basics-4">There's a orange / red exclamation side by my avatar. What does it mean?</a> - -It's because your account is not connected to the DHT. Verify your internet connection or try to relaunch the application. If you use the push notifications, try to disable this option (and re-enable it). - -### <a name="basics-5">Where are the configuration files located</a> - -Jami saves its configuration (account, certificates, history) at -different locations depending the platform. - -- **GNU/Linux**: global configuration is under - **\~/.config/jami/dring.yml** and Accounts files are under - **\~/.local/share/jami/**. Finally some cache can be stored in **~/.cache/jami** -- **OSX**: The full configuration is under **\~/Library/Application - Support/Jami** if installed via https://jami.net. Via the appstore it's **\~/Library/Containers/com.savoirfairelinux.ring.macos/Data/Library/Application Support/jami** -- **Android**: The full configuration is under **/data/data/cx.ring** - (may require root privileges) -- **Windows**: global configuration is under - **%AppData%/Local/jami/dring.yml** and Account files are under - **%AppData%/Local/jami/**. Finally, some caches are in **%USERPROFILE%/.cache/jami** - -Note: audio and video messages are recorded in the local-data in the folder: `sent_data` - -## Account management - -### <a name="account-1">What is a Jami account?</a> - -Jami is not like a lot of communication software. It's not based on any central server and your account is only stored on your device. When you want to use Jami with your account, you don't have to use a classical login/password authentification. - -When you create a new Jami account, you don't have to provide private informations like a mail or a phone number. But this is the informations you can provide (all optionals): - -1. An avatar -2. A display name, it's the name client will display on your contact entry with the avatar. It can contains special character. -3. A username, this is a unique identifier and can be the direct translation of your JamiID. This identifier is stored on a server (ns.jami.net by default). Cf <https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/Name-Server-Protocol> for more details on how you can use your own name server. -4. A password. This password is used to protect the account archive in your device. - -So, after this step, the client will generate an archive (protected by the password you gave). This archive will contains your account's keys. And a JamiID is now created (a 40 chars length string. Technically, this ID is the fingerprint of your public key. And that's it, you have a Jami account. - -### <a name="account-2">No password?</a> - -With Jami, you are not forced to have a password on your account. -Don't worry, it's a decentralized system, consequences are not the same than on other systems. - -With a centralized system, you use your password to authenticate on a public server. Someone who knows your password can usurp your identity. - -**With Jami, your account is stored in a [folder]((#basics-5)) on your device**. The password is only used to protect you from someone who have a physical access to your device by encrypting the account's archive (and don't let anyone access your private key) - -If your device is encrypted, you may not want/need to use a password. - -### <a name="account-3">No username?</a> - -For a while, Jami had no username management system. Instead, we had to use [Infohashs](guidelines/Identifiers). They are quite difficult to use for most people (ie : 3d1112ab2bb089370c0744a44bbbb0786418d40b). To mitigate the issue, we created a system that associate your [Infohashs](guidelines/Identifiers) to a username of your choice that will be much more easier to remember. We recommand you to create a username: Jami will be friendlier. - -The technology we used to associate a username to a [Infohashs](guidelines/Identifiers), Ethereum blockchain, is also [distributed](https://git.jami.net/savoirfairelinux/ring-project/uploads/9b725e440c2705a2a3c4d0a3df092066/Network-topo.png), but it doesn't allow to modify or delete the association between a username and a InfoHash. - -You can still create an account without a username if you wish. Please note that if you choose this option, it is still possible to register a username later. - -### <a name="account-4">How can I back-up my account?</a> - -There is two ways to back-up your account: - -1. Link another device to your account, so your account will be in two devices. You can find this option in the account's settings page. -2. Copy the account's archive on a USB flashdrive or any another place. This file can be found in the paths given in the previous question. In the linux client, you can export this archive from the client in the account's settings page. - -See [Configuration's path](#basics-5) - -The content of the `export.gz` is explained here: <https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/2.1.-Manage-Accounts#how-it-works-from-scratch> but it's basically a gunzipped Json (AES encrypted if a password is set) - -### <a name="account-5">How can I retrieve my username without my keys?</a> - -It depends. If you used `ns.jami.net`, you can't. There is no way to prove it's your username without your key (and there is no way to change your current username). -If it's another name server, it depends if it's possible to change the username linked. See this page for more details: <https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/Name-Server-Protocol> - -### <a name="account-6">I forgot my password, what can I do?</a> - -Nothing. Because we don't have access to your datas, we can't have an option like "I forget my password". You are the only one in charge of your datas, so take care. -If you are scared to forget a password, please use a password manager. - -### <a name="account-7">What is the PIN when I want to link my account to another device</a> - -When you choose to "link your device with another account", you have to enter the password of your account on your first device and a PIN. This PIN is generated by the first device, when you click on "Link this account to another device" (Generally in Settings -> Accounts -> Choose your account -> Link this account to another device), the account will be sent on the DHT during 5 minutes and a PIN is generated at this moment. This is the PIN you need to enter on the other device. - -### <a name="account-8">How to delete my account?</a> - -**Accounts without Infohash** - -A Jami account only exists on linked devices with this account. So, you only have to delete this account in app on all these devices and your account will not exists anymore. Or to uninstall Jami. -If you delete the account's archive, your account will no longer exists. If you uninstall Jami, your data will be deleted too. And nobody will be able to retrieve your account. Never ever. - -- GNU/Linux - -In the settings page, go to *Accounts*, choose your account and click on the **Delete** button in the GUI. Another way is to remove [configuration files](#basics-5) - -- Android - -In the hamburger menu, choose **Manage accounts**, choose the account to delete and click on the trash icon. - -**Note for accounts with a username** - -The technology that handle usernames is also distributed. So, it depends the nameservice you choose to make the translation between a nickname and your Jami ID. By default, a username is registered on `ns.jami.net` where you can't modify the Jami ID associated to this username. So, if you delete or if you lost your account you will not be able to retrieve this username, ever. Nobody will be able to recreate an account with the same username. - -NOTE: If your account has a username, this username will not be deleted. For example, if you use the username `pseudo` on the name server `ns.jami.net`, when you will delete your Jami account and you create a new account, you will not be able to retrieve this username, because `ns.jami.net` can't prove it's your username. - -If you do not want to lose your account, please back-up files related to this one. - -### <a name="account-9">What happens when I bind my account to a new device?</a> - -When you start the binding procedure, the folder containing your account information is simply put on the Jami network for a few minutes. It is protected by a password Jami gives you. - -### <a name="account-10">My contact is not seeing my avatar</a> - -Due to technical limitations of distributed technologies, avatars are only transfered to your contacts when a call (audio or video) is established. - -## Audio / video - -### <a name="media-1">How to configure echo cancellation?</a> - -Go to settings -> media -> and set change your audio manager. -We recommend using Pulse audio. - -### <a name="media-2">Video is laggy</a> - -Use a lower definition. Go to settings -> media -> and change resolution. -You can also try auto mode by clicking the HQ button during a call. - -### <a name="media-3">I can't see myself</a> - -End call and check that you have selected the right video device. -Go to settings -> media -> and change device. - -Check that you can effectively see yourself in the right panel of settings -> media. -You can double check that your device is working by installing the cheese application. - -### <a name="media-4">Others can't ear me</a> - -End call and try changing audio driver or audio input device. - -### <a name="media-5">I have no sound</a> - -End call and try changing audio driver or audio output device. - -### <a name="media-6">How much bandwidth do I need?</a> - -For audio calls, Jami uses about 100 Kbps. For a video call, you need about 2 Mbit/s for medium quality (if the link doesn't allow it, the bitrate will be automatically reduced). - -If you are hosting a video conference, you will need approximately 2 Mbps more per participant. So, for a conference with 10 participants, each participants will need 2Mbps up & down, except the host will need 20Mbps up and down. - -Auto-adaptation is done between 200Kbit/s / max:6Mbit/s - -## Advanced - -### <a name="advanced-1">What data passes through my machine when I participate in the Jami network?</a> - -**All these data are encrypted**. -There is: - -- ICE descriptors of other Jami users. ICE is a protocol that help establishing communication between two computers -- certain text messages -- as indicated above, accounts currently being linked to a new device - -Audio/video streams and some text messages pass through the VOIP protocol. -Text messages can be sent either via VOIP or DHT (the distributed network) depending on whether a VOIP communication channel is already open or not. - -### <a name="advanced-2">Why am I able to communicate with myself?</a> - -Many users use Jami to transfer data from one machine to another. - -### <a name="advanced-3">Should I enable push notifications?</a> - -Push notifications allow Jami to operate in a way more adapted to the context of mobility (energy consumption, data...). However, for the moment, notifications go through Google's servers, via the Firebase service. Only one identifier is transferred and it is unusable for anyone who does not have access to your account. - -### <a name="advanced-4">What is DHT proxy?</a> - -The DHT proxy is a server that registers on the DHT for you and relays your information to you. Thus, it is the server that will be active on the DHT and will participate in the network, and no longer the target device. Multiple devices can register on the same DHT proxy. - -### <a name="advanced-5">How the username registration service work?</a> - -For default parameters the usernames are registered on an Ethereum blockchain. By default, it's ns.jami.net that is used, but if you are a developper, you can create your own system. Hence, nothing forces you to implement it with a blockchain. You can check results at http://ns.jami.net/name/test, where "test" is a username for which we are looking for a matching [Infohashs](guidelines/Identifiers). Once registered, this server doesn't provide a way to remove the mapping. More informations there: https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/Name-Server-Protocol - -### <a name="advanced-6">How can I change the timeout for a call?</a> - -In the `dring.yml` file, you can change your ringingTimeout (in seconds) - -### <a name="advanced-7">How to back up and reimport conversations and accounts</a> - -Note: This is only for client based on LRC (desktop ones) - -First you will need to export all your accounts (For GNU/Linux: Settings => Account => Export account). Then you will need to copy the database (in `~/.local/share/jami` for example). - -Then on the new device, when you will open Jami for the first time, you have to re-import your accounts via the archive previously saved. This will re-import your settings and contacts (with empty conversations). Then close the client and replace the database with the one previously saved. That's all! - -### <a name="advanced-8">How secure are you?</a> - -** We use TLS/SRTP to secure connection and communications over the network.** - -We implement SRTP over SIP using recommendations written in following -RFCs: - -- [`http://tools.ietf.org/html/rfc3711`](http://tools.ietf.org/html/rfc3711) -- [`http://tools.ietf.org/html/rfc4568`](http://tools.ietf.org/html/rfc4568) - -Typically 2 kind of sockets are negotiated. One for the control socket, the other for the media sockets - -Typical control session will use the following cipher suite: -(TLS1.3)-(ECDHE-SECP384R1)-(RSA-PSS-RSAE-SHA384)-(AES-256-GCM) (TLS_ECDHE_RSA_AES_256_GCM_SHA384) - -DTLS (fallback) supported: "SECURE192:-KX-ALL:+ANON-ECDH:+ANON-DH:+SECURE192:-VERS-TLS-ALL:+VERS-DTLS-ALL:-RSA:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION" -TLS: "SECURE192:-KX-ALL:+ANON-ECDH:+ANON-DH:+SECURE192:-RSA:-GROUP-FFDHE4096:-GROUP-FFDHE6144:-GROUP-FFDHE8192:+GROUP-X25519:%SERVER_PRECEDENCE:%SAFE_RENEGOTIATION" - -Supported crypto suite for the media session are: - -- AES_CM_128_HMAC_SHA1_80 / SRTP_AES128_CM_HMAC_SHA1_80 -- AES_CM_128_HMAC_SHA1_32 / SRTP_AES128_CM_HMAC_SHA1_32 - -### <a name="advanced-9">When do public IPs get exposed?</a> - -We can describe 3 main connectivity scenarios. A classic configuration (1.), behind a VPN (2.), via Tor (3.). As Jami is a p2p app, I think you understand that (2.) or (3.) is a bit mandatory to avoid IP leaking. - -Moreover, even if it's my answer, you can choose to not trust my answer and check the code, or use wireshark or other tools. Generally, I (and the other devs I think) are using the first scenario (sometimes the second one), and we surely can't test all the network we want, so if you discover a bug, please open a issue. - -Anyway, in these 3 scenarios, there is 3 main actions: - -+ Send a message (this will use the DHT) -+ Send a file (TCP ICE connection as described here: https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/2.5.%20File%20transfer) -+ Do a call (TCP + UDP ICE connection as described here: https://git.jami.net/savoirfairelinux/ring-project/wikis/technical/2.4.%20Let's%20do%20a%20call) - -#### Classic config - -- Send a message - -The Jami application is running a DHT (https://opendht.net) node on your device. So every operations on the DHT will use your ips. This is why Jami has the option to use a dhtproxy (eg dhtproxy.jami.net), this will avoid to use your node, but will use another node on the network (which will see your ip). Note that your message is not sent directly to the other device. In fact your message is sent on some nodes of the DHT and your contact will retrieve the message on this node. So, your contact don't see your IP at this step, but the node who get the message will (or they will see the IP of the proxy). - -- Send a file - -As described in the docs, you will send a message with all the IP you know that your peer can contact in an encrypted packet. So, if your peer send you a file or you send a file, your addresses will appear in the ICE message. - -- Calls - -Same as above, the IP is present in the ICE. - -#### Behind a VPN - -- Send a message - -The IP of your VPN will be used by the DHT node. If you want a proof, you can compile dhtnode and run the 'la' command to get your public detected address. This is what I got: - -``` -./tools/dhtnode -b bootstrap.jami.net -Bootstrap: bootstrap.jami.net:4222 -OpenDHT node be58fdc9f782269bfc0bbfc21a60bca5f02cb881 running on port 54299 - (type 'h' or 'help' for a list of possible commands) - ->> la -Reported public addresses: -IPs OF MY VPN -``` - -So, if you don't use a proxy, your VPN addresses will be used for using the DHT. If you use a dhtproxy, the dhtproxy will see your VPN addresses - -- Send a file - -Same as above, the ICE will contains: -+ addresses from your LAN -+ public address of your VPN -+ TURN address if TURN is enabled - -- Do a call - -Same as above, your public address is replaced by your VPN address. You can see it in the logs from daemon. See https://git.jami.net/savoirfairelinux/ring-project/wikis/tutorials/Bug-report-guide#logs - -#### Tor - -- Send a message - -Tor basically doesn't supports UDP. This means that you can't use your DHT node locally, you MUST use a DHTProxy. That proxy will see the Exit node. - -- Send a file - -I prefer a proof that any description. So, I did a file transfer with Jami + TOR. This is what I see in the logs for the remote: - -``` -[1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a8c801 1 TCP 2130706431 192.168.200.1 33293 typ host tcptype passive -[1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a8c801 1 TCP 2130706431 192.168.200.1 9 typ host tcptype active -[1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a80103 1 TCP 2130706431 192.168.1.3 33293 typ host tcptype passive -[1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Hc0a80103 1 TCP 2130706431 192.168.1.3 9 typ host tcptype active -[1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: R33fe279d 1 TCP 16777215 51.254.39.157 27427 typ relay tcptype passive -[1574218330.556|10688|p2p.cpp :241 ] [Account:93a03f519f394143] add remote ICE candidate: Sc0a8c801 1 TCP 1694498815 185.220.101.24 33293 typ srflx tcptype passive -``` - -The first ones are some 192.168.x.x so we don't care. 51.254.39.157 is the TURN address in France (my device is in the Canada). 185.220.101.24 is the Tor exit node: - -``` -inetnum: 185.220.101.0 - 185.220.101.127 -netname: MK-TOR-EXIT -``` - -- Do a call - -This will not work (actually, you can create the SIP control connection because it's a TCP connection), but medias are negotiated in UDP, so this will fail. - - -### <a name="advanced-10">What ports does Jami use?</a> - -Jami works as a server and gets new ports for each connections (randomly binded). These are the ranges that can be used for each component: - -+ dht: UDP [4000, 8888] -+ audio: UDP [16384-32766] -+ video: UDP [49152-65534] -+ SIP Control: UDP/TCP randomly binded - -Note: if UDP is blocked, a dhtproxy can be used to use TCP instead. Note that medias will not work cause it only supports UDP. - -So for ufw, we recommend to run: -`sudo ufw default allow outgoing` - -For now, you can't specify a specific range to configure ports used by Jami. The inbound traffic can be controlled without issue, Jami should work and can use a TURN server if needed. - -If you run your own proxy or nameserver: - -+ dhtproxy, nameserver: TCP [80-100], 443 - -If you run your own TURN server: - -+ TURN/STUN: TCP+UDP 3478, 5349 - - -### <a name="advanced-11">How can I configure the codecs even more?</a> - -Codecs can be configured via a file. In the configurations files, you can create a file called `encoder.json` like this: - -``` -{ - "libx264": { - "profile": 100, - "level": 42, - "crf": 20, - "preset": "ultrafast" - }, - "h264_vaapi": { - "low_power": 1 - }, - "libopus": { - "application": "voip" - } -} -``` - -or: - -``` -{ - "libopus": { - "bit_rate": 128000 - } -} -``` - -This file is located in the same directory of [`dring.yml`](#basics-5) - -The best way to check which options are supported is through the command "ffmpeg -h encoder=\[encoder_name\]" where encoder_name can be whichever of libx264, libvpx, mpeg4, h263, libopus, libspeex, g722, pcm_alaw, pcm_mulaw (FFmpeg names for all of Jami's supported encoders). \ No newline at end of file