selfhosted
/
pairdrop
mirror of https://github.com/schlagmichdoch/PairDrop.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

technical-documentation reworked

This commit is contained in:
Allan Nordhøy 2023-07-08 13:24:42 +00:00 committed by GitHub
parent 913b60b712
commit 17a12baa2a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 56 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
docs/technical-documentation.md
View File

@ -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)