From 3cd7716900e9e0712fb0ee4313979b37b172c4aa Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Thu, 12 Oct 2023 21:46:51 -0400 Subject: Update more things that looked like html tags in the markdown --- spec/bridgedb-spec.md | 8 +++---- spec/control-spec/implementation-notes.md | 5 ++-- spec/dir-spec/directory-cache-operation.md | 8 ++++--- spec/dir-spec/exchanging-votes.md | 10 ++++---- spec/dir-spec/serving-bandwidth-list-files.md | 20 ++++++++-------- spec/ext-orport-spec.md | 4 ++-- spec/guard-spec/algorithm.md | 26 ++++++++++----------- ...luggable-transport-configuration-environment.md | 20 ++++++++-------- ...le-transport-to-parent-process-communication.md | 27 ++++++++++++---------- ...deriving-blinded-keys-subcredentials-subcred.md | 6 ++--- 10 files changed, 71 insertions(+), 63 deletions(-) diff --git a/spec/bridgedb-spec.md b/spec/bridgedb-spec.md index fc95399..8572d8f 100644 --- a/spec/bridgedb-spec.md +++ b/spec/bridgedb-spec.md @@ -390,20 +390,20 @@ After bridges are selected using one of the methods described in Sections 4 - 6, they are output in one of two formats. Bridges are formatted as: - NL +` NL` Pluggable transports are formatted as: - SP [SP arglist] NL +` SP [SP arglist] NL` where arglist is an optional space-separated list of key-value pairs in the form of k=v. Previously, each line was prepended with the "bridge" keyword, such as -"bridge" SP NL +`"bridge" SP NL` -"bridge" SP SP [SP arglist] NL +`"bridge" SP SP [SP arglist] NL` # We don't do this anymore because Vidalia and TorLauncher don't expect it. # See the commit message for b70347a9c5fd769c6d5d0c0eb5171ace2999a736. diff --git a/spec/control-spec/implementation-notes.md b/spec/control-spec/implementation-notes.md index 1a610bb..8340a94 100644 --- a/spec/control-spec/implementation-notes.md +++ b/spec/control-spec/implementation-notes.md @@ -47,9 +47,10 @@ This is then encoded in hexadecimal, prefixed by the indicator sequence ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ salt hashed value indicator +``` - You can generate the salt of a password by calling - +You can generate the salt of a password by calling +``` 'tor --hash-password ' ``` diff --git a/spec/dir-spec/directory-cache-operation.md b/spec/dir-spec/directory-cache-operation.md index 6003d64..ed14fc2 100644 --- a/spec/dir-spec/directory-cache-operation.md +++ b/spec/dir-spec/directory-cache-operation.md @@ -62,12 +62,12 @@ descriptor seemed newest.) Directory mirrors should fetch, cache, and serve each microdescriptor from the authorities. -The microdescriptors with base64 hashes ,, are available +The microdescriptors with base64 hashes ``, ``, `` are available at: -http:///tor/micro/d/--[.z] +`http:///tor/micro/d/--[.z]` - are base64 encoded with trailing =s omitted for size and for +`` are base64 encoded with trailing =s omitted for size and for consistency with the microdescriptor consensus format. -s are used instead of +s to separate items, since the + character is used in base64 encoding. @@ -143,8 +143,10 @@ send that diff instead of the specified consensus. Caches also serve diffs from the URIs: +``` /tor/status-vote/current/consensus/diff//.z /tor/status-vote/current/consensus-/diff//.z +``` where FLAVOR is the consensus flavor, defaulting to "ns", and FPRLIST is +-separated list of recognized authority identity diff --git a/spec/dir-spec/exchanging-votes.md b/spec/dir-spec/exchanging-votes.md index 7c42ad4..4bc6740 100644 --- a/spec/dir-spec/exchanging-votes.md +++ b/spec/dir-spec/exchanging-votes.md @@ -22,11 +22,11 @@ An authority SHOULD publish its vote immediately at the start of each voting period (minus VoteSeconds+DistSeconds). It does this by making it available at -http:///tor/status-vote/next/authority.z +`http:///tor/status-vote/next/authority.z` and sending it in an HTTP POST request to each other authority at the URL -http:///tor/post/vote +`http:///tor/post/vote` If, at the start of the voting period, minus DistSeconds, an authority does not have a current statement from another authority, the first @@ -35,14 +35,14 @@ authority downloads the other's statement. Once an authority has a vote from another authority, it makes it available at -http:///tor/status-vote/next/.z +`http:///tor/status-vote/next/.z` where is the fingerprint of the other authority's identity key. And at -http:///tor/status-vote/next/d/.z +`http:///tor/status-vote/next/d/.z` -where is the digest of the vote document. +where `` is the digest of the vote document. Also, once an authority receives a vote from another authority, it examines it for new descriptors and fetches them from that authority. diff --git a/spec/dir-spec/serving-bandwidth-list-files.md b/spec/dir-spec/serving-bandwidth-list-files.md index 8e7f970..531dc2b 100644 --- a/spec/dir-spec/serving-bandwidth-list-files.md +++ b/spec/dir-spec/serving-bandwidth-list-files.md @@ -4,7 +4,7 @@ If an authority has used a bandwidth list file to generate a vote document it SHOULD make it available at -http:///tor/status-vote/next/bandwidth.z +`http:///tor/status-vote/next/bandwidth.z` at the start of each voting period. @@ -15,7 +15,7 @@ authorities available. If an authority makes this file available, it MUST be the bandwidth file used to create the vote document available at -http:///tor/status-vote/next/authority.z +`http:///tor/status-vote/next/authority.z` To avoid inconsistent reads, authorities SHOULD only read the bandwidth file once per voting period. Further processing and serving SHOULD use a @@ -84,7 +84,7 @@ Given a set of votes, authorities compute the contents of the consensus. The consensus status, along with as many signatures as the server currently knows (see section 3.10 below), should be available at -http:///tor/status-vote/next/consensus.z +`http:///tor/status-vote/next/consensus.z` The contents of the consensus document are as follows: @@ -150,7 +150,7 @@ vote's dir-source line. of the authorities who care about that flag. * Two router entries are "the same" if they have the same - tuple. + (descriptor digest, published time, nickname, IP, ports> tuple. We choose the tuple for a given router as whichever tuple appears for that router in the most votes. We break ties first in favor of the more recently published, then in favor of smaller server @@ -758,14 +758,14 @@ Once an authority has computed and signed a consensus network status, it should send its detached signature to each other authority in an HTTP POST request to the URL: -http:///tor/post/consensus-signature +`http:///tor/post/consensus-signature` [XXX Note why we support push-and-then-pull.] All of the detached signatures it knows for consensus status should be available at: -http:///tor/status-vote/next/consensus-signatures.z +`http:///tor/status-vote/next/consensus-signatures.z` Assuming full connectivity, every authority should compute and sign the same consensus including any flavors in each period. Therefore, it @@ -835,11 +835,11 @@ The voting period ends at the valid-after time. If the consensus has been signed by a majority of authorities, these documents are made available at -http:///tor/status-vote/current/consensus.z +`http:///tor/status-vote/current/consensus.z` and -http:///tor/status-vote/current/consensus-signatures.z +`http:///tor/status-vote/current/consensus-signatures.z` ```text [XXX current/consensus-signatures is not currently implemented, as it @@ -849,20 +849,22 @@ http:///tor/status-vote/current/consensus-signatures.z consensuses.] The other vote documents are analogously made available under -``` http:///tor/status-vote/current/authority.z http:///tor/status-vote/current/.z http:///tor/status-vote/current/d/.z http:///tor/status-vote/current/bandwidth.z +``` once the voting period ends, regardless of the number of signatures. The authorities serve another consensus of each flavor "F" from the locations +``` /tor/status-vote/(current|next)/consensus-F.z. and /tor/status-vote/(current|next)/consensus-F/+....z. +``` The standard URLs for bandwidth list files first-appeared in Tor 0.3.5. diff --git a/spec/ext-orport-spec.md b/spec/ext-orport-spec.md index 7a3a50b..d8688c5 100644 --- a/spec/ext-orport-spec.md +++ b/spec/ext-orport-spec.md @@ -83,9 +83,9 @@ The location of the cookie can be overridden by using the configuration file parameter ExtORPortCookieAuthFile, which is defined as: -ExtORPortCookieAuthFile +`ExtORPortCookieAuthFile ` -where is a filesystem path. +where `` is a filesystem path. ### Cookie-file format diff --git a/spec/guard-spec/algorithm.md b/spec/guard-spec/algorithm.md index acdf343..0f04f31 100644 --- a/spec/guard-spec/algorithm.md +++ b/spec/guard-spec/algorithm.md @@ -157,7 +157,7 @@ of the following are true: We have an additional subset, {set:USABLE_FILTERED_GUARDS}, which is defined to be the subset of {FILTERED_GUARDS} where -{is_reachable} is or . +{is_reachable} is `` or ``. We try to maintain a requirement that {USABLE_FILTERED_GUARDS} contain at least {MIN_FILTERED_SAMPLE} elements: @@ -278,13 +278,13 @@ usable after all. (We run this process as frequently as needed. It can be done once a second, or just-in-time.) -If a primary sampled guard's {is_reachable} status is , then -we decide whether to update its {is_reachable} status to +If a primary sampled guard's {is_reachable} status is ``, then +we decide whether to update its {is_reachable} status to `` based on its {last_tried_connect} time, its {failing_since} time, and the {PRIMARY_GUARDS_RETRY_SCHED} schedule. -If a non-primary sampled guard's {is_reachable} status is , then -we decide whether to update its {is_reachable} status to +If a non-primary sampled guard's {is_reachable} status is ``, then +we decide whether to update its {is_reachable} status to `` based on its {last_tried_connect} time, its {failing_since} time, and the {GUARDS_RETRY_SCHED} schedule. @@ -306,9 +306,9 @@ Every origin circuit is now in one of these states: . ``` -You may only attach streams to circuits. +You may only attach streams to `` circuits. (Additionally, you may only send RENDEZVOUS cells, ESTABLISH_INTRO -cells, and INTRODUCE cells on circuits.) +cells, and INTRODUCE cells on `` circuits.) The per-circuit state machine is: @@ -468,8 +468,8 @@ See [SELECTING] above for rationale. ## Updating the list of waiting circuits [Section:UPDATE_WAITING] We run this procedure whenever it's possible that a - circuit might be ready to be called -. +`` circuit might be ready to be called +``. ```text * If any circuit C1 is , AND: @@ -498,9 +498,9 @@ immediately (if we're sure that it's the best we can do), or we might want to wait a little while to see if some other circuit which we like better will finish. -When we mark a circuit , we don't close the +When we mark a circuit ``, we don't close the lower-priority circuits immediately: we might decide to use -them after all if the circuit goes down before +them after all if the `` circuit goes down before {NONPRIMARY_GUARD_IDLE_TIMEOUT} seconds. @@ -574,8 +574,8 @@ We generate a new circuit when we don't have enough circuits either built or in-progress to handle a given stream, or an expected stream. -For the purpose of this rule, we say that -circuits are neither built nor in-progress; that +For the purpose of this rule, we say that `` +circuits are neither built nor in-progress; that `` circuits are built; and that the other states are in-progress. ```text 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: -://[[:][@]:. +`://[[:][@]:`. 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 : pairs, where -is a PT name and is a k=v string value with options +semicolon-separated list of `:` pairs, where `` +is a PT name and `` 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 - pairs, where is -a PT name and is the
: on which it +A comma separated list of `-` pairs, where `` is +a PT name and `` is the `
:` 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
MAY be a locally scoped address as long as port +The `
` MAY be a locally scoped address as long as port forwarding is done externally. -The
: combination MUST be an IP address +The `
:` combination MUST be an IP address supported by `bind()`, and MUST NOT be a host name. Applications MUST NOT set more than one
: pair per PT name. -If there is no specific
: combination to be +If there is no specific `
:` 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 -
:. +`
:`. 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
:. +as an `
:`. 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 ::= ::= | ::= @@ -12,6 +13,7 @@ via writing NL-terminated lines to stdout. The line metaformat is: ::= ::= ::= +``` 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 +`VERSION-ERROR ` 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 SHOULD be set to "no-version" for +The `` 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 +`VERSION ` 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 +`ENV-ERROR ` 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 are: error, warning, notice, info, debug The MESSAGE value is a human readable string formatted by the PT. The - contains the log message which can be a String or CString (see +`` 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"` ### 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 = [= ...] +`STATUS TRANSPORT=Transport = [= ...]` 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 = values are specific to the PT and there has to be at least +The `=` 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. can be a String or CString. +report. `` 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= ERRSTR="Connection refused" STATUS TRANSPORT=trebuchet ADDRESS=198.51.100.15:443 PERCENT=42 - +``` diff --git a/spec/rend-spec-v3/deriving-blinded-keys-subcredentials-subcred.md b/spec/rend-spec-v3/deriving-blinded-keys-subcredentials-subcred.md index 586d9a5..b98f1ae 100644 --- a/spec/rend-spec-v3/deriving-blinded-keys-subcredentials-subcred.md +++ b/spec/rend-spec-v3/deriving-blinded-keys-subcredentials-subcred.md @@ -371,10 +371,10 @@ the time period has changed). ### URLs for anonymous uploading and downloading Hidden service descriptors conforming to this specification are uploaded -with an HTTP POST request to the URL /tor/hs//publish relative to +with an HTTP POST request to the URL `/tor/hs//publish` relative to the hidden service directory's root, and downloaded with an HTTP GET -request for the URL /tor/hs// where is a base64 encoding of -the hidden service's blinded public key and is the protocol +request for the URL `/tor/hs//` where `` is a base64 encoding of +the hidden service's blinded public key and `` is the protocol version which is "3" in this case. These requests must be made anonymously, on circuits not used for -- cgit v1.2.3-54-g00ecf