[gnunet-scheme] 04/05: doc: Begin drafting the CADET API.

[gnunet]

This is an automated email from the git hooks/post-receive script.

maxime-devos pushed a commit to branch master
in repository gnunet-scheme.

commit 4c59777ad10c838025a5811985ac1442d819f59f
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Mon Feb 7 12:49:12 2022 +0000

    doc: Begin drafting the CADET API.
    
    * doc/scheme-gnunet.tm (Communication between peers): New chapter.
    * doc/cadet.tm: New file.
---
 doc/cadet.tm         | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/scheme-gnunet.tm |   4 ++
 2 files changed, 119 insertions(+)

diff --git a/doc/cadet.tm b/doc/cadet.tm
new file mode 100644
index 0000000..ffd6a29
--- /dev/null
+++ b/doc/cadet.tm
@@ -0,0 +1,115 @@
+<TeXmacs|2.1>
+
+<project|scheme-gnunet.tm>
+
+<style|tmmanual>
+
+<\body>
+  Two arbitrary peers on GNUnet can communicate with the CADET<index|CADET>
+  service<\footnote>
+    With some restrictions: there must be a path between the nodes, in a
+    lossy and malicious network with few connections the connection will be
+    lossy, etc.
+  </footnote>. Before describing the API the software can use, some
+  background on CADET's capabilities is given.
+
+  <\warning>
+    To be implemented, this is a draft of the API!
+  </warning>
+
+  <section|Qualities and limitations \V avoiding reinventing the wheel>
+
+  <dfn|Channels><index|tunnel><\footnote>
+    They could have been called <em|connections>, but that means something
+    different in CADET.
+  </footnote> \U i.e., bidirectional communication channels between two peers
+  over CADET, are encrypted and authentication and hence are impractical to
+  eavesdrop on or be modified by an attacker<\footnote>
+    Assuming that the cryptography is not broken.
+  </footnote>. To aid reliability and performance, CADET aims to keep three
+  independent connections between the two peers so manually creating multiple
+  channels ought to be unnecessary.
+
+  The unit of information sent over a channel is a
+  <with|font-shape|italic|message> \U essentially, a bytevector. The software
+  can select multiple options: it can choose between <em|reliable> or
+  <em|unreliable>, <em|in-order> and <em|out-of-order> and <em|low-latency>
+  or <em|corked>, see <reference|mq-prio-prefs>.
+
+  <todo|ACKs for messages, opening, closing, window size>
+
+  <section|Addresses>
+
+  To contact a peer over CADET, the remote peer must have an <dfn|open
+  port><index|port> and the local peer needs to contact this port. The remote
+  peer\Uport identifier pair is called a <dfn|CADET address><index|CADET
+  address> in Scheme-GNUnet. A <dfn|CADET address> can be made with the
+  <scm|make-cadet-address> procedure:
+
+  <\explain>
+    <scm|(make-cadet-address <var|peer> <var|port>)>
+  <|explain>
+    Make a CADET address for the peer <var|peer> (a readable bytevector slice
+    containing a <scm|/peer-identity>) at the port <var|port> (a readable
+    bytevector slice containing a <scm|/hashcode:512>). The slices <var|peer>
+    and <var|port> are copied, so future changes to them do not have any
+    impact on the CADET address.
+
+    The predicate for CADET addresses is <scm|cadet-address?>. The peer and
+    port can be extracted with the accessors <scm|cadet-address-peer> and
+    <scm|cadet-address-port>.
+  </explain>
+
+  Guile has a generic interface for network addresses, see (guile)Network
+  Socket Address. If BSD socket integration is activated (see <todo|todo>),
+  this interface is extended to support CADET addresses. In particular,
+  <scm|sockaddr:fam> will return <scm|AF_CADET> (a symbol, also available as
+  the variable <scm|AF_CADET>) an <scm|sockaddr:addr> and <scm|sockaddr:port>
+  will return the peer and port respectively as a bytevector that should not
+  be modified<\footnote>
+    A copy is made to avoid letting buggy code mutate the CADET address, but
+    this is an implementation detail.
+  </footnote>.
+
+  <section|Listening at an address>
+
+  To listen at some address such that other peers can connect, the
+  <scm|open-port!> procedure is used.
+
+  <\explain>
+    (open-port! <var|server> <var|port> <var|connected> HANDLERS)
+  </explain|>
+
+  <section|Connecting to an address>
+
+  <section|Performing I/O \U GNUnet style>
+
+  <section|Performing I/O \U BSD style>
+
+  <scm|send>, <scm|recv!> (MSG_PEEK), getsockname \U\<gtr\> ???, getpeername
+  \U\<gtr\> ???, accept, listen, bind, shutdown
+
+  No reuseport
+
+  <section|BSD socket integration>
+
+  (AF_CADET, SOCK_RAW, 0) \U\<gtr\> GNUnet messages (with reliability
+  according to socket options).
+
+  (AF_CADET, SOCK_STREAM, 0) \U\<gtr\> TCP/CADET (VPN)
+
+  (AF_CADET, SOCK_DGRAM, 0) \U\<gtr\> UDP/CADET (VPN)
+
+  (AF_CADET, SOCK_SEQPACKET, 0) \U\<gtr\> UDP/CADET (VPN), in-order, reliable
+
+  (AF_CADET, SOCK_RDM, 0) \U\<gtr\> UDP/CADET (VPN), out-of-order, reliable
+
+  These sockets not dupable, don't have a fd.<todo|>
+</body>
+
+<\initial>
+  <\collection>
+    <associate|page-medium|paper>
+    <associate|save-aux|false>
+  </collection>
+</initial>
\ No newline at end of file
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 45b52bc..2f22bb3 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -248,6 +248,10 @@
 
   <include|distributed-hash-table.tm>
 
+  <chapter|Communication between peers>
+
+  <include|cadet.tm>
+
   <chapter|Cryptography>
 
   The module <scm|(gnu gnunet crypto)><index|(gnu gnunet crypto)> has a few

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.