GitLab is used only for code review, issue tracking and project management. Canonical locations for source code are still https://gitweb.torproject.org/ https://git.torproject.org/ and git-rw.torproject.org.

README.md 3.5 KB
Newer Older
1 2 3
Bridgestrap
===========

4 5 6
Bridgestrap implements an API (for machines) and a Web interface (for people)
to test Tor bridge lines by making a Tor instance fetch the bridges'
descriptor.
7 8 9 10 11 12 13 14 15 16 17 18

Installation
------------

First, install the Golang binary:

      go install

Then, run the binary:

      bridgestrap

19
By default, bridgestrap will listen on port 5000.  To use its Web interface
Philipp Winter's avatar
Philipp Winter committed
20
(don't forget to turn it on by using the `-web` switch), point your browser to
21 22
the address and port that bridgestrap is listening on.  Use the argument
`-addr` to listen to a custom address and port.
23 24 25 26

Input
-----

27 28
Clients send one or more bridge lines to the following API, using an HTTP GET
request, and place the bridge lines in the request body:
29

30
      https://HOST/bridge-state
31

32
The request body must look as follows:
33

34
      {"bridge_lines": ["BRIDGE_LINE_1", ..., "BRIDGE_LINE_N"]}
35

36 37
The "BRIDGE_LINE" strings in the list may contain any bridge line (excluding
the "Bridge" prefix) that tor accepts.  Here are a few examples:
38

39 40 41 42 43 44
* `1.2.3.4:1234`
* `1.2.3.4:1234 1234567890ABCDEF1234567890ABCDEF12345678`
* `obfs4 1.2.3.4:1234 cert=fJRlJc0T7i2Qkw3SyLQq+M6iTGs9ghLHK65LBy/MQewXJpNOKFq63Om1JHVkLlrmEBbX1w iat-mode=0`

You can test bridgestrap's API over the command line as follows:

45 46 47 48
      curl -X GET localhost:5000/bridge-state -d '{"bridge_lines": ["BRIDGE_LINE"]}'

You can also use the script test-bridge-lines in the "script" directory to test
a batch of bridge lines.
49 50 51 52 53 54 55

Output
------

The service responds with the following JSON:

      {
56 57
        "bridge_results": {
          "BRIDGE_LINE_1": {
Philipp Winter's avatar
Philipp Winter committed
58
            "functional": BOOL,
59
            "last_tested": "STRING",
60 61 62 63 64 65 66 67
            "error": "STRING", (only present if "functional" is false)
          },
          ...
          "BRIDGE_LINE_N": {
            ...
          }
        },
        "error": "STRING", (only present if the entire test failed)
68 69 70
        "time": FLOAT
      }

71
In a nutshell, the "bridge_results" dictionary maps bridge lines (as they were
72
provided in the request) to a dictionary consisting of three keys: "functional"
73 74
is set to "true" if tor could fetch the bridge's descriptor.  If tor was unable
to fetch the bridge's descriptor, "functional" is set to "false" and the
75 76 77
"error" key maps to an error string.  The key "last_tested" maps to a string
representation (in ISO 8601 format) of the UTC time and date the bridge was
last tested.
78

79 80 81 82
In addition to the "bridge_results" dictionary, the response may contain an
optional "error" key if the entire test failed (e.g. if bridgestrap failed to
communicate with its tor instance).  Finally, "time" is a float that represents
the number of seconds that the test took.
83

84
Here are a few examples:
85 86

    {
87 88 89 90
      "bridge_results": {
      },
      "error": "something truly ominous happened",
      "time": 0.32
91 92 93
    }

    {
94 95
      "bridge_results": {
        "obfs4 1.2.3.4:1234 cert=fJRlJc0T7i2Qkw3SyLQq+M6iTGs9ghLHK65LBy/MQewXJpNOKFq63Om1JHVkLlrmEBbX1w iat-mode=0": {
96 97
          "functional": true,
          "last_tested": "2020-11-12T19:42:16.736853122Z"
98 99 100
        },
        "1.2.3.4:1234": {
          "functional": false,
101
          "last_tested": "2020-11-10T09:44:45.877531581Z",
102 103 104 105
          "error": "timed out waiting for bridge descriptor"
        }
      },
      "time": 3.1824
106 107 108
    }

    {
109 110 111
      "bridge_results": {
        "1.2.3.4:1234 1234567890ABCDEF1234567890ABCDEF12345678": {
          "functional": false,
112
          "last_tested": "2020-11-10T09:44:45.877531581Z",
113 114 115 116
          "error": "timed out waiting for bridge descriptor"
        }
      },
      "time": 0
117
    }