add README

README.md

@@ -0,0 +1,66 @@
+# Introduction
+``punchd`` (short for "hole punching daemon") provides TCP (and soon UDP) hole punching as a service to applications. This allows two applications on different hosts, both behind NAT and / or firewalls, to establish a direct communication channel. The motivation is to help peer-to-peer applications improve their connectivity.
+
+
+# How does it work?
+The idea is to try out a sequence of well known hole punching techniques until one of them succeeds. ``punchd`` implements the following techniques:
+
+- [SYNI](https://www.uni-kassel.de/eecs/fileadmin/datas/fb16/Fachgebiete/UC/papers/HWW_11-SYNI.pdf) (TCP hole punching based on SYN injection), DOI: 10.1109/NCA.2011.66
+- [NUTSS](https://www.cs.cornell.edu/people/francis/nutss-fdna.pdf) (TCP hole punching, the asymmetrical non-spoofing approach described in section 4.2.2 of the paper), DOI: 10.1145/1016707.1016715
+
+
+# How can I use punchd?
+Applications can communicate with ``punchd`` through a unix domain socket (by default ``/tmp/punchd.socket``). An application can call one of ``punchd``'s API functions to either start a hole punching attempt (``initiate``) or react to an attempt started by another peer (``respond``). After calling an API function ``punchd`` will report back a status (either ``ok``, ``progress`` or ``error``). After a successful hole punching attempt, ``punchd`` will pass a socket to the application which can be used immediately to communicate with the other peer. The full ``punchd`` API is described in section ``The punchd API``.
+
+The figure below shows the workflow of a successful hole punching attempt between two peers A (initiator) and B (responder).
+
+```shell
+                   +--------------------------+
+                   |  Rendezvous server (RS)  |
+                   +--------------------------+
+                        Λ                |
+                        |                4 
+                        3                |
+                        |                V
+ +----------------------------+    +----------------------------+
+ | Application at peer A (AA) |    | Application at peer B (AB) |
+ +----------------------------+    +----------------------------+
+            |  Λ  Λ                             |  Λ
+            1  |  |                             5  |
+            |  2  6                             |  7
+            V  |  |                             V  |
+ +-------------------------+          +-------------------------+
+ |  punchd at peer A (PA)  |          |  punchd at peer B (PB)  |
+ +-------------------------+          +-------------------------+
+``` 
+
+1. ``initiate``: ``AA`` asks ``PA`` to initiate the hole punching to ``AB``
+2. ``progress``: ``PA`` reports progress
+3. ``AA`` sends notification about the hole punching attempt to ``RS``
+4. ``RS`` forwards notification to ``AB``
+5. ``respond``: ``AB`` asks ``PB`` to respond to the hole punching attempt
+6. ``ok``: ``PA`` reports success and passes a connected socket to ``AA``
+7. ``ok``: ``PB`` reports success and passes a connected socket to ``AB``
+
+
+# Installation
+No packages exist yet, so installation has to be done manually to the desired location after running ``nimble install``. Starting punchd is as simple as
+
+```
+$ sudo ./punchd
+```
+
+
+# The punchd API
+TBD
+
+
+# FAQ
+- **Q: Why does ``punchd`` only offer a weird socket API and not REST?**
+  A: ``punchd`` needs to pass a file descriptor to the application. On Unix systems that is only possible using the ``sendmsg`` system call with an ancillary message of type ``SCM_RIGHTS`` on a unix domain socket. See the [unix(7) man page](https://linux.die.net/man/7/unix).
+
+- **Q: Why does ``punchd`` need root permissions?**
+  A: Most hole punching techniques require elevated privileges because they need raw sockets (e.g. for capturing TCP sequence numbers) or they need to create firewall rules (some techniques require sending out low-TTL packets; the resulting ICMP time-exceeded responses have to be filtered out or else TCP connections will fail). On linux punchd can run as a non-root user though if ``punchd`` is started with the ``CAP_NET_RAW`` and ``CAP_NET_ADMIN`` capabilities.
+
+- **Q: Which one is the best hole punching technique?**
+  A: No hole punching technique will work for all environments. In fact there are environments where no hole punching will be possible at all. The goal of this project is to find a good *sequence* of hole punching techniques to be tried one after the other. A lot of research still has to be done. See the example applications for some proposed sequences.