Research about designing an armored bridge line sharing URL format
Tor's bridge line format is well suited for professional developers and power users on desktop environments. However, for other users the current bridge line does not work so well because:
- The bridge line contains white space and other special characters that could make it hard to copy and paste correctly.
- When the bridge line was corrupted, the client software can neither detect it, nor correct it. This results in user confusion as the corrupted bridge line results in silent error.
- User tries to edit the bridge line without understanding how it works internally. This results in inconsistency between how the user expects a bridge line to work and how it actually works.
This ticket tracks the research and discussion about creating a new bridge line format specialized in sharing to address the issues mentioned.
Let's make some initial discussion before I write the full spec and write a reference implementation.
Goals and non-goals
This armored bridge line format will try to:
- auto detect/auto correct error occurred during transmission. Give the user explicit feedback when the bridge line is corrupted and avoid silent errors.
- improve its operating system integration, allowing the user to click on the armored bridge line and be redirected to a bridge line recipient application.
- avoid any characters or design that could make it harder to transmit the bridge line correctly.
- signal user not to modify the shared bridge line by intuitively
It won't:
- try to replace the current bridge line format. It is used to share bridge lines, and original bridge line format will still be accepted by all Tor applications and shown to users by default. The current bridge line format will still be the way bridge configurations are represented.
- prevent users from editing bridge lines. Users still will be able to edit the bridge line once it is decoded from armored format.
- prevent the bridge line from being censored or detected by authority.
Expected Usage Context
This armored bridge line design will be used exclusively for sharing.
Specifically:
- On Tor Browser, there will be a share bridge line button, when clicked, an armored bridge line will be converted from an ordinary bridge line, and shown to the user as plain text and QR code.
- The user support team will share an armored bridge line generated from Tor Browser or command line tool to users requesting a bridge when appropriate.
- Users can share armored bridge lines with each other.
- Tor client implementations MAY support armored bridge line input. It is optional since this design is targeted toward ordinary users, and Tor Browser already supports converting bridge lines between different forms with command line tools. Advanced users can just use command line tools to convert bridge lines between its different formats.
Internal design (for discussion)
The 2 way convention between armored bridge line and ordinary bridge line is through a sequence of reversible transform steps. Some of them are optional(under discussion), and may or may not be included in the final design. There are no dynamic or skipable step in the final version of the design.
Compression (optional)
A compression like 7 bit UTF8 can be used to reduce the length of the final url string. It will however make conversion more complex to implement.
All or none transform (optional)
A all or none transform(AONT) like SAEP+ can make sure the final output is completely random looking, polymorphic without any resemblance of underlying data.
This ensures:
- Data are covered by checksum(see SAEP+ design), so any corruption will be detected.
- Because data are encoded differently each time, if the final output contains a censored keyword, the user can just try again.
- there will be less observable patterns in the final URL, preventing users from attempting to modify or interpreting it. The users will need to use a supported application to process the armored bridge line.
- (less of a concern for Tor ecosystem) prevent client implementation from ignoring the checksum and process anyway.
This is a complex transform step.
Checksum (if All or none transform step is not used) (optional)
Use a CRC64 or SHA-3 to generate a checksum to detect corruption.
This step should be skipped if AONT step was used.
Forward error correction (optional)
Split the data into chunks and use Reed Solomon coding to encode the data and generate recovery shreds.
When the bridge line is corrupted, forward error correction attempts to repair content directly, without asking the user to try again. This non-interactive repair makes it easier for the user to get the bridge line working, without asking and waiting for assistance. Some environments like bad email clients/line breakers corrupt the content each time it processes it, retry itself won't work and frustrate users.
This is a complex transform step.
URLSafe base64 encoding without padding + concreted
URL safe base64 encoding without padding will convert the binary result of previous steps into a URL safe string. If there is more than one shard of contents, they will be concreted with ~ symbol, which is URL safe and not used by URL safe base64.
URL Prefix
The final string will be prefixed with either bridgeprefix:?
or https://bridgeprefix/#
to allow it to be clicked and be redirected to Tor client application by operating system.