Forked version of Jami documentation, see wrycode.com/jami-docs-demo
git clone git://git.wrycode.com/wrycode/jami-docs.git
Log | Files | Refs

technical-overview.txt (11241B)

      1 Technical Overview
      2 ==================
      4 The goal of this page is to explain the Jami network clearly and
      5 concisely without going into details like implementation, libraries,
      6 and APIs. For more in-depth information, see the `Technical Reference
      7 <../technical/index.html>`__.
      9 .. contents::
     10    :local:
     11    :depth: 3
     13 Before reading
     14 -----------------
     16 Distributed systems have many moving parts. You may have to research
     17 some of these terms and draw your own diagrams. You should have a
     18 basic understanding of `public-key cryptography
     19 <https://en.wikipedia.org/wiki/Public-key_cryptography>`__ and
     20 computing concepts like `software libraries
     21 <https://en.wikipedia.org/wiki/Library_(computing)>`__.
     23 If you are still struggling to understand part of this document, please
     24 reach out to us and we can try to help you understand it or make
     25 improvements, if needed.
     27 Jami account
     28 -----------------------
     30 A Jami account is an x.509 certificate as defined by `RFC
     31 5280 <https://tools.ietf.org/html/rfc5280>`__ with a 4096-bit RSA key
     32 pair.
     34 Jami uses the `GnuTLS <https://www.gnutls.org/>`__ library to generate
     35 and manage RSA keys and certificates.
     37 Account certificate
     38 ~~~~~~~~~~~~~~~~~~~
     40 An account certificate is generated at account creation and represents
     41 the identity of a Jami user. The certificate contains:
     43 -  the public key
     44 -  its 160 bit fingerprint (the Jami Id, usually displayed as 40 hex digits)
     45 -  the fingerprint of the certificate issuer, which can be a certificate
     46    authority, but most likely is just same as the Jami ID, indicating a
     47    self-signature
     48 -  the signature: a signed hash of the certificate
     50 Device certificate
     51 ~~~~~~~~~~~~~~~~~~
     53 Each device has its own certificate. Device certificates look like
     54 account certificates except that instead of being self-signed they are
     55 signed by the RSA key associated with the account certificate.
     57 For more information about Jami certificates, see
     58 `Certificates <certificates.html>`__.
     60 The fingerprint of the device’s public key (analogous to a Jami Id) is
     61 called the Device Id.
     63 Account storage and backup
     64 ~~~~~~~~~~~~~~~~~~~~~~~~~~
     66 Jami serializes account data using JSON, including contacts, daemon
     67 settings, certificates, revoked devices, display name, and almost
     68 anything else besides message history. The file is compressed using Gzip
     69 and stored in the :ref:`account files
     70 folder <general/faq:Where are the configuration files located?>` as
     71 ``archive.gz``. If you use an account password, this file will also be
     72 encrypted.
     74 Linking a device entails simply copying this file to another device over
     75 the DHT.
     77 The DHT
     78 -------
     80 Jami uses a `distributed hash
     81 table <https://en.wikipedia.org/wiki/Distributed_hash_table>`__ library,
     82 `OpenDHT <https://github.com/savoirfairelinux/opendht>`__ (also led by
     83 Savoir-faire Linux), to find peers, connect new devices, and even
     84 temporarily store messages. Understanding how a DHT works is out of the
     85 scope of this overview, but if you want to learn more, `this blog
     86 post <https://enconn.fr/blog/p2p-internals-dht/>`__ is a good
     87 introduction.
     89 For now, think of it as a *distributed* way to store key-value pairs on
     90 the Jami network.
     92 You can think of the key ``k`` as a “location” on the DHT. ``put(k, v)``
     93 stores the value ``v`` on the DHT at location ``k``, while ``get(k)``
     94 gets the value(s) stored at ``k``.
     96 The key, in this case, is always a Jami Id or Device Id. Jami checks
     97 that values are signed by a device key belonging to the correct Jami ID.
     99 DHT example: announcing and checking presence
    100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    102 To announce your presence to the Jami network, simply
    103 ``put(<Jami ID>, <Device ID>)`` on the DHT. To check for the presence of
    104 your contacts, check the DHT for devices announced at the contact’s Jami
    105 ID: ``get(<Jami ID>)``.
    107 Doing more with the DHT
    108 ~~~~~~~~~~~~~~~~~~~~~~~
    110 It should be clear by now that the DHT is a useful data store that
    111 serves as an intermediary for peers. Clients exchange IP addresses,
    112 device and account certificates, text messages, device revocations, and
    113 more over the DHT.
    115 Once accounts have exchanged their certificates, they can encrypt and
    116 sign messages before storing them on the DHT. This means that your IP
    117 address and messages are always encrypted to a 4096-bit RSA key while
    118 on the public DHT.
    120 The OpenDHT library takes care of encrypting and signing values with
    121 your certificate. OpenDHT also handles certificate exchange with an
    122 “identity layer” for publishing certificates. See `OpenDHT’s
    123 documentation <https://github.com/savoirfairelinux/opendht/wiki>`__
    124 for more information.
    126 OpenDHT has other useful features, like the ability to “listen” on a DHT
    127 location (rather than polling every X seconds), but we will not cover
    128 all of them.
    130 Significance of the Jami Id
    131 ---------------------------
    133 Jami Ids are a fundamental way to “bootstrap” secure communication
    134 between two peers. As long as you have the correct Jami Id for your
    135 friend, nobody can impersonate them or read messages you’ve sent them.
    136 The Jami Id is used to verify certificates during the initial
    137 certificate exchange.
    140 Calls and file transfers
    141 ------------------------
    143 The DHT’s bandwidth and latency are not good enough for real-time
    144 communications (RTC) and file tranfers. For calls and file transfers, we
    145 must make direct (peer-to-peer) connections between devices.
    147 Once our devices are connected, Jami uses the IETF `SIP
    148 standard <https://tools.ietf.org/html/rfc3261>`__ to share files and
    149 stream audio and video with the `PJSIP <https://www.pjsip.org/>`__
    150 library. The hard part is establishing a connection, and then securing it. Jami
    151 does the former with ICE and the latter with GnuTLS.
    153 Connecting devices with ICE
    154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    156 We’ve seen that securely exchanging IP addresses over the DHT is easy,
    157 but how do we actually connect two devices? We need to navigate
    158 firewalls and other network conditions.
    160 `RFC 5245 <https://tools.ietf.org/html/rfc5245>`__ defines ICE
    161 (Interactive Connectivity Establishment), a protocol for NAT traversal.
    162 Jami uses ICE to establish a peer-to-peer communication between two
    163 devices.
    165 As a quick summary, each client gathers a list of potential IP:port
    166 addresses called **ICE candidates**. The peer initiating the call or
    167 tranfer stores these candidates on the DHT (encrypted to the recipient,
    168 of course). Once the recipient accepts the connection by storing their
    169 candidate list, the devices each build a list of **candidate pairs** and
    170 the devices negotiate a connection using rules specified by ICE.
    172 Encrypting the connection with GnuTLS
    173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    175 Once a peer-to-peer communication channel has been established, the
    176 recipient device listens on it for incoming DTLS connections (acting as
    177 a DTLS server) while the caller initiates an outgoing DTLS connection
    178 (acting as a DTLS client).
    180 The DTLS communication must be
    181 `RFC6347 <https://tools.ietf.org/html/rfc6347>`__ compliant.
    183 Peers must only support PFS (perfect forward secrecy) cypher suites. The
    184 set of supported cypher suites is implementation defined but should
    185 include at least ECDHE-AES-GCM
    187 TODO: specify the exact suites recommended to support.
    189 During the DTLS handshake, both peers must provide their respective
    190 device certificate chain and must authenticate the other peer. Jami
    191 checks that its public key is the same key used during the DHT ICE
    192 exchange.
    194 This connection is similar to the connection your browser makes with a
    195 web server (web browsers actually use DTLS for WebRTC). Jami uses GnuTLS
    196 instead of implementing its own crypto. This keeps connections
    197 up-to-date with the latest algorithms and security fixes, and helps us
    198 avoid the pitfalls of DIY crypto.
    200 TODO: Someone please review the wording and correctness of this
    201 section^^^^
    203 Swarms
    204 ------
    206 Swarms are a new generation of group conversations.
    208 `Here is the January 2021 announcement
    209 <https://jami.net/swarm-introducing-a-new-generation-of-group-conversations/>`_
    210 about the feature.
    212 The design is still changing frequently, so we will defer to the
    213 `Technical Reference <../technical/basic-features/swarm.html>`_ for a
    214 full explanation.
    216 However, as a quick summary: Swarms use `Git <https://git-scm.com/>`_
    217 to store and sync conversations between participants over a p2p
    218 connection. Each swarm is a single distributed Git repository, and
    219 each message is a commit.
    221 Participants include all linked devices, so swarms will bring
    222 much-requested full conversation sync between devices. This also fixes
    223 a few other things like :ref:`contacts not seeing avatars
    224 <general/faq:Why is my contact not seeing my avatar?>`.
    226 Group conference calls
    227 ----------------------
    229 Jami manages audio and video conferences between more than two
    230 participants by treating the host as an ad-hoc server. The meeting
    231 host receives video and audio feeds from every participant, remixes
    232 them into a single stream, and sends the final version back to every
    233 participant.
    235 At any time, a Jami account can be a **rendezvous point**, which
    236 allows people to call in and join the group conference whenever the
    237 account is online. It also adds the ability to set default moderators.
    238 This feature can be enabled and disabled in the account settings for
    239 any Jami account.
    241 TODO: this section needs better explanation
    243 Optional servers
    244 ----------------
    246 In most circumstances, all of the core features work without any sort
    247 of central server. However, there are some optional servers in the
    248 Jami ecosystem which help with things like reliability and efficiency.
    250 All of these servers are **completely optional**, they are Free/Libre
    251 software, and users may choose to host their own, change the default
    252 ones, or not use them at all.
    254 DHT proxy and push notifications
    255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    257 OpenDHT provides a HTTP API that allows users to indirectly talk with
    258 the DHT. This is called a DHT proxy because all ``get``, ``put``, and
    259 ``listen`` operations are relayed through the node instead of the rest
    260 of the DHT.
    262 The purpose of this feature is to enable push notifications and reduce
    263 energy consumption on mobile phones.
    265 Instead of leaving the Jami daemon to crawl and monitor the DHT in the
    266 background, devices can ask the DHT proxy to watch the DHT and notify
    267 them through the official iOS and Android push services when new values appear.
    269 A DHT proxy sends a wake up event through the device vendor's push
    270 provider when it notices new values at the subscribed DHT
    271 locations. Then the daemon on the iOS or Android device wakes up and
    272 downloads the values directly from the DHTproxy.
    274 Message contents, recipients, and other metadata are never sent
    275 through Google or Apple servers during this process, only wakeup
    276 events.
    278 For more information about this feature, see `OpenDHT's documentation
    279 <https://github.com/savoirfairelinux/opendht/wiki/Push-notifications-support>`_.
    281 If you want to host your own DHT proxy, see our :doc:`guide
    282 <../guides/how-to-set-up-a-dhtproxy-or-bootstrap-server>`.
    284 TURN and STUN
    285 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    288 Name servers and ns.jami.net
    289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    291 DHT bootstrap servers
    292 --------------------------
    294 JAMS: Managed Jami networks for organizations
    295 -------------------------------------------------