scheme-gnunet/doc/cadet.tm

<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>. CADET addresses can be compared with
    <scm|equal?>.
  </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|>

  <section|Constructing and analysing network messages>

  <todo|difference between channels and ports>

  <todo|acknowledgement>

  <todo|readable bytevector slices>

  <todo|verify against GNUnet documentation>

  <todo|analysis>

  <\explain>
    (construct-open-local-port <var|port>)<index|construct-open-local-port>
  </explain|Create a new <scm|/:msg:cadet:local:port:open><index|/:msg:cadet:local:port:open>
  message for instructing the service to open the port <var|port> at the
  local peer.>

  <\explain>
    (construct-close-local-port <var|port>)<index|construct-close-local-port>
  </explain|Crreate a new <scm|/:msg:cadet:local:port:close><index|/:msg:cadet:local:port:close>
  message for closing the port.>

  <\explain>
    (construct-local-data <var|client-channel-number> <var|priority>
    <var|data>)<index|construct-local-data>
  </explain|Construct a new <scm|/:msg:cadet:local:data><index|/:msg:cadet:local:data>
  message for sending <var|data> \ <todo|client\<less\>-\<gtr\>service>
  <todo|to/from> the channel with identifier <var|client-channel-number> at
  the priority specified by the numeric priority-preference value
  <var|priority>.>

  <\explain>
    <scm|(construct-local-acknowledgement
    <var|client-channel-number>)><index|construct-local-acknowledgement>
  </explain|Construct a new <scm|/:msg:cadet:local:acknowledgement><index|/:msg:cadet:local:acknowledgemeent>
  message for the channel with identifier <var|client-channel-number>, for
  informing the client that the service is ready for more data.>

  <\explain>
    <scm|(construct-local-channel-create <todo|arguments> <var|#:options>)>
  </explain|Construct a new <scm|msg:cadet:local:channel:create> message for
  <todo|which direction? client\<less\>-\<gtr\>service, reasonable options>>

  <\explain>
    (construct-destroy-local-channel <var|client-channel-number>)
  <|explain>
    Construct a new <scm|msg:cadet:local:channel:destroy> message to destroy
    the channel with identifier <var|client-channel-number>. This can be sent
    in two directions: from the client to the service, to close the channel,
    or from service to client, to inform the channel has been closed.

    <todo|Can the service send this without the client requesting this? If
    the client send this message, will the service send this message in
    return as an acknowledgment?>
  </explain>
</body>

<\initial>
  <\collection>
    <associate|page-medium|paper>
    <associate|save-aux|false>
  </collection>
</initial>