diff --git a/docs/api_v0.txt b/docs/api_v0.txt index 3fd3079dd..0aaa9fec5 100644 --- a/docs/api_v0.txt +++ b/docs/api_v0.txt @@ -12,14 +12,23 @@ Overview: LRTP is a message oriented data delivery and receival protocol for hidden service traffic. All structures are BitTorrent Encoded dictionaries sent -over UDP. +over TCP. + +all structures are bencoded when sent over the networks. +In this document they are provided in JSON for ease of display. + +message format: + +<2 bytes length (N)> + + Nouns (data structures): Path: information about a path that we have built { - H: "" // 32 bytes aligned + H: [router_id_32_bytes, router_id_32_bytes, router_id_32_bytes, router_id_32_bytes], R: "<16 bytes local rxid>", T: "<16 bytes local txid>" } @@ -30,161 +39,225 @@ Introduction: a hidden service introduction E: expiration_ms_since_epoch_uint64, L: advertised_latency_ms_uint64, P: "<16 bytes pathid>", - R: "<32 bytes RouterID>", + R: "<32 bytes RouterID>" } -ServiceInfo: public key blob for hidden service address +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>", - X: "computedbase32address.loki" + 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 } -HiddenServiceMessage: a message sent between hidden services +Converstation: information about a loki network converstation { - D: "", - R: ServiceInfo of recipiant, - S: ServiceInfo of source + L: "<32 bytes loki address provided if a loki address>", + S: "<32 bytes snode address provided if a snode address>", + T: "<16 bytes convo tag>" } -HiddenServiceSessionInfo: information about our current session +SessionInfo: information about our current session { + I: [inbound,convos,here], + O: [outbound,covos,here], P: [Path0, Path1, .... PathN], - I: "<32 byte aligned remote hidden services inbound>", - O: "<32 byte aligned remote hidden services outbound>", - S: Current ServiceInfo, + S: Current IntroSet, } Verbs (methods): -spawn a new hidden service (C->S) +session requset (C->S) + +the first message sent by the client + +{ + 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", + B: "<8 bytes random from session request>", + 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 from session request>", + R: "", + 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", - N: "Human Readable Name Of Hidden Service", - Y: sequence_num_uint64, + C: "<16 bytes session cookie>", + O: config_options_dict, + Y: 1, 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", + A: "spawn-reply", + C: "<16 bytes session cookie>", S: ServiceInfo, - Y: sequence_num_uint64, + Y: 1, Z: "<32 bytes keyed hash>" } -lookup an intro set for a remote hidden service (C->S) +inform that we have not spaned a new hidden service endpint (S->C) + +after sending this message the server closes the connection { - A: "lookup" - N: "base32encoded.loki", - Y: sequence_num_uint64, + A: "spawn-reject", + C: "<16 bytes session cookie>", + E: "", + Y: 1, Z: "<32 bytes keyed hash>" } -reply to a intro set lookup (S->C) +create a new convseration on a loki/snode address (C->S) { - A: "lookup", - I: IntroSet, + A: "start-convo", + B: "<8 bytes random>", + C: "<16 bytes session cookie>", + R: "human readable remote address .snode/.loki", Y: sequence_num_uint64, Z: "<32 bytes keyed hash>" } - -align a path to align with a remote endpoint by public router ID (C->S) +sent in reply to a make-convo message to indicate rejection (S->C) { - A: "align", - R: "<32 bytes router ID>", + A: "start-convo-reject", + B: "<8 bytes random from start-convo message>", + C: "<16 bytes session cookie>", + S: status_bitmask_uint, Y: sequence_num_uint64, Z: "<32 bytes keyed hash>" } -infrom that we have aligned with a remote endpoint (S->C) +sent in reply to a make-convo message to indicate that we have accepted this +new conversation and gives the convo tag it uses. { - A: "align", - R: "<32 bytes Router ID>", - I: IntroForPathAligned, + A: "start-convo-accept", + B: "<8 bytes random from start-convo message>", + C: "<16 bytes session cookie>", Y: sequence_num_uint64, - Z: "<32 bytes keyed hash>" + Z: "<32 bytes keyed hash> } -send or recieve authenticated data to or from the network (bidi) +infrom the status of a converstation on a loki address (S->C) + +for an outbund conversation it is sent every time the status bitmask changes. +for inbound convos it is sent immediately when a new inbound conversation is made. + +S bit 0 (LSB): we found the introset/endpoint 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: "data", - D: "destinationaddressbase32.loki", - I: Introduction in use, - S: "sourceaddressbase32.loki", - X: "", + A: "convo-status", + C: "<16 bytes session cookie>", + R: "human readable address .snode/.loki", + S: bitmask_status_uint64, + T: "<16 bytes convotag>", Y: sequence_num_uint64, Z: "<32 bytes keyed hash>" } +send or recieve authenticated data to or from the network (bidi) -sent in reply to every message indicating that it was recieved (bidi) +protocol numbers are + +1 for ipv4 +2 for ipv6 { - A: "ack", + A: "data", + C: "<16 bytes session cookie>", + T: "<16 bytes convotag>", + W: protocol_number_uint, + X: "", Y: sequence_num_uint64, Z: "<32 bytes keyed hash>" } -send a session keep alive (bidi) +get session information (C->S) { - A: "keepalive", + A: "info", + C: "<16 bytes session cookie>", Y: sequence_num_uint64, - Z: "<32 bytes keyed hash>", + Z: "<32 bytes keyed hash>" } -exit session (bidi) + +session information update (S->C) + +sent in reply to a get session information message { - A: "exit", + A: "info-reply", + C: "<16 bytes session cookie>", + I: hiddenserviceinfo, Y: sequence_num_uint64, Z: "<32 bytes keyed hash>" } Protocol Flow: -all messages have an A, Y and Z value +all messages have an A, C, Y and Z value A is the function name being called -Y is the 64 bit message sequence number +C is the session cookie indicating the current session + +Y is the 64 bit message sequence number as an integer Z is the keyed hash computed by MDS(BE(msg), K) where K is HS(api_password) +with the msg.Z being set to 32 bytes of \x00 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. \ No newline at end of file +the Y value is incremented by 1 for each direction every time the sender sends +a message in that direction.