lokinet/doc/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 UDP.

Nouns (data structures):

Path: information about a path that we have built

{
  H: "<RouterID_0 + RouterID_1 + ... RouterID_N>" // 32 bytes aligned
  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 blob for hidden service address

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

IntroSet: information about an introduction set from the network

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

HiddenServiceMessage: a message sent between hidden services

{
  D: "<N bytes payload>",
  R: ServiceInfo of recipiant,
  S: ServiceInfo of source
}

HiddenServiceSessionInfo: information about our current session

{
  P: [Path0, Path1, .... PathN],
  I: "<32 byte aligned remote hidden services inbound>",
  O: "<32 byte aligned remote hidden services outbound>",
  S: Current ServiceInfo,
}

Verbs (methods):

spawn a new hidden service (C->S)

{
  A: "spawn",
  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",
  N: "Human Readable Name Of Hidden Service",
  S: ServiceInfo,
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

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

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

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

{
  A: "lookup",
  I: IntroSet,
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}


align a path to align with a remote endpoint by public router ID (C->S)

{
  A: "align",
  R: "<32 bytes router ID>",
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

infrom that we have aligned with a remote endpoint (S->C)

{
  A: "align",
  R: "<32 bytes Router ID>",
  I: IntroForPathAligned,
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

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

{
  A: "data",
  D: "destinationaddressbase32.loki",
  I: Introduction in use,
  S: "sourceaddressbase32.loki",
  X: "<N bytes payload>",
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}


sent in reply to every message indicating that it was recieved (bidi)

{
  A: "ack",
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

send a session keep alive (bidi)

{
  A: "keepalive",
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>",
}

exit session (bidi)

{
  A: "exit",
  Y: sequence_num_uint64,
  Z: "<32 bytes keyed hash>"
}

Protocol Flow:

all messages have an A, Y and Z value

A is the function name being called

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)

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.