lox/doc/lox-distributor-api.md

API Documentation for Lox Distributor

Overview

The Lox distributor receives resources from rdsys and writes them to Lox BridgeLines which are used to populate Lox's bridgetable. The bridgelines are sorted into open entry and hot spare buckets (which can be used to replace blocked bridges or those that are no longer distributed by rdsys). Each time resources are requested from rdsys, the bridgelines received are synced with Lox's existing bridgetable. New resources are appended to the bridgetable and assigned to new (open entry or) hot spare buckets. Resources with changed information are identified by their fingerprint, and updated in the bridgetable. Concurrently with syncing, the distributor receives and responds to requests from Lox clients.

Lox client requests

Lox clients make periodic requests to the Lox distributor through POST requests to various endpoints:

Headers

• Host: must be set
• Content-Type: must be set to application/json

Client Requests without Data

Reachability Credential

Endpoint: /reachability Body: empty

Reachability credentials are freshness tokens that confirm the bucket in a Lox credential isn't blocked.

Reachability Example Request:

POST /reachability HTTP/1.1
Host: localhost:8100
Content-Type: application/json

Reachability Example Response Body:

[{"X":[[32,42,33,192,42,192,76,69,25,142,135,47,167,226,145,12,9,200,219,134,184,199,251,181,191,24,246,111,56,241,86,117],[86,203,251,39,118,208,115,192,60,128,84,255,164,9,66,235,184,199,118,174,188,126,238,98,67,174,240,159,9,66,6,31],[86,73,27,240,105,210,61,53,222,251,187,16,118,151,186,33,91,59,163,160,32,7,219,137,185,49,70,192,214,85,217,79],[132,183,214,45,227,118,3,236,8,76,193,41,61,160,100,93,177,5,120,165,173,13,83,171,253,190,74,94,151,113,26,16],[116,207,116,236,37,247,161,233,184,217,193,17,90,157,191,78,61,139,180,31,240,116,224,182,162,232,248,194,162,228,210,71],[28,70,221,171,158,248,248,74,227,204,199,164,81,29,178,216,149,5,7,196,30,66,172,93,133,26,89,236,223,99,126,75],[86,35,210,49,17,13,182,111,80,225,187,23,220,161,105,32,130,19,105,80,151,230,162,67,118,160,178,223,49,162,129,125]]},{"X":[[74,43,179,87,134,246,247,215,231,162,7,96,231,78,193,82,217,240,122,55,4,63,46,37,216,236,125,224,186,232,64,54],[90,46,128,37,199,205,137,207,235,218,100,14,93,10,83,179,154,199,71,136,240,47,31,227,232,159,238,107,31,3,18,27],[176,130,161,54,245,155,205,235,96,5,82,7,146,234,34,41,195,90,80,131,69,30,215,170,164,76,87,40,78,185,195,41],[34,138,37,63,126,59,100,100,169,112,156,115,188,103,134,239,196,146,96,79,33,185,66,121,206,227,117,146,107,141,166,15],[246,19,224,128,119,40,140,254,122,194,237,42,73,171,56,13,89,16,132,111,251,38,116,209,52,241,195,70,150,134,143,1]]},{"X":[[30,121,219,56,164,90,181,198,41,0,75,175,116,149,149,214,114,210,58,96,94,98,41,129,102,7,53,212,154,240,116,46],[116,66,239,117,202,173,23,51,11,92,234,52,201,73,22,196,177,19,137,183,90,225,224,37,226,68,56,106,1,237,80,89],[8,185,193,108,42,105,110,148,196,165,38,113,8,148,21,160,241,51,31,23,140,223,116,250,75,157,50,154,43,125,239,71]]},{"X":[[192,30,38,225,82,41,239,207,228,117,85,181,23,159,125,203,53,195,141,149,252,50,221,49,63,157,147,152,219,72,161,83],[182,187,203,171,143,89,69,70,59,213,154,130,15,112,50,30,250,138,171,61,26,198,3,73,118,129,79,108,242,81,47,12],[110,69,138,66,120,45,177,47,14,235,41,144,197,136,188,245,127,73,85,103,182,48,40,225,48,250,240,44,135,79,12,119]]},{"X":[[158,144,97,7,148,145,17,91,5,41,218,230,194,158,124,30,103,129,218,108,243,205,53,42,126,84,194,97,166,63,158,107],[64,140,146,26,89,105,199,139,163,155,39,98,81,209,236,252,130,128,36,139,87,16,18,3,74,214,172,119,176,69,106,90],[12,88,112,202,248,255,37,204,90,169,50,5,154,36,42,189,30,189,198,157,22,210,67,86,52,14,46,50,149,53,91,12],[184,37,27,9,36,84,123,31,185,2,182,25,155,45,74,241,51,241,233,3,91,219,101,125,173,0,203,232,116,208,117,88],[148,106,194,9,9,125,247,153,92,97,243,101,170,6,227,130,52,51,182,34,197,187,151,242,30,200,156,243,158,100,96,106]]}]

Public Keys

Endpoint: /pubkeys Body: empty

The public keys for each type of Lox credential are bundled together and can be reused until Lox keys are rotated.

Pubkeys Example Request:

POST /pubkeys HTTP/1.1
Host: localhost:8100
Content-Type: application/json

Pubkeys Example Response Body:

[{"X":[[32,42,33,192,42,192,76,69,25,142,135,47,167,226,145,12,9,200,219,134,184,199,251,181,191,24,246,111,56,241,86,117],[86,203,251,39,118,208,115,192,60,128,84,255,164,9,66,235,184,199,118,174,188,126,238,98,67,174,240,159,9,66,6,31],[86,73,27,240,105,210,61,53,222,251,187,16,118,151,186,33,91,59,163,160,32,7,219,137,185,49,70,192,214,85,217,79],[132,183,214,45,227,118,3,236,8,76,193,41,61,160,100,93,177,5,120,165,173,13,83,171,253,190,74,94,151,113,26,16],[116,207,116,236,37,247,161,233,184,217,193,17,90,157,191,78,61,139,180,31,240,116,224,182,162,232,248,194,162,228,210,71],[28,70,221,171,158,248,248,74,227,204,199,164,81,29,178,216,149,5,7,196,30,66,172,93,133,26,89,236,223,99,126,75],[86,35,210,49,17,13,182,111,80,225,187,23,220,161,105,32,130,19,105,80,151,230,162,67,118,160,178,223,49,162,129,125]]},{"X":[[74,43,179,87,134,246,247,215,231,162,7,96,231,78,193,82,217,240,122,55,4,63,46,37,216,236,125,224,186,232,64,54],[90,46,128,37,199,205,137,207,235,218,100,14,93,10,83,179,154,199,71,136,240,47,31,227,232,159,238,107,31,3,18,27],[176,130,161,54,245,155,205,235,96,5,82,7,146,234,34,41,195,90,80,131,69,30,215,170,164,76,87,40,78,185,195,41],[34,138,37,63,126,59,100,100,169,112,156,115,188,103,134,239,196,146,96,79,33,185,66,121,206,227,117,146,107,141,166,15],[246,19,224,128,119,40,140,254,122,194,237,42,73,171,56,13,89,16,132,111,251,38,116,209,52,241,195,70,150,134,143,1]]},{"X":[[30,121,219,56,164,90,181,198,41,0,75,175,116,149,149,214,114,210,58,96,94,98,41,129,102,7,53,212,154,240,116,46],[116,66,239,117,202,173,23,51,11,92,234,52,201,73,22,196,177,19,137,183,90,225,224,37,226,68,56,106,1,237,80,89],[8,185,193,108,42,105,110,148,196,165,38,113,8,148,21,160,241,51,31,23,140,223,116,250,75,157,50,154,43,125,239,71]]},{"X":[[192,30,38,225,82,41,239,207,228,117,85,181,23,159,125,203,53,195,141,149,252,50,221,49,63,157,147,152,219,72,161,83],[182,187,203,171,143,89,69,70,59,213,154,130,15,112,50,30,250,138,171,61,26,198,3,73,118,129,79,108,242,81,47,12],[110,69,138,66,120,45,177,47,14,235,41,144,197,136,188,245,127,73,85,103,182,48,40,225,48,250,240,44,135,79,12,119]]},{"X":[[158,144,97,7,148,145,17,91,5,41,218,230,194,158,124,30,103,129,218,108,243,205,53,42,126,84,194,97,166,63,158,107],[64,140,146,26,89,105,199,139,163,155,39,98,81,209,236,252,130,128,36,139,87,16,18,3,74,214,172,119,176,69,106,90],[12,88,112,202,248,255,37,204,90,169,50,5,154,36,42,189,30,189,198,157,22,210,67,86,52,14,46,50,149,53,91,12],[184,37,27,9,36,84,123,31,185,2,182,25,155,45,74,241,51,241,233,3,91,219,101,125,173,0,203,232,116,208,117,88],[148,106,194,9,9,125,247,153,92,97,243,101,170,6,227,130,52,51,182,34,197,187,151,242,30,200,156,243,158,100,96,106]]}]

Request Invite

Endpoint: /invite Body: empty

Open invitations can be requested by untrusted users to get an initial Lox credential. These will be distributed through a telegram bot that requests through this endpoint.

Example:

POST /invite HTTP/1.1
Host: localhost:8100
Content-Type: application/json

Client Requests with Data

Once a user has an open invitation or Lox credential, each client request will be sent with a JSON object to different endpoints corresponding to the correct Lox protocol:

Open Invitation

Endpoint: /openreq Body: empty

Example:

POST /openreq HTTP/1.1
Host: localhost:8100
Content-Type: application/json

{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}

Trust Promotion

Endpoint: /trustpromo Body: empty

Example:

POST /trustpromo HTTP/1.1
Host: localhost:8100
Content-Type: application/json

{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}

Trust Migration

Endpoint: /trustmig Body: empty

Example:

POST /trustmig HTTP/1.1
Host: localhost:8100
Content-Type: application/json

{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}

Level Up

Endpoint: /levelup Body: empty

Example:

POST /levelup HTTP/1.1
Host: localhost:8100
Content-Type: application/json

{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}

Issue Invitation

Endpoint: /issueinvite Body: empty

Example:

POST /issueinvite HTTP/1.1
Host: localhost:8100
Content-Type: application/json

{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}

Redeem Invitation

Endpoint: /redeeminvite Body: empty

Example:

POST /redeem HTTP/1.1
Host: localhost:8100
Content-Type: application/json

{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}

Check Blockage

Endpoint: /checkblockage Body: empty

Example:

POST /checkblockage HTTP/1.1
Host: localhost:8100
Content-Type: application/json

{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}

Blockage Migration

Endpoint: /blockagemigration Body: empty

Example:

POST /blockagemigration HTTP/1.1
Host: localhost:8100
Content-Type: application/json

{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}

Lox Server responses

The HTTP response to the POST request API call is a chunked transfer encoding of a list of JSON objects that represent all the resources currently allocated to the distributor.

[
  Resource,
  Resource,
  ...
  Resource
]