From 17a12baa2a48643f7c015c4b2dcbb67e31bbdfa8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Allan=20Nordh=C3=B8y?= Date: Sat, 8 Jul 2023 13:24:42 +0000 Subject: [PATCH] technical-documentation reworked --- docs/technical-documentation.md | 80 +++++++++++++++++++++++---------- 1 file changed, 56 insertions(+), 24 deletions(-) diff --git a/docs/technical-documentation.md b/docs/technical-documentation.md index bf050ae..b8783c0 100644 --- a/docs/technical-documentation.md +++ b/docs/technical-documentation.md @@ -3,48 +3,80 @@ Encryption is mandatory for WebRTC connections and completely done by the browser itself. -When the peers are first connecting, a channel is created by exchanging their signaling information. -This signaling information includes some sort of public key and is specific to the clients ip address. -That is what the STUN Server is used for: it simply returns your public IP address as you only know your local ip address +When the peers are first connecting, \ +a channel is created by exchanging their signaling info. \ +This signaling information includes some sort of public key \ +and is specific to the clients IP address. \ +That is what the STUN Server is used for: \ +it simply returns your public IP address \ +as you only know your local ip address \ if behind a NAT (router). -The transfer of the signaling information is done by the PairDrop / Snapdrop server using secure websockets. -After that the channel itself is completely peer-2-peer and all information can only be decrypted by the receiver. -When the two peers are on the same network or when they are not behind any NAT system (which they are always for classic -Snapdrop and for not paired users on PairDrop) the files are send directly peer to peer. +The transfer of the signaling info is done by the \ +PairDrop / Snapdrop server using secure websockets. \ +After that the channel itself is completely peer-to-peer \ +and all info can only be decrypted by the receiver. \ +When the two peers are on the same network \ +or when they are not behind any NAT system \ +(which they are always for classic \ +Snapdrop and for not paired users on PairDrop) \ +the files are send directly peer-to-peer. -When a user is behind a NAT (behind a router) the contents are channeled through a TURN server. -But again, the contents send via the channel can only be decrypted by the receiver. So a rogue TURN server could only -see that there is a connection, but not what is sent. Obviously, connections which are channeled through a TURN server -are not as fast as peer to peer. +When a user is behind a NAT (behind a router) \ +the contents are channeled through a TURN server. \ +But again, the contents send via the channel \ +can only be decrypted by the receiver. \ +So a rogue TURN server could only \ +see that there is a connection, but not what is sent. \ +Obviously, connections which are channeled through a TURN server \ +are not as fast as peer-to-peer. -The selection whether a TURN server is needed or not is also done automatically by the browser. -It simply iterated through the configured RTC iceServers and checks what works. Only if the STUN server is not sufficient, +The selection whether a TURN server is needed \ +or not is also done automatically by the web browser. \ +It simply iterated through the configured \ +RTC iceServers and checks what works. \ +Only if the STUN server is not sufficient, \ the TURN server is used. ![img](https://www.wowza.com/wp-content/uploads/WeRTC-Encryption-Diagrams-01.jpg) _Diagram created by wowza.com_ -Good thing: if your device has an IPv6 address it is uniquely reachable by that address. As I understand it, when both devices are using IPv6 addresses there is no need for a TURN server in any scenario. +Good thing: if your device has an IPv6 address \ +it is uniquely reachable by that address. \ +As I understand it, when both devices are using \ +IPv6 addresses there is no need for a TURN server in any scenario. -To learn more take a look at https://www.wowza.com/blog/webrtc-encryption-and-security which gives a good insight into stun, turn and webrtc +Learn more by reading https://www.wowza.com/blog/webrtc-encryption-and-security \ +which gives a good insight into STUN, TURN and WebRTC. ## Device Pairing The pairing functionality uses the [IndexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). -It works by creating long secrets that are served by the server to the initiating and requesting pair peer, -when the inserted key is correct. These long secrets are then saved to an indexedDB database in the browser. -IndexedDB is somewhat the successor of localStorage as saved data is shared between all tabs. -It goes one step further by making the data persistent and available offline if implemented to a PWA. +It works by creating long secrets that are served \ +by the server to the initiating and requesting pair peer, \ +when the inserted key is correct. \ +These long secrets are then saved to an \ +indexedDB database in the web browser. \ +IndexedDB is somewhat the successor of localStorage \ +as saved data is shared between all tabs. \ +It goes one step further by making the data persistent \ +and available offline if implemented to a PWA. -All secrets a client has saved to its database are send to the PairDrop server. Peers with a common secret are discoverable -to each other analog to peers with the same ip-address are discoverable to each other. +All secrets a client has saved to its database \ +are sent to the PairDrop server. \ +Peers with a common secret are discoverable \ +to each other analog to peers with the same \ +IP address are discoverable by each other. -What I really like about this approach, and the reason why I implemented it, is that devices on the same network are always -visible regardless whether any devices are paired or not. The main user flow is never obstructed. Paired devices are simply -shown additionally. This makes it in my idea better than the idea of using a room system as [discussed here](https://github.com/RobinLinus/snapdrop/pull/214). +What I really like about this approach (and the reason I implemented it) \ +is that devices on the same network are always \ +visible regardless whether any devices are paired or not. \ +The main user flow is never obstructed. \ +Paired devices are simply shown additionally. \ +This makes it in my idea better than the idea of \ +using a room system as [discussed here](https://github.com/RobinLinus/snapdrop/pull/214). [< Back](/README.md)