technical-overview.txt (11241B)
1 Technical Overview 2 ================== 3 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>`__. 8 9 .. contents:: 10 :local: 11 :depth: 3 12 13 Before reading 14 ----------------- 15 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)>`__. 22 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. 26 27 Jami account 28 ----------------------- 29 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. 33 34 Jami uses the `GnuTLS <https://www.gnutls.org/>`__ library to generate 35 and manage RSA keys and certificates. 36 37 Account certificate 38 ~~~~~~~~~~~~~~~~~~~ 39 40 An account certificate is generated at account creation and represents 41 the identity of a Jami user. The certificate contains: 42 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 49 50 Device certificate 51 ~~~~~~~~~~~~~~~~~~ 52 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. 56 57 For more information about Jami certificates, see 58 `Certificates <certificates.html>`__. 59 60 The fingerprint of the device’s public key (analogous to a Jami Id) is 61 called the Device Id. 62 63 Account storage and backup 64 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 65 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. 73 74 Linking a device entails simply copying this file to another device over 75 the DHT. 76 77 The DHT 78 ------- 79 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. 88 89 For now, think of it as a *distributed* way to store key-value pairs on 90 the Jami network. 91 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``. 95 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. 98 99 DHT example: announcing and checking presence 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 101 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>)``. 106 107 Doing more with the DHT 108 ~~~~~~~~~~~~~~~~~~~~~~~ 109 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. 114 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. 119 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. 125 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. 129 130 Significance of the Jami Id 131 --------------------------- 132 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. 138 139 140 Calls and file transfers 141 ------------------------ 142 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. 146 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. 152 153 Connecting devices with ICE 154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 155 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. 159 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. 164 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. 171 172 Encrypting the connection with GnuTLS 173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 174 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). 179 180 The DTLS communication must be 181 `RFC6347 <https://tools.ietf.org/html/rfc6347>`__ compliant. 182 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 186 187 TODO: specify the exact suites recommended to support. 188 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. 193 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. 199 200 TODO: Someone please review the wording and correctness of this 201 section^^^^ 202 203 Swarms 204 ------ 205 206 Swarms are a new generation of group conversations. 207 208 `Here is the January 2021 announcement 209 <https://jami.net/swarm-introducing-a-new-generation-of-group-conversations/>`_ 210 about the feature. 211 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. 215 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. 220 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?>`. 225 226 Group conference calls 227 ---------------------- 228 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. 234 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. 240 241 TODO: this section needs better explanation 242 243 Optional servers 244 ---------------- 245 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. 249 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. 253 254 DHT proxy and push notifications 255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 256 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. 261 262 The purpose of this feature is to enable push notifications and reduce 263 energy consumption on mobile phones. 264 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. 268 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. 273 274 Message contents, recipients, and other metadata are never sent 275 through Google or Apple servers during this process, only wakeup 276 events. 277 278 For more information about this feature, see `OpenDHT's documentation 279 <https://github.com/savoirfairelinux/opendht/wiki/Push-notifications-support>`_. 280 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>`. 283 284 TURN and STUN 285 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 286 287 288 Name servers and ns.jami.net 289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 290 291 DHT bootstrap servers 292 -------------------------- 293 294 JAMS: Managed Jami networks for organizations 295 -------------------------------------------------