diff options
author | Nick Mathewson <nickm@torproject.org> | 2023-10-12 21:46:51 -0400 |
---|---|---|
committer | Nick Mathewson <nickm@torproject.org> | 2023-10-12 21:46:51 -0400 |
commit | 3cd7716900e9e0712fb0ee4313979b37b172c4aa (patch) | |
tree | 30ed9b03475f7b3f93801a982c4f45afc72c7f57 /spec/pt-spec | |
parent | c7b1172618fbeadd0d6236a406697e2a99e58af9 (diff) | |
download | torspec-3cd7716900e9e0712fb0ee4313979b37b172c4aa.tar.gz torspec-3cd7716900e9e0712fb0ee4313979b37b172c4aa.zip |
Update more things that looked like html tags in the markdown
Diffstat (limited to 'spec/pt-spec')
-rw-r--r-- | spec/pt-spec/pluggable-transport-configuration-environment.md | 20 | ||||
-rw-r--r-- | spec/pt-spec/pluggable-transport-to-parent-process-communication.md | 27 |
2 files changed, 25 insertions, 22 deletions
diff --git a/spec/pt-spec/pluggable-transport-configuration-environment.md b/spec/pt-spec/pluggable-transport-configuration-environment.md index 61b6b01..3a201f8 100644 --- a/spec/pt-spec/pluggable-transport-configuration-environment.md +++ b/spec/pt-spec/pluggable-transport-configuration-environment.md @@ -124,7 +124,7 @@ Specifies an upstream proxy that the PT MUST use when making outgoing network connections. It is a URI [RFC3986] of the format: -<proxy_type>://[<user_name>[:<password>][@]<ip>:<port>. +`<proxy_type>://[<user_name>[:<password>][@]<ip>:<port>`. The "TOR_PT_PROXY" environment variable is OPTIONAL and MUST be omitted if there is no need to connect via an @@ -161,8 +161,8 @@ TOR_PT_SERVER_TRANSPORTS=obfs3,scramblesuit "TOR_PT_SERVER_TRANSPORT_OPTIONS" Specifies per-PT protocol configuration directives, as a -semicolon-separated list of <key>:<value> pairs, where <key> -is a PT name and <value> is a k=v string value with options +semicolon-separated list of `<key>:<value>` pairs, where `<key>` +is a PT name and `<value>` is a k=v string value with options that are to be passed to the transport. Colons, semicolons, and backslashes MUST be @@ -183,23 +183,23 @@ TOR_PT_SERVER_TRANSPORT_OPTIONS=scramblesuit:key=banana;automata:rule=110;automa "TOR_PT_SERVER_BINDADDR" ``` -A comma separated list of <key>-<value> pairs, where <key> is -a PT name and <value> is the <address>:<port> on which it +A comma separated list of `<key>-<value>` pairs, where `<key>` is +a PT name and `<value>` is the `<address>:<port>` on which it should listen for incoming client connections. The keys holding transport names MUST be in the same order as they appear in "TOR_PT_SERVER_TRANSPORTS". -The <address> MAY be a locally scoped address as long as port +The `<address>` MAY be a locally scoped address as long as port forwarding is done externally. -The <address>:<port> combination MUST be an IP address +The `<address>:<port>` combination MUST be an IP address supported by `bind()`, and MUST NOT be a host name. Applications MUST NOT set more than one <address>:<port> pair per PT name. -If there is no specific <address>:<port> combination to be +If there is no specific `<address>:<port>` combination to be configured for any transports, "TOR_PT_SERVER_BINDADDR" MAY be omitted. @@ -211,7 +211,7 @@ TOR_PT_SERVER_BINDADDR=obfs3-198.51.100.1:1984,scramblesuit-127.0.0.1:4891 Specifies the destination that the PT reverse proxy should forward traffic to after transforming it as appropriate, as an -<address>:<port>. +`<address>:<port>`. Connections to the destination specified via "TOR_PT_ORPORT" MUST only contain application payload. If the parent process @@ -227,7 +227,7 @@ TOR_PT_ORPORT=127.0.0.1:9001 Specifies the destination that the PT reverse proxy should forward traffic to, via the Extended ORPort protocol [EXTORPORT] -as an <address>:<port>. +as an `<address>:<port>`. The Extended ORPort protocol allows the PT reverse proxy to communicate per-connection metadata such as the PT name and diff --git a/spec/pt-spec/pluggable-transport-to-parent-process-communication.md b/spec/pt-spec/pluggable-transport-to-parent-process-communication.md index 7f7de76..b7f8175 100644 --- a/spec/pt-spec/pluggable-transport-to-parent-process-communication.md +++ b/spec/pt-spec/pluggable-transport-to-parent-process-communication.md @@ -4,6 +4,7 @@ All Pluggable Transport Proxies communicate to the parent process via writing NL-terminated lines to stdout. The line metaformat is: +```text <Line> ::= <Keyword> <OptArgs> <NL> <Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar> <KeywordChar> ::= <any US-ASCII alphanumeric, dash, and underscore> @@ -12,6 +13,7 @@ via writing NL-terminated lines to stdout. The line metaformat is: <ArgChar> ::= <any US-ASCII character but NUL or NL> <SP> ::= <US-ASCII whitespace symbol (32)> <NL> ::= <US-ASCII newline (line feed) character (10)> +``` The parent process MUST ignore lines received from PT proxies with unknown keywords. @@ -30,13 +32,13 @@ by the application. Upon determining the version to use, or lack thereof, the PT proxy responds with one of two messages. -VERSION-ERROR <ErrorMessage> +`VERSION-ERROR <ErrorMessage>` The "VERSION-ERROR" message is used to signal that there was no compatible Pluggable Transport Specification version present in the "TOR_PT_MANAGED_TRANSPORT_VER" list. -The <ErrorMessage> SHOULD be set to "no-version" for +The `<ErrorMessage>` SHOULD be set to "no-version" for historical reasons but MAY be set to a useful error message instead. @@ -45,9 +47,9 @@ message. Example: -VERSION-ERROR no-version +`VERSION-ERROR no-version` -VERSION <ProtocolVersion> +`VERSION <ProtocolVersion>` The "VERSION" message is used to signal the Pluggable Transport Specification version (as in "TOR_PT_MANAGED_TRANSPORT_VER") @@ -74,7 +76,7 @@ At any point, if there is an error encountered related to configuration supplied via the environment variables, it MAY respond with an error message and terminate. -ENV-ERROR <ErrorMessage> +`ENV-ERROR <ErrorMessage>` The "ENV-ERROR" message is used to signal the PT proxy's failure to parse the configuration environment variables (3.2). @@ -254,18 +256,18 @@ event so any third party can pick them up for debugging. The format of the message: -LOG SEVERITY=Severity MESSAGE=Message +`LOG SEVERITY=Severity MESSAGE=Message` The SEVERITY value indicate at which logging level the message applies. The accepted values for <Severity> are: error, warning, notice, info, debug The MESSAGE value is a human readable string formatted by the PT. The -<Message> contains the log message which can be a String or CString (see +`<Message>` contains the log message which can be a String or CString (see section 2 in control-spec.txt). Example: -LOG SEVERITY=debug MESSAGE="Connected to bridge A" +`LOG SEVERITY=debug MESSAGE="Connected to bridge A"` <a id="pt-spec.txt-3.3.5"></a> ### Pluggable Transport Status Message @@ -275,20 +277,21 @@ parent process via stdout or stderr any status messages. The format of the message: -STATUS TRANSPORT=Transport <K_1>=<V_1> [<K_2>=<V_2> ...] +`STATUS TRANSPORT=Transport <K_1>=<V_1> [<K_2>=<V_2> ...]` The TRANSPORT value indicates a hint on what the PT is such has the name or the protocol used for instance. As an example, obfs4proxy would use "obfs4". Thus, the Transport value can be anything the PT itself defines and it can be a String or CString (see section 2 in control-spec.txt). -The <K_n>=<V_n> values are specific to the PT and there has to be at least +The `<K_n>=<V_n>` values are specific to the PT and there has to be at least one. They are messages that reflects the status that the PT wants to -report. <V_n> can be a String or CString. +report. `<V_n>` can be a String or CString. Examples (fictional): +```text STATUS TRANSPORT=obfs4 ADDRESS=198.51.100.123:1234 CONNECT=Success STATUS TRANSPORT=obfs4 ADDRESS=198.51.100.222:2222 CONNECT=Failed FINGERPRINT=<Fingerprint> ERRSTR="Connection refused" STATUS TRANSPORT=trebuchet ADDRESS=198.51.100.15:443 PERCENT=42 - +``` |