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:

see crypto_v0.txt

---

wire protocol

see iwp-v0.txt

---

datastructures:

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

all ip addresses can be ipv4 via hybrid dual stack ipv4 mapped ipv6 addresses,
i.e ::ffff.8.8.8.8. The underlying implementation MAY implement ipv4 as native
ipv4 instead of using a hybrid dual stack.

net address:

net addresses are a variable length byte string, if between 7 and 15 bytes it's
treated as a dot notation ipv4 address (xxx.xxx.xxx.xxx)
if it's exactly 16 bytes it's treated as a big endian encoding ipv6 address.

address info (AI)

An address info (AI) defines a publically reachable endpoint

{
  c: transport_rank_uint16,
  d: "<transport dialect name>",
  e: "<32 bytes public encryption key>",
  i: "<net address>",
  p: port_uint16,
  v: 0
}

example iwp address info:

{
  c: 1,
  d: "iwp",
  e: "<32 bytes of 0x61>",
  i: "123.123.123.123",
  p: 1234,
  v: 0
}

bencoded form:

d1:ci1e1:d3:iwp1:e32:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1:d3:iwp1:i15:123.123.123.1231:pi1234e1:vi0ee

Exit Info (XI)

An exit info (XI) defines a exit address that can relay exit traffic to the 
internet.

{
  a: "<net address exit address>",
  b: "<net address exit netmask>",
  k: "<32 bytes public encryption/signing key>",
  v: 0
}


Exit Route (XR)

An exit route (XR) define an allocated exit address and any additional
information required to access the internet via that exit address.

{
  a: "<16 bytes big endian ipv6 gateway address>",
  b: "<16 bytes big endian ipv6 netmask>",
  c: "<16 bytes big endian ipv6 source address>",
  l: lifetime_in_seconds_uint64,
  v: 0
}

router contact (RC)

router's full identity

{
  a: [ one, or, many, AI, here ... ],
  k: "<32 bytes public long term identity signing key>",
  p: "<32 bytes public path encryption key>",   
  u: last_updated_seconds_since_epoch_uint64,
  v: 0,
  x: [ Exit, Infos ],
  z: "<64 bytes signature using identity key>"
}

service info (SI)

public information blob for a hidden service

e is the long term public encryption key
s is the long term public signing key
v is the protocol version
x is a nounce value for generating vanity addresses that can be omitted

if x is included it MUST be less than or equal to 16 bytes, any larger and it is
considered invalid.

{
  e: "<32 bytes public encryption key>",
  s: "<32 bytes public signing key>",
  v: 0,
  x: "<optional nounce for vanity>"
}

service address (SA)

the "network address" of a hidden service, which is computed as the blake2b
256 bit hash of the public infomration blob.

HS(BE(SI))

introducer (I)

a descriptor annoucing a path to a hidden service

k is the rc.k value of the router to contact
p is the path id on the router that is owned by the service
v is the protocol version
x is the timestamp seconds since epoch that this introducer expires at

{
  k: "<32 bytes public identity key of router>",
  p: "<16 bytes path id>",
  v: 0,
  x: time_expires_seconds_since_epoch_uint64
}

introducer set (IS)

a signed set of introducers for a hidden service
a is the service info
i is the list of introducers that this service is advertising with
v is the protocol version
z is the signature of the entire IS where z is set to zero signed by the hidden
service's signing key.

{
  a: SI,
  i: [ I, I, I, ... ],
  v: 0,
  z: "<64 bytes signature using service info signing key>"
}


---

Encrypted frames:

{
  v: 0,
  w: "<32+32+32+N bytes payload>"
}

Encrypted frames are encrypted containers for link message records like LRCR.

32 bytes hmac, h
32 bytes nounce, n
32 bytes ephmeral sender's public encryption key, k
remaining bytes ciphertext, x

decryption:

0) verify hmac

S = PKE(n, k, our_RC.K)
verify h == MDS(n + k + x, S)

If the hmac verification fails the entire parent message is discarded

1) decrypt and decode

new_x = SD(S, n[0:24], x)
msg = BD(new_x)

If the decoding fails the entire parent message is discarded

encryption:

to encrypt a frame to a router with public key B.k

0) prepare nounce n, ephemeral keypair (A.k, s) and derive shared secret S

A.k, s = ECKG()
n = RAND(32)
S = PKE(p, A.k, B.k)

1) encode and encrypt

x = BE(msg)
new_x = SE(S, n[0:24], x)

2) generate hmac

h = MDS(n + A.k + new_x, S)

resulting frame is h + n + A.k + new_x


---

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 introduce message (LIM)

This message MUST be the first link message sent before any others. This message
identifies the sender as having the RC contained in r. The recipiant MUST
validate the RC's signature and ensure that the public key in use is listed in
the RC.a matching the ipv6 address it originated from.

if r is not present in sessions made by clients.

{
  a: "i",
  r: RC,
  v: 0
}

link relay commit message (LRCM)

request a commit to relay traffic to another node.

{
  a: "c",
  c: [ list, of, encrypted, frames ],
  f: encrypted data for last hop ,
  r: [ list, of, encrypted, acks ],
  v: 0
}

c and r MUST contain dummy records if the hop length is less than the maximum
hop length.


link relay commit record (LRCR)

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

additionally an ephemeral encryption keypair is made for the downstream
direction.

{
  c: "<32 byte public encryption key used for upstream>",
  i: "<32 byte RC.k of next hop>",
  n: "<32 bytes nounce for key exchange>",
  p: "<16 bytes tx path id>",
  s: "<32 bytes symmettric key for encrypting reply downstream public key>",
  u: "<24 bytes nonce for encrypting reply downstream public key>",
  v: 0,
  w: proof of work (optional),
}


if i is equal to RC.k then any LRDM.z values are decrypted and interpreted as
routing layer messages. This indicates that we are the farthest hop in the path.
if we are the farthest hop s and u MUST be present and discarded.

we decrypt the encrypted frame f, as encrypted to RC.e 

if i is not equal to RC.k then forward the LRCM with first element removed
and the last element holding our hop's LRAR, encrypted via

x = SE(s, u, LRAR)
h = MDS(x, s)

h + x is stored as the ack and appended to the end of r and the first element of
r is removed.


link relay acknowledgement record (LRAR)

{
  c: "<32 bytes public encryption key>",
  r: "<16 bytes rx path id>",
}

all parameters in the LRAR are chosen by the hop

it puts an association (rxid, next_hop) -> ( prev_hop, LRAR.c )

when we get an LCAM from next_hop with rxid we will know the parameters for it.


plaintext contents of f is:

[ PRI, PRI, PRI ...]

path reply info (PRI):

{
  n: "<24 bytes nonce>",
  s: "<32 bytes symmettric key>",
  v: 0
}



link commit acknowledgement message (LCAM)

sent in the opposite direction of an LRCM by the farthest hop in the path.
this establishes the downstream keys.

{
  a: "a",
  c: [ list, of, encrypted, LCAR],
  l: encrypted frame for path creator,
  t: "<16 bytes tx hop>",
  v: 0
}

the recipiant's public key for frame encryption of l is obtained from the LRCM's
last hop frame. the sender's public key is RC.e of the farthest hop.

each entry in c is encrypted using the symettric key and nonce provided from the
corrisponding LRCM previously received.

link commit acknowledgement record (LCAR)

a record in an LCAM

{
  c: "<32 bytes public encryption key for downstream traffic>",
  n: "<32 bytes nonce for kdf>",
  r: "<16 bytes next rx path id>",
  v: 0
}

downstream key is generated via:

k_down = PKE(LRAR.c, LCAM.c, LCAM.n)

next a LCAM is sent to prev_hop with LCAR.r as rxid with the first element
popped off and the last element filled with random.


link relay upstream message (LRUM)

sent to relay data via upstream direction of a previously created path.

{
  a: "u",
  p: "<16 bytes tx path id>",
  v: 0,
  x: "<N bytes encrypted x1 value>",
  y: "<32 bytes nonce>",
  z: "<discard>"
}

plaintext x1 is a routing message


x1 = BD(SD(k_up, y[0:24], x))
new_y = HS(y + k_up)
verify new_y == x1.n

in the event we get a path data message (PDM), transmit a LRUM to next hop 

{
  a: "u",
  p: x1.P,
  v: x1.V,
  x: x1.D,
  y: x1.N,
  z: RAND(x1.R)
}

if we are the farthest hop, process x1 as a routing message


link relay downstream message (LRDM)

sent to relay data via downstream direction of a previously created path.

same as LRUM but a is 'd' and p/x1.p refer to the rx path id

link relay exit message (LRXM) [under construction]

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, ecrypted, exit, records ],
  v: 0
}

link relay exit record (LRXR)

{
  c: "x",
  p: "<16 bytes tx path id>",
  v: 0,
  x: "<N bytes padding>",
  z: "<64 bytes signature>"
}

link immediate dht message (LIDM):

transfer one or more dht messages directly without a previously made path.

{
  a: "m",
  m: [many, dht, messages],
  v: 0
}


link stateless relay message (LSRM)

statelessly relay a link message.

{
  a: "r",
  c: r_counter_uint8,
  d: "<32 bytes rc.K of destination>",
  s: "<32 bytes rc.K of source>",
  v: 0,
  x: "<N bytes encrypted link message>",
  y: "<24 bytes nounce>",
  z: "<64 bytes signature>"
}

ONLY exchanged over ethernet, if recieved from an IP link it MUST be discarded.

relay an encrypted link message from source s to destination d.
check signature z using public key s and discard if invalid signature.

if d is equal to ourRC.k then decrypt x via SD(KE(d, s), y, x) and process it as
a link message. if the inner decrypted link message is a LRCM forward all
following LRUM, LRDM and LRSM to s via a LSRM. LIDM and LSRM are discarded.

if d is not equal to ourRC.k then forward it to an ethernet peer that is cloeser
to d than you are. if you are closer to d than all of your other ethernet peers
then increment c and send to the ethernet peer with the lowest detected latency
that isn't the peer that this message was recieved from but ONLY if c is less
than 128. if c is equal to or greater than 128 then the message is discarded.

---

routing layer:

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

ipv4 addresses are allowed via ipv4 mapped ipv6 addresses, i.e. ::ffff.10.0.0.1

path data message (PDM)

intermediate path data
forward N as LRUM if we got it in a LRUM
forward N as LRDM if we got it in a LRDM

{
  A: "D",
  D: "<N bytes payload here>",
  N: "<32 bytes next nonce>",
  P: "<16 bytes next path id>", 
  R: number_of_bytes_Z_padding,
  V: 0
}

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>",
  V: 0,
  X: lifetime_of_address_mapping_in_seconds_uint64,
}

grant exit address messsage (GXAM)

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

{
  A: "G",
  E: XR,
  I: "<32 bytes signing public key of requester>",
  T: transaction_id_uint64,
  V: 0,
  Z: "<64 bytes signature using exit info's signing key>"
}

E contains an exit route that was granted to the requester that can be used with
IP exit traffic.

The requester will now have any ip traffic going to address S forwarded to them
via the path that originally sent the OXAM and any TDFM will is recieved on the
same path will be forwarded out to the internet, given that they have
valid signatures and addresses.


reject exit address message (RXAM)

sent in response to an OXAM to indicate that exit traffic is not allowed or
was denied.

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

B is set to a backoff value.
R contains additional metadata text describing why the exit was rejected.



hidden service data message (HSDM)

signed data sent anonymously over the network to a recipiant from a sender.
sent inside a TDFM encrypted to the hidden service's public encryption key.

{
  A: "H",
  H: "<payload bytes>",
  I: Introducer for reply,
  R: SA of recipiant,
  S: SI of sender,
  V: 0,
  Z: "<64 bytes signature from sender of the entire message>"
}

transfer data fragment message (TDFM)

variant 1 (with path id):

transfer data between paths.

{
  A: "T",
  P: path_id_uint64,
  V: 0,
  X: "<N bytes payload>", 
  Y: "<24 bytes nounce>",
  Z: "<64 bytes signature>"
}

transfer data to another path with id P on the local router place Y and X values
into y and z values into a LRDM message (respectively) and send it in the
downstream direction.

variant 2 (no path id):

transfer ip traffic for exit

{
  A: "T",
  V: 0,
  X: "<N bytes ipv6 packet>",
  Y: "<16 bytes nounce>",
  Z: "<64 bytes signature using previously provided signing key>"
}

X is parsed as an IPv6 packet and the source addresss is extracted.
Next we find the corrisponding signing key for a previously granted exit address
and use it to validate the siganture of the entire message. If the signing key
cannot be found or the signature is invalid this message is dropped, otherwise
the X value is sent on the appropriate exit network interface.

When we recieve an ip packet from the internet to an exit address, we put it
into a TDFM, signed with the exit info's signing key and send it downstream the
corrisponding path in an LRDM.

update exit path message (UXPM)

sent from a new path by client to indicate that a previously established exit
should use the new path that this message came from.

{
  A: "U",
  T: transaction_id_uint64,
  V: 0,
  Y: "<16 bytes nounce>",
  Z: "<64 bytes signature using previously provided signing key>"
}

T is the transaction ID from the GXAM

close exit path message (CXPM)

client sends a CXPM when the exit is no longer needed.
The address used in exit MAY be reused later.

{
  A: "C",
  T: transaction_id_uint64,
  V: 0,
  Y: "<16 bytes nounce>",
  Z: "<64 bytes signagure using previously provided signing key>"
}