doc/proto.texi

   1 @node Protocol
   2 @unnumbered Protocol
   3
   4 VoRS uses the Opus codec with 20ms frames with 48kHz 1ch 16-bit S-LE
   5 sound. It uses native @code{libopus}'es Packet Loss Concealment (PLC)
   6 feature when the number of lost frame does not exceed 32 count. DTX
   7 (discontinuous transmission) is also on.
   8
   9 Each frame has a single byte stream identifier (unique identifier of the
  10 participant), 24-bit big-endian packet counter and 24-bit big-endian
  11 audio frame counter. Reordered packets are dropped. 24-bit counter is
  12 long enough for very long talk sessions. Audio frame counter is
  13 increased every 20ms data from microphone is read. When peer is muted,
  14 then no packets are sent, but audio frames are still counted. That gives
  15 ability to distinguish jitters and delays from lack of audio
  16 transmission.
  17
  18 Each packet is encrypted with ChaCha20 and authenticated with SipHash24.
  19 Their keys are generated from BLAKE2s-XOF, which is fed with completed
  20 handshake's binding value. Then they are shared among the other
  21 participants. The stream identifier together with the packet counter is
  22 used as a nonce.
  23
  24 It is tuned for 24Kbps bandwidth. But remember that it has additional 8B
  25 of MAC tag, 7B VoRS, 8B UDP and 40B IPv6 headers.
  26
  27 Each client handshakes with the server over TCP connection using the
  28 @url{http://noiseprotocol.org/, Noise}-NK protocol pattern with
  29 curve25519, ChaCha20-Poly1305 and BLAKE2s algorithms.
  30
  31 @itemize
  32
  33 @item Client sends @code{VoRS v3} to the socket. Just a magic number.
  34
  35 @item All next messages are @url{http://cr.yp.to/proto/netstrings.txt,
  36 Netstring} encoded strings. Most of them contain netstring encoded
  37 sequence of netstrings if multiple values are expected:
  38
  39 @example
  40 NS(NS(arg0) || NS(arg1) || ...)
  41 @end example
  42
  43 @item Client sends initial Noise handshake message with his username,
  44 room name and optional BLAKE2s-256 hash of the room's password (or an
  45 empty string) as a payload: @code{"USERNAME", "ROOM", BLAKE2s(PASSWORD)}.
  46
  47 @item Server answers with final noise handshake message with the
  48 @code{"COOKIE", COOKIE}, or @code{"ERR", MSG} failure message.
  49 It may reject a client if there are too many peers, its name is
  50 already taken or it provided an invalid room's password.
  51
  52 @item The 128-bit cookie is sent by client over UDP to the server every
  53 second. If UDP packets are lost, then no connection is possible and
  54 after a timeout the server drops the TCP connection. That cookie means:
  55
  56     @itemize
  57     @item confirmation of successful handshake on client side;
  58     @item UDP hole punching of stateful firewall or NAT;
  59     @item fact of client's UDP traffic ability to reach the server;
  60     @item client's UDP address knowledge (after passing NAT, its port
  61         may differ from known to client one)
  62     @end itemize
  63
  64 @item Server replies with @code{"SID", X}, where X is single byte
  65 stream number client must use.
  66
  67 @item @code{"PING"} and @code{"PONG"} messages are then sent every ten
  68 seconds as a heartbeat.
  69
  70 @end itemize
  71
  72 @example
  73 S <- C : e, es, NS(NS("USERNAME") || NS("ROOM") || NS("PASSWORD"))
  74 S -> C : e, ee, NS(NS("COOKIE") || NS(COOKIE))
  75 S <- C : UDP(COOKIE)
  76 S -> C : NS(NS("SID") || NS(X))
  77
  78 S <- C : NS(NS("PING"))
  79 S -> C : NS(NS("PONG"))
  80 S <> C : ...
  81
  82 S -> C : NS(NS("ADD") || NS(SID) || NS(USERNAME) || NS(KEY))
  83 S -> C : ...
  84
  85 S -> C : NS(NS("DEL") || NS(SID))
  86 S -> C : ...
  87 @end example
  88
  89 Every second the client sends UDP packet with his single-byte stream
  90 identifier, even if it's muted. That may help punching holes in stateful
  91 firewalls.
  92
  93 Clients are notified about new peers appearance with @code{ADD}
  94 commands, telling their SIDs, usernames and keys. @code{DEL} notifies
  95 about leaving peers. @code{MUTED}, @code{UNMUTED} notifies peer's mute
  96 toggling.