From 1343fcb0b91a9ae09c77ca43948123ccd87bb511 Mon Sep 17 00:00:00 2001 From: schlagmichdoch Date: Thu, 19 Jan 2023 19:24:09 +0100 Subject: [PATCH] add technical documentation --- docs/faq.md | 3 +++ docs/how-to.md | 1 + docs/technical-documentation.md | 47 +++++++++++++++++++++++++++++++++ 3 files changed, 51 insertions(+) create mode 100644 docs/technical-documentation.md diff --git a/docs/faq.md b/docs/faq.md index 98b39a3..00fc54a 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -43,4 +43,7 @@ If you want to learn more about simplicity you can read [Insanely Simple: The Ob * Do security analysis and suggestions +### How does it work? +[See here for Information about the Technical Implementation](/docs/technical-documentation.md) + [< Back](/README.md) diff --git a/docs/how-to.md b/docs/how-to.md index 1b367f3..932345e 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -1,3 +1,4 @@ +# How-To ## Share files directly form context menu on Windows ### Registering to open files with PairDrop The [File Handling API](https://learn.microsoft.com/en-us/microsoft-edge/progressive-web-apps-chromium/how-to/handle-files) is implemented diff --git a/docs/technical-documentation.md b/docs/technical-documentation.md new file mode 100644 index 0000000..199f2b1 --- /dev/null +++ b/docs/technical-documentation.md @@ -0,0 +1,47 @@ +# Technical Documentation +## Encryption, WebRTC, STUN and TURN + +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 +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. + +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 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. + +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 + + +## 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. + +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. + +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).