lokinet/docs/api_v0.txt

LLARP Traffic Routing Protocol (LTRP)

LRTP is a protocol that instructs how to route hidden service traffic on LLARP 
based networks.

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].

Overview:

LRTP is a message oriented data delivery and receival protocol for hidden 
service traffic. All structures are BitTorrent Encoded dictionaries sent 
over TCP.

all structures are bencoded when sent over the network but are provided in JSON
for ease of display in documentation.

message format:

<2 bytes length (N)>
<N bytes of data>


Nouns (data structures):

Path: information about a path that we have built

{
  H: [router_id, router_id, router_id, router_id],
  R: "<16 bytes local rxid>",
  T: "<16 bytes local txid>"
}

Introduction: a hidden service introduction

{
  E: expiration_ms_since_epoch_uint64,
  L: advertised_latency_ms_uint64,
  P: "<16 bytes pathid>",
  R: "<32 bytes RouterID>",
}

ServiceInfo: public key info for hidden service address

{
  A: "<32 bytes .loki address>",
  E: "<32 bytes public encryption key>",
  S: "<32 bytes public signing key>"
}

IntroSet: information about an introduction set from the network

{
  E: expires_at_timestamp_ms_since_epoch_uint64,
  I: [Intro0, Intro1, ... IntroN],
  S: ServiceInfo
}

Converstation: information about a loki network converstation

{
  A: "<32 bytes loki address>",
  T: "<16 bytes convo tag>"
}

SessionInfo: information about our current session

{
  I: [inbound,convos,here],
  O: [outbound,covos,here],
  P: [Path0, Path1, .... PathN],
  S: Current IntroSet,
}

Verbs (methods):

session requset (C->S)

{
  A: "session",
  B: "<8 bytes random>",
  T: milliseconds_since_epoch_client_now_uint64,
  Y: 0,
  Z: "<32 bytes keyed hash>"
}

session accept (S->C)

sent in reply to a session message to indicate session accept and give
a session cookie to the client.

{
  A: "session-reply",
  C: "<16 bytes session cookie>",
  T: milliseconds_since_epoch_server_now_uint64,
  Y: 0,
  Z: "<32 bytes keyed hash>"
}

session reject (S->C)

sent in reply to a session message to indicate session rejection

{
  A: "session-reject",
  B: "<8 bytes random>",
  R: "<variable length utf-8 encoded bytes human readable reason here>",
  T: milliseconds_since_epoch_server_now_uint64,
  Y: 0,
  Z: "<32 bytes keyed hash>"
}

spawn a hidden service (C->S)

only one hidden service can be made per session

{
  A: "spawn",
  C: "<16 bytes session cookie>",
  N: "Human Readable Name Of Hidden Service",
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

inform that we have spawned a new hidden service endpoint (S->C)

{
  A: "spawn-reply",
  C: "<16 bytes session cookie>",
  N: "Human Readable Name Of Hidden Service",
  S: ServiceInfo,
  Z: "<32 bytes keyed hash>"
}

lookup an intro set for a remote hidden service (C->S)

{
  A: "lookup"
  C: "<16 bytes session cookie>",
  N: "base32encoded.loki",
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

reply to a intro set lookup (S->C)

{
  A: "lookup-reply",
  C: "<16 bytes session cookie>",
  I: IntroSet,
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}




craete a new convseration on a loki address (bidi)

{
  A: "make-convo",
  C: "<16 bytes session cookie>",
  R: "<32 bytes loki address>",
  T: "<16 bytes convo tag>",
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

infrom the status of a converstation on a loki address (S->C)

sent every 500 ms until fully established for outbound convos and immediately
when a new inbound conversation is made.

S bit 0 (LSB): we found the introset for (set by outbound)
S bit 1: we found the router to align on (set by outbound)
S bit 2: we have a path right now (set by outbound)
S bit 3: we have made the converstation (set by both)
S bit 4: we are an inbound converstation (set by inbound)

{
  A: "convo",
  C: "<16 bytes session cookie>",
  R: "<32 bytes loki remote address>",
  S: bitmask_status_uint64,
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

send or recieve authenticated data to or from the network (bidi)

{
  A: "data",
  C: "<16 bytes session cookie>",
  T: "<16 bytes convotag>",
  P: protocol_number_uint,
  X: "<N bytes payload>",
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}


session information update (S->C)

sent every 5000 millisecond to the client

{
  A: "info",
  C: "<16 bytes session cookie>",
  I: hiddenserviceinfo,
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

Protocol Flow:

all messages have an A, C, Y and Z value

A is the function name being called

C is the session cookie indicating the current session

Y is the 64 bit message sequence number

Z is the keyed hash computed by MDS(BE(msg), K) where K is HS(api_password)
with the msg.Z being set to zeros.

both client and server MUST know a variable length string api_password used to
authenticate access to the api subsystem.

first message MUST be a spawn message, before any other messages are sent by 
client (other than keepalives and acl) the client MUST wait for the server to 
send a spawn message in reply.

once the server spawn message is sent lookup messages may be sent.

when a lookup is done by the client, the router looks up the descriptor from
the DHT. when a response is obtained the api server gives the introset to 
the client.

in order to send data to a remote hidden service, the client must align a path
to a intro in the hidden service's intro set.

after alignment is done, data messages may flow in a bidirectional manner.