lokinet/doc/proto_v0.txt

LLARP v0

LLARP (Low Latency Anon Routing Protocol) is a protocol for anonymizing senders and
recipiants of encrypted messages sent over the internet without a centralied
trusted party.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].

basic structures:

all structures are key, value dictionaries encoded with bittorrent encoding
notation:

a + b is a concatanated with b

a ^ b is a bitwise XOR b

x[a:b] is a memory slice of x from index a to b

BE(x) is bittorrent encode x

BD(x) is bittorrent decode x

{ a: b, y: z } is a dictionary with two keys a and y
    who's values are b and z respectively

[ a, b, c ... ] is a list containing a b c and more items in that order

"<description>" is a bytestring who's contents and length is described by the
    quoted value <description>

"<value>" * N is a bytestring containing the <value> concatenated N times.

cryptography:

H(x) is 512 bit blake2b digest of x
MD(x, k) is 512 bit blake2b hmac of x with secret value k
NE(k, x) is sntrup4591761 encrypt data x to public key k
ND(k, x) is sntrup4591761 decrypt data x with private key k
SE(k, n, x) is chacha20 encrypt data x using symettric key k and nounce n
SD(k, n, x) is chacha20 dectypt data x using symettric key k and nounce n
S(k, x) is sign x with ed25519 using seed k
V(k, x, sig) is verify x data using signature sig using public key k
DH(x, y) is a ecdh key exchange using ed25519 scalarmult between public keys x
  and y
KE(x, y) is a ecdh key exchange using H(DH(x, y) + x)


---


wire protocol:

as of version 0 plaintext sctp is used, future versions will use an encrypted udp transport (IWP).



IWP inbound handshake:


IWP outbound handshake:



---

datastructures:

all datastructures are assumed version 0 if they lack a v value
otherwise version is provided by the v value

address info (AI)

An address info (AI) defines a publically reachable ipv6 endpoint

{
  c: transport_rank_uint16,
  e: "<32 bytes public encryption key>",
  d: "<transport dialect name>",
  i: "<16 bytes big endian public ipv6 address>",
  p: port_uint16
}

Exit Info (XI)

{
  a: "<16 bytes big endian ipv6 address>",
  b: "<16 bytes big endian ipv6 netmask>"
}

router contact (RC)

{
  a: [ one, or, many, AI, here ... ],
  k: "<32 bytes public sigining/encryption key>",
  x: [ Exit, Infos ],
  z: "<64 bytes signature using signing key>"
}

service info (SI)

{
  n: "<optional claimed name>",
  s: "<32 bytes public signing key>",
  x: "<optional nounce for vanity>"
}

service address (SA)

H(BE(SI))

introducer (I)

{
  i: "<32 bytes public key of router>",
  p: path_id_uint64,
  x: time_expires_seconds_since_epoch_uint64
}

introducer set (IS)

{
  a: "<64 bytes SA>",
  e: "<1218 bytes ntru public encryption key>",
  i: [ I, I, I, ... ],
  z: "<64 bytes signature using service info signing key>"
}


---

link layer messages:

the link layer is responsible for anonymising the source and destination of
routing layer messages.

any link layer message without a key v is assumed to be version 0 otherwise
indicates the protocol version in use.

link relay commit message (LRCM)


{
  a: "c",
  b: [ list, of, encrypted, RCR, as, bytes ],
}

relay commit record (RCR)

record requesting path with tunnel id p relay messages for x seconds to router
on network who's i is equal to RC.k and decrypt data any messages using
MD(n, KE(c, RC.k)) as symettric key for encryption and decryption.

{
  c: "<32 byte public signing/encryption key used for further communication>",
  i: "<32 byte RC.k of next hop>",
  n: "<32 bytes nounce for key exchange>",
  p: path_id_uint64,
  x: seconds_lifetime_uint64
}

if i is equal to RC.k then any LRDM.z values are decrypted and interpreted as
routing layer messages.

if i is not equal to RC.k then forward the LRCM with first element removed
and the last element holding our hop's reply. this ensures that the first entry
in the forwarded LRCM is for the next hop in the requested path.

if i is equal to RC.k unconditionally send a LRDM with encrypted payload
holding a LRSM with our record at the end and the previous ones in the front.

link relay reject record (LRRR)

sent in reply to a LRCM indicating we have rejected the request to relay data
for path with id p, the recipiant of this message MUST backoff sending LRCM for
b milliseconds or recipiant MAY get banned by recipiant router for an undefined
amount of time. r contains a bytestring of 7 bit clean ascii metadata indicating
why the commit was rejected. if included r MUST be logged or collected for later
review by node operator. inclusion of r is OPTIONAL. review of collected events
is RECOMMENDED.

{
  b: miliseconds_backoff_uint64,
  c: "r",
  p: path_id_uint64,
  r: "<optional reason metadata here>",
  x: "<N bytes arbirary padding>"
}

link relay accept record (LRAR)

sent in reply to a LRCM indicating we have accepted the request to relay data
for path with id p.

{
  c: "a",
  p: path_id_uint64,
  x: "<N bytes arbitrary padding>"
}


link relay status message (LRSM)

sent inside a LRDM after build has reached the end of the path to finish the
path build and send the result of the build.

{
  a: "s",
  p: [list, of, encrypted, replies]
}


link relay upstream message (LRUM)

sent to relay data via upstream direction of a previously created path.
decrypt z using previously derived key and nounce y. Relay with new_y and new_z
in upstream direction as a LRUM.

new_z = SD(k, y, z)
new_y = y ^ new_z[0:24]

{
  a: "u",
  p: path_id_uint64,
  y: "<insert 24 bytes nounce here>",
  z: "<insert N bytes payload here>"
}

link relay downstream message (LRDM)

sent to relay data via downstream direction of a previously created path.
encrypt z using previously derived key and nonce new_y and relay in downstream
direction as a LRDM.

new_y = y ^ z[0:24]
new_z = SE(k, new_y, z)

{
  a: "d",
  p: path_id_uint64,
  y: "<insert 24 bytes nounce here>",
  z: "<insert N bytes payload here>"
}

link relay exit message (LRXM)

sent to exit a previously commited path before it expires.
verify signature using cancel key c in relay commit message.

{
  a: "x",
  b: [ list, of, exit, records, as, bytes ]
}

link relay exit record (LRXR)

{
  c: "x",
  p: path_id_uint64,
  x: "<N bytes padding>",
  z: "<64 bytes signature>"
}

---

routing layer:

the routing layer provides inter network communication between the SARP link
layer and ip (internet protocol) for exit traffic or hp (hidden protocol) for
SARP hidden services. replies to messages are sent back via the path they
originated from inside a LRDM.

obtain exit address message (OXAM)

sent to an exit router to obtain a NAT ip address for ip exit traffic.
replies are sent down the path that messages originate from.

{
  A: "X",
  I: "<32 bytes signing public key for future communication>",
  X: lifetime_of_address_mapping_in_seconds_uint64,
}

grant exit address messsage (GXAM)

sent in response to a OXAM to grant an ip for exit traffic from an external
ip address used for exit traffic.

{
  A: "G",
  E: "<16 byte big endian externally reachable ipv6 address>",
  I: "<32 bytes signing public key of requester>",
  Z: "<64 bytes signature using exit's signing key>"
}

reject exit address message (RXAM)

{
  A: "R",
  B: backoff_milliseconds_uint64,
  I: "<32 bytes signing public key of requester>",
  R: "<optional reject metadata>",
  Z: "<64 bytes signature signed by exit>"
}



transfer data fragment message (TDFM)

variant 1 (with path id):

transfer data to another path with id P on the local router place Y and X values into
y and z values in LRDM message respectively.

{
  A: "T",
  P: path_id_uint64,
  X: "<N bytes payload>", 
  Y: "<24 bytes nounce>",
  Z: "<64 bytes signature of entire message where Z is set to NUL>",
}

variant 2 (no path id):

transfer ip traffic for exit

{
  A: "T",
  X: "<N bytes ipv6 packet>",
  Z: "<64 bytes signature of previously provided signing key>"
}

find introduction message (FIM)

{
  A: "F",
  S: "<64 bytes dht key>",
  T: transaction_id_uint64
}

got introduction message (GIM)

{
  A: "G",
  T: transaction_id_uint64,
  X: [ IS, IS, IS, ... ]
}

publish introduction message (PIM)

publish one or many IM into the dht at once.
each IS will be placed in the dht

version 0 uses the SA of each IS as the keyspace location.

in the future the location will be determined by the dht kdf
which uses a shared random source to obfuscate keyspace location.


{
  A: "P",
  T: transaction_id_uint64,
  X: [ IS, IS, IS, ... ]
}

acknoleged introduction message (AIM)

acknolege the publishing of a previous PIM, back off publishing for B ms.
nonzero B value indicates failure to publish.

{
  A: "A",
  B: backoff_milliseconds_uint64,
  P: number_of_IS_published_uint,
  T: transaction_id_uint64,
}

find router contact message (FRCM)

find a router by public key

{
  A: "F",
  R: "<32 byte public key of router>",
  T: transaction_id_uint64
}

got router contact message (GRCM)

{
  A: "G",
  R: [RC, RC, RC ...],
  T: transaction_id_uint64
}

store router contact message (SRCM)

{
  A: "S",
  R: RC
}