diff options
29 files changed, 740 insertions, 238 deletions
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index d40f0e1..6f56955 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -49,4 +49,4 @@ pages: paths: - public only: - - master + - main diff --git a/control-spec.txt b/control-spec.txt index 0e2add3..af0368a 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -2425,6 +2425,14 @@ Table of Contents "DETACHED" / ; Detached from circuit; still retriable "CONTROLLER_WAIT" ; Waiting for controller to use ATTACHSTREAM ; (new in 0.4.5.1-alpha) + "XOFF_SENT" ; XOFF has been sent for this stream + ; (new in 0.4.7.5-alpha) + "XOFF_RECV" ; XOFF has been received for this stream + ; (new in 0.4.7.5-alpha) + "XON_SENT" ; XON has been sent for this stream + ; (new in 0.4.7.5-alpha) + "XON_RECV" ; XON has been received for this stream + ; (new in 0.4.7.5-alpha) Target = TargetAddress ":" Port Port = an integer from 0 to 65535 inclusive @@ -3430,14 +3438,21 @@ Table of Contents "WRITTEN=" BytesWritten SP "TIME=" Time SP "DELIVERED_READ=" DeliveredBytesRead SP "OVERHEAD_READ=" OverheadBytesRead SP - "DELIVERED_WRITTEN=" DeliveredBytesWritten CRLF + "DELIVERED_WRITTEN=" DeliveredBytesWritten SP "OVERHEAD_WRITTEN=" OverheadBytesWritten SP + "SS=" SlowStartState SP + "CWND=" CWNDCells SP + "RTT=" RTTMilliseconds SP + "MIN_RTT=" RTTMilliseconds CRLF BytesRead = 1*DIGIT BytesWritten = 1*DIGIT OverheadBytesRead = 1*DIGIT OverheadBytesWritten = 1*DIGIT DeliveredBytesRead = 1*DIGIT DeliveredBytesWritten = 1*DIGIT + SlowStartState = 0 or 1 + CWNDCells = 1*DIGIT + RTTMilliseconds= 1*DIGIT Time = ISOTime2Frac BytesRead and BytesWritten are the number of bytes read and written @@ -3465,6 +3480,16 @@ Table of Contents The Time field is provided only in versions 0.3.2.1-alpha and later. It records when Tor created the bandwidth event. + The SS, CWND, RTT, and MIN_RTT fields are present only if the circuit + has negotiated congestion control to an onion service or Exit hop (any + intermediate leaky pipe congestion control hops are not examined here). + SS provides an indication if the circuit is in slow start (1), or not (0). + CWND is the size of the congestion window in terms of number of cells. + RTT is the N_EWMA smoothed current RTT value, and MIN_RTT is the minimum + RTT value of the circuit. The SS and CWND fields apply only to the + upstream direction of the circuit. The slow start state and CWND values + of the other endpoint may be different. + These events are generated about once per second per circuit; no events are generated for circuits that had no attached stream writing or reading. @@ -3474,6 +3499,8 @@ Table of Contents [DELIVERED_READ, OVERHEAD_READ, DELIVERED_WRITTEN, and OVERHEAD_WRITTEN were added in Tor 0.3.4.0-alpha] + [SS, CWND, RTT, and MIN_RTT were added in Tor 0.4.7.5-alpha] + 4.1.23. Per-circuit cell stats The syntax is: diff --git a/dir-spec.txt b/dir-spec.txt index 1cf3665..0de986f 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -711,7 +711,6 @@ Table of Contents - Any OOM invocation due to memory pressure - Any ntor onionskins are dropped - TCP port exhaustion - - DNS timeout reached The timestamp is when at least one metrics was detected. It should always be at the hour and thus, as an example, "2020-01-10 13:00:00" is an @@ -1331,6 +1330,8 @@ Table of Contents is first added after the relay has been running for at least 24 hours. + (Introduced in tor-0.4.6.1-alpha) + "hidserv-rend-relayed-cells" SP NUM SP key=val SP key=val ... NL [At most once.] "hidserv-rend-v3-relayed-cells" SP NUM SP key=val SP key=val ... NL @@ -1351,6 +1352,8 @@ Table of Contents integer and included as 'NUM'. Note that the overall reported value can be negative. + (Introduced in tor-0.4.6.1-alpha) + "hidserv-dir-onions-seen" SP NUM SP key=val SP key=val ... NL [At most once.] "hidserv-dir-v3-onions-seen" SP NUM SP key=val SP key=val ... NL @@ -1366,6 +1369,8 @@ Table of Contents of this line. Note that the overall reported value can be negative. + (Introduced in tor-0.4.6.1-alpha) + "transport" transportname address:port [arglist] NL [Any number.] @@ -2330,6 +2335,11 @@ Table of Contents "Fast" if the router is suitable for high-bandwidth circuits. "Guard" if the router is suitable for use as an entry guard. "HSDir" if the router is considered a v2 hidden service directory. + "MiddleOnly" if the router is considered unsuitable for + usage other than as a middle relay. Clients do not need + to handle this option, since when it is present, the authorities + will automatically vote against flags that would make the router + usable in other positions. (Since 0.4.7.2-alpha.) "NoEdConsensus" if any Ed25519 key in the router's descriptor or microdescriptor does not reflect authority consensus. "Stable" if the router is suitable for long-lived circuits. @@ -2639,6 +2649,13 @@ Table of Contents authority believes that it's been up for at least 96 hours (or the current value of MinUptimeHidServDirectoryV2). + "MiddleOnly" -- An authority should vote for this flag if it believes + that a relay is unsuitable for use except as a middle relay. When + voting for this flag, the authority should also vote against "Exit", + "Guard", "HsDir", and "V2Dir". When voting for this flag, if the + authority votes on the "BadExit" flag, the authority should vote in + favor of "BadExit". (This flag was added in 0.4.7.2-alpha.) + "NoEdConsensus" -- authorities should not vote on this flag; it is produced as part of the consensus for consensus method 22 or later. @@ -2958,6 +2975,13 @@ Table of Contents "bwweightscale" and "maxunmeasuredbw" parameters correctly when computing votes. + * If consensus method 32 or later is used, authorities handle the + "MiddleOnly" flag specially when computing a consensus. When the + voters agree to include "MiddleOnly" in a routerstatus, they + automatically remove "Exit", "Guard", "V2Dir", and "HSDir". If + the BadExit flag is included in the consensus, they automatically + add it to the routerstatus. + * If consensus method 33 or later is used, and the consensus flavor is "microdesc", then the "Publication" field in the "r" line is set to "2038-01-01 00:00:00". @@ -4167,10 +4191,20 @@ C. Converting a curve25519 public key to an ed25519 public key [Recomputing the sign bit from the private key every time sounds rather strange and inefficient to me… —isis] - Alternatively, without access to the corresponding ed25519 private - key, one may use the Montgomery u-coordinate to recover the - Montgomery v-coordinate by computing the right-hand side of the - Montgomery curve equation: + Note that in addition to its coordinates, an expanded Ed25519 private key + also has a 32-byte random value, "prefix", used to compute internal `r` + values in the signature. For security, this prefix value should be + derived deterministically from the curve25519 key. The Tor + implementation derives it as SHA512(private_key | STR)[0..32], where + STR is the nul-terminated string: + + "Derive high part of ed25519 key from curve25519 key\0" + + + On the client side, where there is no access to the curve25519 private + keys, one may use the curve25519 public key's Montgomery u-coordinate to + recover the Montgomery v-coordinate by computing the right-hand side of + the Montgomery curve equation: bv^2 = u(u^2 + au +1) diff --git a/param-spec.txt b/param-spec.txt index 429ec13..67c809d 100644 --- a/param-spec.txt +++ b/param-spec.txt @@ -17,7 +17,6 @@ Table of Contents 9. Denial-of-service parameters 10. Padding-related parameters 11. Guard-related parameters - 12. Relay behavior X. Obsolete parameters 1. Network protocol parameters @@ -197,6 +196,7 @@ Table of Contents represent decimal point. As an example, a value of 1000 means 1%. Min: 0. Max: 100000. Default: 1000. First-appeared: 0.4.6.8 + Deprecated: 0.4.7.3-alpha-dev "overload_dns_timeout_period_secs" -- This value is the period in seconds of the DNS timeout measurements (the N in the @@ -205,6 +205,46 @@ Table of Contents assessment on the overload general signal with regards to DNS timeouts. Min: 0. Max: 2147483647. Default: 600 First-appeared: 0.4.6.8 + Deprecated: 0.4.7.3-alpha-dev + + "overload_onionskin_ntor_scale_percent" -- This value is a percentage of + how many onionskin ntor drop over N seconds we accept before reporting the + overload general state. It is scaled by a factor of 1000 in order to be + able to represent decimal point. As an example, a value of 1000 means 1%. + Min: 0. Max: 100000. Default: 1000. + First-appeared: 0.4.7.5-alpha + + "overload_onionskin_ntor_period_secs" -- This value is the period in + seconds of the onionskin ntor overload measurements (the N in the + "overload_onionskin_ntor_scale_percent" parameter). For this amount of + seconds, we will gather onionskin ntor statistics and at the end, we'll do + an assessment on the overload general signal. + Min: 0. Max: 2147483647. Default: 21600 (6 hours) + First-appeared: 0.4.7.5-alpha + + "assume-reachable" -- If true, relays should publish descriptors + even when they cannot make a connection to their IPv4 ORPort. + Min: 0. Max: 1. Default: 0. + First appeared: 0.4.5.1-alpha. + + "assume-reachable-ipv6" -- If true, relays should publish + descriptors even when they cannot make a connection to their IPv6 + ORPort. + Min: 0. Max: 1. Default: 0. + First appeared: 0.4.5.1-alpha. + + "exit_dns_timeout" -- The time in milliseconds an Exit sets libevent to + wait before it considers the DNS timed out. The corresponding libevent + option is "timeout:". + Min: 1. Max: 120000. Default: 1000 (1sec) + First appeared: 0.4.7.5-alpha. + + "exit_dns_num_attempts" -- How many attempts _after the first_ should an + Exit should try a timing-out DNS query before calling it hopeless? (Each of + these attempts will wait for "exit_dns_timeout" independently). The + corresponding libevent option is "attempts:". + Min: 0. Max: 255. Default: 2 + First appeared: 0.4.7.5-alpha. 8. V3 onion service parameters @@ -422,19 +462,6 @@ Table of Contents Min: 1. Max: 3650. Default: 20. First appeared: 0.3.0 -12. Relay behavior - - "assume-reachable" -- If true, relays should publish descriptors - even when they cannot make a connection to their IPv4 ORPort. - Min: 0. Max: 1. Default: 0. - First appeared: 0.4.5.1-alpha. - - "assume-reachable-ipv6" -- If true, relays should publish - descriptors even when they cannot make a connection to their IPv6 - ORPort. - Min: 0. Max: 1. Default: 0. - First appeared: 0.4.5.1-alpha. - X. Obsolete parameters "NumDirectoryGuards", "NumEntryGuards" -- Number of guard nodes diff --git a/path-spec.txt b/path-spec.txt index 4422be4..33d50e5 100644 --- a/path-spec.txt +++ b/path-spec.txt @@ -633,8 +633,8 @@ Tables of Contents Default: 20 Min: 3 Max: 1000 - Effect: This is the number of circuit build times to keep track of - for the following option. + Effect: This is the number of circuit build outcomes (success vs + timeout) to keep track of for the following option. cbtmaxtimeouts Default: 18 @@ -644,6 +644,10 @@ Tables of Contents circuit attempts, the client should discard all of its history and begin learning a fresh timeout value. + Note that if this parameter's value is greater than the value + of 'cbtrecentcount', then the history will never be + discarded because of this feature. + cbtmincircs Default: 100 Min: 1 @@ -651,6 +655,12 @@ Tables of Contents Effect: This is the minimum number of circuits to build before computing a timeout. + Note that if this parameter's value is higher than 1000 (the + number of time observations that a client keeps in its + circular buffer), circuit build timeout calculation is + effectively disabled, and the default timeouts are used + indefinitely. + cbtquantile Default: 80 Min: 10 diff --git a/proposals/000-index.txt b/proposals/000-index.txt index 41bf901..e20fea8 100644 --- a/proposals/000-index.txt +++ b/proposals/000-index.txt @@ -80,7 +80,7 @@ Proposals by number: 157 Make certificate downloads specific [CLOSED] 158 Clients download consensus + microdescriptors [CLOSED] 159 Exit Scanning [INFORMATIONAL] -160 Authorities vote for bandwidth offsets in consensus [FINISHED] +160 Authorities vote for bandwidth offsets in consensus [CLOSED] 161 Computing Bandwidth Adjustments [CLOSED] 162 Publish the consensus in multiple flavors [CLOSED] 163 Detecting whether a connection comes from a client [SUPERSEDED] @@ -152,7 +152,7 @@ Proposals by number: 229 Further SOCKS5 extensions [REJECTED] 230 How to change RSA1024 relay identity keys [OBSOLETE] 231 Migrating authority RSA1024 identity keys [OBSOLETE] -232 Pluggable Transport through SOCKS proxy [FINISHED] +232 Pluggable Transport through SOCKS proxy [CLOSED] 233 Making Tor2Web mode faster [REJECTED] 234 Adding remittance field to directory specification [REJECTED] 235 Stop assigning (and eventually supporting) the Named flag [CLOSED] @@ -162,7 +162,7 @@ Proposals by number: 239 Consensus Hash Chaining [OPEN] 240 Early signing key revocation for directory authorities [OPEN] 241 Resisting guard-turnover attacks [REJECTED] -242 Better performance and usability for the MyFamily option [RESERVE] +242 Better performance and usability for the MyFamily option [SUPERSEDED] 243 Give out HSDir flag only to relays with Stable flag [CLOSED] 244 Use RFC5705 Key Exporting in our AUTHENTICATE calls [CLOSED] 245 Deprecating and removing the TAP circuit extension protocol [NEEDS-REVISION] @@ -193,7 +193,7 @@ Proposals by number: 270 RebelAlliance: A Post-Quantum Secure Hybrid Handshake Based on NewHope [OBSOLETE] 271 Another algorithm for guard selection [CLOSED] 272 Listed routers should be Valid, Running, and treated as such [CLOSED] -273 Exit relay pinning for web services [DRAFT] +273 Exit relay pinning for web services [RESERVE] 274 Rotate onion keys less frequently [CLOSED] 275 Stop including meaningful "published" time in microdescriptor consensus [CLOSED] 276 Report bandwidth with lower granularity in consensus documents [DEAD] @@ -202,13 +202,13 @@ Proposals by number: 279 A Name System API for Tor Onion Services [NEEDS-REVISION] 280 Privacy-Preserving Statistics with Privcount in Tor [SUPERSEDED] 281 Downloading microdescriptors in bulk [RESERVE] -282 Remove "Named" and "Unnamed" handling from consensus voting [FINISHED] +282 Remove "Named" and "Unnamed" handling from consensus voting [ACCEPTED] 283 Move IPv6 ORPorts from microdescriptors to the microdesc consensus [CLOSED] 284 Hidden Service v3 Control Port [CLOSED] 285 Directory documents should be standardized as UTF-8 [ACCEPTED] 286 Controller APIs for hibernation access on mobile [REJECTED] 287 Reduce circuit lifetime without overloading the network [OPEN] -288 Privacy-Preserving Statistics with Privcount in Tor (Shamir version) [ACCEPTED] +288 Privacy-Preserving Statistics with Privcount in Tor (Shamir version) [RESERVE] 289 Authenticating sendme cells to mitigate bandwidth attacks [CLOSED] 290 Continuously update consensus methods [META] 291 The move to two guard nodes [NEEDS-REVISION] @@ -221,7 +221,7 @@ Proposals by number: 298 Putting family lines in canonical form [CLOSED] 299 Preferring IPv4 or IPv6 based on IP Version Failure Count [SUPERSEDED] 300 Walking Onions: Scaling and Saving Bandwidth [INFORMATIONAL] -301 Don't include package fingerprints in consensus documents [FINISHED] +301 Don't include package fingerprints in consensus documents [OPEN] 302 Hiding onion service clients using padding [CLOSED] 303 When and how to remove support for protocol versions [OPEN] 304 Extending SOCKS5 Onion Service Error Codes [CLOSED] @@ -230,12 +230,12 @@ Proposals by number: 307 Onion Balance Support for Onion Service v3 [RESERVE] 308 Counter Galois Onion: A New Proposal for Forward-Secure Relay Cryptography [OPEN] 309 Optimistic SOCKS Data [OPEN] -310 Towards load-balancing in Prop 271 [FINISHED] +310 Towards load-balancing in Prop 271 [CLOSED] 311 Tor Relay IPv6 Reachability [ACCEPTED] 312 Tor Relay Automatic IPv6 Address Discovery [ACCEPTED] 313 Tor Relay IPv6 Statistics [ACCEPTED] -314 Allow Markdown for proposal format [FINISHED] -315 Updating the list of fields required in directory documents [OPEN] +314 Allow Markdown for proposal format [CLOSED] +315 Updating the list of fields required in directory documents [CLOSED] 316 FlashFlow: A Secure Speed Test for Tor (Parent Proposal) [DRAFT] 317 Improve security aspects of DNS name resolution [NEEDS-REVISION] 318 Limit protover values to 0-63 [CLOSED] @@ -252,24 +252,23 @@ Proposals by number: 329 Overcoming Tor's Bottlenecks with Traffic Splitting [DRAFT] 330 Modernizing authority contact entries [OPEN] 331 Res tokens: Anonymous Credentials for Onion Service DoS Resilience [DRAFT] -332 Ntor protocol with extra data, version 3 [OPEN] -333 Vanguards lite [DRAFT] -334 A Directory Authority Flag To Mark Relays As Middle-only [OPEN] -335 An authority-only design for MiddleOnly [OPEN] +332 Ntor protocol with extra data, version 3 [ACCEPTED] +333 Vanguards lite [FINISHED] +334 A Directory Authority Flag To Mark Relays As Middle-only [SUPERSEDED] +335 An authority-only design for MiddleOnly [CLOSED] 336 Randomized schedule for guard retries [OPEN] 337 A simpler way to decide, "Is this guard usable?" [OPEN] +338 Use an 8-byte timestamp in NETINFO cells [OPEN] Proposals by status: DRAFT: - 273 Exit relay pinning for web services [for n/a] 294 TLS 1.3 Migration 316 FlashFlow: A Secure Speed Test for Tor (Parent Proposal) 327 A First Take at PoW Over Introduction Circuits 329 Overcoming Tor's Bottlenecks with Traffic Splitting 331 Res tokens: Anonymous Credentials for Onion Service DoS Resilience - 333 Vanguards lite NEEDS-REVISION: 212 Increase Acceptable Consensus Age [for 0.2.4.x+] 219 Support for full DNS and DNSSEC resolution in Tor [for 0.2.5.x] @@ -287,11 +286,11 @@ Proposals by status: 287 Reduce circuit lifetime without overloading the network 295 Using ADL for relay cryptography (solving the crypto-tagging attack) 296 Have Directory Authorities expose raw bandwidth list files + 301 Don't include package fingerprints in consensus documents 303 When and how to remove support for protocol versions 306 A Tor Implementation of IPv6 Happy Eyeballs 308 Counter Galois Onion: A New Proposal for Forward-Secure Relay Cryptography 309 Optimistic SOCKS Data - 315 Updating the list of fields required in directory documents 319 RELAY_FRAGMENT cells 321 Better performance and usability for the MyFamily option (v2) 322 Extending link specifiers to include the directory port @@ -300,19 +299,18 @@ Proposals by status: 325 Packed relay cells: saving space on small commands 326 The "tor-relay" Well-Known Resource Identifier 330 Modernizing authority contact entries - 332 Ntor protocol with extra data, version 3 - 334 A Directory Authority Flag To Mark Relays As Middle-only - 335 An authority-only design for MiddleOnly 336 Randomized schedule for guard retries 337 A simpler way to decide, "Is this guard usable?" + 338 Use an 8-byte timestamp in NETINFO cells ACCEPTED: 265 Load Balancing with Overhead Parameters [for 0.2.9.x] + 282 Remove "Named" and "Unnamed" handling from consensus voting [for 0.3.3.x] 285 Directory documents should be standardized as UTF-8 - 288 Privacy-Preserving Statistics with Privcount in Tor (Shamir version) 292 Mesh-based vanguards 311 Tor Relay IPv6 Reachability 312 Tor Relay Automatic IPv6 Address Discovery 313 Tor Relay IPv6 Statistics + 332 Ntor protocol with extra data, version 3 META: 000 Index of Tor Proposals 001 The Tor Proposal Process @@ -322,13 +320,8 @@ Proposals by status: 257 Refactoring authorities and making them more isolated from the net 290 Continuously update consensus methods FINISHED: - 160 Authorities vote for bandwidth offsets in consensus [for 0.2.1.x] - 232 Pluggable Transport through SOCKS proxy [in 0.2.6] 260 Rendezvous Single Onion Services [in 0.2.9.3-alpha] - 282 Remove "Named" and "Unnamed" handling from consensus voting [for 0.3.3.x] - 301 Don't include package fingerprints in consensus documents - 310 Towards load-balancing in Prop 271 - 314 Allow Markdown for proposal format + 333 Vanguards lite [in 0.4.7.1-alpha] CLOSED: 101 Voting on the Tor Directory System [in 0.2.0.x] 102 Dropping "opt" from the directory format [in 0.2.0.x] @@ -364,6 +357,7 @@ Proposals by status: 155 Four Improvements of Hidden Service Performance [in 0.2.1.x] 157 Make certificate downloads specific [for 0.2.4.x] 158 Clients download consensus + microdescriptors [in 0.2.3.1-alpha] + 160 Authorities vote for bandwidth offsets in consensus [for 0.2.1.x] 161 Computing Bandwidth Adjustments [for 0.2.1.x] 162 Publish the consensus in multiple flavors [in 0.2.3.1-alpha] 166 Including Network Statistics in Extra-Info Documents [for 0.2.2] @@ -399,6 +393,7 @@ Proposals by status: 224 Next-Generation Hidden Services in Tor [in 0.3.2.1-alpha] 227 Include package fingerprints in consensus documents [in 0.2.6.3-alpha] 228 Cross-certifying identity keys with onion keys + 232 Pluggable Transport through SOCKS proxy [in 0.2.6] 235 Stop assigning (and eventually supporting) the Named flag [in 0.2.6, 0.2.7] 236 The move to a single guard node 237 All relays are directory servers [for 0.2.7.x] @@ -423,8 +418,12 @@ Proposals by status: 302 Hiding onion service clients using padding [in 0.4.1.1-alpha] 304 Extending SOCKS5 Onion Service Error Codes 305 ESTABLISH_INTRO Cell DoS Defense Extension + 310 Towards load-balancing in Prop 271 + 314 Allow Markdown for proposal format + 315 Updating the list of fields required in directory documents [in 0.4.5.1-alpha] 318 Limit protover values to 0-63 [in 0.4.5.1-alpha] 328 Make Relays Report When They Are Overloaded + 335 An authority-only design for MiddleOnly [in 0.4.7.2-alpha] SUPERSEDED: 112 Bring Back Pathlen Coin Weight 113 Simplifying directory authority administration @@ -444,12 +443,14 @@ Proposals by status: 194 Mnemonic .onion URLs 210 Faster Headless Consensus Bootstrapping 225 Strawman proposal: commit-and-reveal shared rng + 242 Better performance and usability for the MyFamily option 247 Defending Against Guard Discovery Attacks using Vanguards 249 Allow CREATE cells with >505 bytes of handshake data 252 Single Onion Services 266 Removing current obsolete clients from the Tor network 280 Privacy-Preserving Statistics with Privcount in Tor 299 Preferring IPv4 or IPv6 based on IP Version Failure Count + 334 A Directory Authority Flag To Mark Relays As Middle-only DEAD: 100 Tor Unreliable Datagram Extension Proposal 115 Two Hop Paths @@ -508,11 +509,12 @@ Proposals by status: 211 Internal Mapaddress for Tor Configuration Testing [for 0.2.4.x+] 223 Ace: Improved circuit-creation key exchange 226 "Scalability and Stability Improvements to BridgeDB: Switching to a Distributed Database System and RDBMS" - 242 Better performance and usability for the MyFamily option 255 Controller features to allow for load-balancing hidden services 256 Key revocation for relays and authorities 262 Re-keying live circuits with new cryptographic material + 273 Exit relay pinning for web services [for n/a] 281 Downloading microdescriptors in bulk + 288 Privacy-Preserving Statistics with Privcount in Tor (Shamir version) 307 Onion Balance Support for Onion Service v3 INFORMATIONAL: 159 Exit Scanning diff --git a/proposals/001-process.txt b/proposals/001-process.txt index d6717bf..7211c3b 100644 --- a/proposals/001-process.txt +++ b/proposals/001-process.txt @@ -145,6 +145,12 @@ What should go in a proposal: can avoid really expensive performance regressions, and so we can avoid wasting time on insignificant gains. +How to format proposals: + + Proposals may be written in plain text (like this one), or in Markdown. + If using Markdown, the header must be wrapped in triple-backtick ("```") + lines. Whenever possible, we prefer the Commonmark dialect of Markdown. + Proposal status: Open: A proposal under discussion. diff --git a/proposals/160-bandwidth-offset.txt b/proposals/160-bandwidth-offset.txt index de9c6e4..8ad4d18 100644 --- a/proposals/160-bandwidth-offset.txt +++ b/proposals/160-bandwidth-offset.txt @@ -2,7 +2,7 @@ Filename: 160-bandwidth-offset.txt Title: Authorities vote for bandwidth offsets in consensus Author: Roger Dingledine Created: 4-May-2009 -Status: Finished +Status: Closed Target: 0.2.1.x 1. Motivation diff --git a/proposals/232-pluggable-transports-through-proxy.txt b/proposals/232-pluggable-transports-through-proxy.txt index f4fa1ce..03cee07 100644 --- a/proposals/232-pluggable-transports-through-proxy.txt +++ b/proposals/232-pluggable-transports-through-proxy.txt @@ -2,7 +2,7 @@ Filename: 232-pluggable-transports-through-proxy.txt Title: Pluggable Transport through SOCKS proxy Author: Arturo Filastò Created: 28 February 2012 -Status: Finished +Status: Closed Implemented-In: 0.2.6 Overview diff --git a/proposals/242-better-families.txt b/proposals/242-better-families.txt index 8a79fa2..5f4ac47 100644 --- a/proposals/242-better-families.txt +++ b/proposals/242-better-families.txt @@ -2,7 +2,8 @@ Filename: 242-better-families.txt Title: Better performance and usability for the MyFamily option Author: Nick Mathewson Created: 2015-02-27 -Status: Reserve +Status: Superseded +Superseded-by: 321-happy-families.md 1. Problem statement. diff --git a/proposals/273-exit-relay-pinning.txt b/proposals/273-exit-relay-pinning.txt index 91c3763..4a83a00 100644 --- a/proposals/273-exit-relay-pinning.txt +++ b/proposals/273-exit-relay-pinning.txt @@ -2,7 +2,7 @@ Filename: 273-exit-relay-pinning.txt Title: Exit relay pinning for web services Author: Philipp Winter, Tobias Pulls, Roya Ensafi, and Nick Feamster Created: 2016-09-22 -Status: Draft +Status: Reserve Target: n/a 0. Overview diff --git a/proposals/282-remove-named-from-consensus.txt b/proposals/282-remove-named-from-consensus.txt index 4c3ba13..7fc28f0 100644 --- a/proposals/282-remove-named-from-consensus.txt +++ b/proposals/282-remove-named-from-consensus.txt @@ -2,7 +2,7 @@ Filename: 282-remove-named-from-consensus.txt Title: Remove "Named" and "Unnamed" handling from consensus voting Author: Nick Mathewson Created: 12-Sep-2017 -Status: Finished +Status: Accepted Target: 0.3.3.x 1. Summary diff --git a/proposals/288-privcount-with-shamir.txt b/proposals/288-privcount-with-shamir.txt index 62faa1d..109c743 100644 --- a/proposals/288-privcount-with-shamir.txt +++ b/proposals/288-privcount-with-shamir.txt @@ -3,7 +3,7 @@ Title: Privacy-Preserving Statistics with Privcount in Tor (Shamir version) Author: Nick Mathewson, Tim Wilson-Brown, Aaron Johnson Created: 1-Dec-2017 Supercedes: 280 -Status: Accepted +Status: Reserve 0. Acknowledgments diff --git a/proposals/301-dont-vote-on-package-fingerprints.txt b/proposals/301-dont-vote-on-package-fingerprints.txt index 0a2f146..8e8b63a 100644 --- a/proposals/301-dont-vote-on-package-fingerprints.txt +++ b/proposals/301-dont-vote-on-package-fingerprints.txt @@ -2,7 +2,7 @@ Filename: 301-dont-vote-on-package-fingerprints.txt Title: Don't include package fingerprints in consensus documents Author: Iain R. Learmonth Created: 2019-02-21 -Status: Finished +Status: Open Ticket: #28465 0. Abstract diff --git a/proposals/310-bandaid-on-guard-selection.txt b/proposals/310-bandaid-on-guard-selection.txt index 74842dc..2001994 100644 --- a/proposals/310-bandaid-on-guard-selection.txt +++ b/proposals/310-bandaid-on-guard-selection.txt @@ -3,7 +3,7 @@ Title: Towards load-balancing in Prop 271 Author: Florentin Rochet, Aaron Johnson et al. Created: 2019-10-27 Supersedes: 271 -Status: Finished +Status: Closed 1. Motivation and Context diff --git a/proposals/314-allow-markdown-proposals.md b/proposals/314-allow-markdown-proposals.md index 99677f0..8469757 100644 --- a/proposals/314-allow-markdown-proposals.md +++ b/proposals/314-allow-markdown-proposals.md @@ -3,7 +3,7 @@ Filename: 314-allow-markdown-proposals.md Title: Allow Markdown for proposal format. Author: Nick Mathewson Created: 23 April 2020 -Status: Finished +Status: Closed ``` # Introduction diff --git a/proposals/315-update-dir-required-fields.txt b/proposals/315-update-dir-required-fields.txt index c22536c..1761a03 100644 --- a/proposals/315-update-dir-required-fields.txt +++ b/proposals/315-update-dir-required-fields.txt @@ -2,7 +2,13 @@ Filename: 315-update-dir-required-fields.txt Title: Updating the list of fields required in directory documents Author: Nick Mathewson Created: 23 April 2020 -Status: Open +Status: Closed +Implemented-In: 0.4.5.1-alpha + +Notes: + + The "hidden-service-dir" field was not made assumed-present; all other + fields were updated. 1. Introduction diff --git a/proposals/321-happy-families.md b/proposals/321-happy-families.md index f9ac7b4..4d8f144 100644 --- a/proposals/321-happy-families.md +++ b/proposals/321-happy-families.md @@ -62,8 +62,10 @@ We add a new entry to microdescriptors: `family-keys`. This line contains one or more space-separated strings describing families to which the node belongs. These strings MUST be sorted in -lexicographic order. Clients MUST NOT depend on any particular property -of these strings. +lexicographic order. These strings MAY be base64-formated nonpadded +ed25519 family keys, or may represent some future encoding. + +Clients SHOULD accept unrecognized key formats. ## Changes to voting algorithm @@ -125,7 +127,9 @@ family if ANY of these is true: in its family line, and B's descriptor lists A in its family line. * Client A has descriptors for A and B, and they both contain the - same entry in their family-keys or family-cert. + same entry in their family-keys or family-cert. (Note that a + family-cert key may match a base64-encoded entry in the family-keys + entry.) ## Migration diff --git a/proposals/324-rtt-congestion-control.txt b/proposals/324-rtt-congestion-control.txt index 36e10e7..78b6789 100644 --- a/proposals/324-rtt-congestion-control.txt +++ b/proposals/324-rtt-congestion-control.txt @@ -51,6 +51,9 @@ be found at: An exhaustive list of citations for further reading is in Section [CITATIONS]. +A glossary of common congestion control acronyms and terminology is in +Section [GLOSSARY]. + 1. Overview [OVERVIEW] @@ -115,15 +118,14 @@ RELAY_COMMAND_SENDME relay cells every CIRCWINDOW_INCREMENT (100) cells of received RELAY_COMMAND_DATA. This allows those endpoints to measure the current circuit RTT, by -measuring the amount of time between sending of every 100th data cell -and the arrival of the SENDME command that the other endpoint -immediately sends to ack that 100th cell. - -Circuits will record the current RTT measurement as a field in their -circuit_t data structure. The current RTT is N-EWMA smoothed[27] over a -'cc_ewma_cwnd_cnt' multiple of congestion window worth of sendme acks. +measuring the amount of time between sending a RELAY_COMMAND_DATA cell +that would trigger a SENDME from the other endpoint, and the arrival of +that SENDME cell. This means that RTT is measured every 'cc_sendme_inc' +data cells. -Circuits will also record the minimum and maximum RTT seen so far. +Circuits will record the minimum and maximum RTT measurement, as well as +a smoothed value of representing the current RTT. The smoothing for the +current RTT is performed as specified in [N_EWMA_SMOOTHING]. Algorithms that make use of this RTT measurement for congestion window update are specified in [CONTROL_ALGORITHMS]. @@ -146,8 +148,8 @@ If the time delta is 0, that is always treated as a clock stall. If we have measured at least 'cc_bwe_min' RTT values or we have successfully exited slow start, then every sendme ACK, the new candidate RTT is compared to -the stored EWMA RTT. If the new RTT is either 100 times larger than the EWMA -RTT, or 100 times smaller than the stored EWMA RTT, then we do not record that +the stored EWMA RTT. If the new RTT is either 5000 times larger than the EWMA +RTT, or 5000 times smaller than the stored EWMA RTT, then we do not record that estimate, and do not update BDP or the congestion control algorithms for that SENDME ack. @@ -157,6 +159,28 @@ have enough data to compute the above heueristics. This cached value is also exported for use by the edge connection rate calculations done by [XON_ADVISORY]. +2.1.2. N_EWMA Smoothing [N_EWMA_SMOOTHING] + +Both RTT estimation and SENDME BDP estimation require smoothing, to +reduce the effects of packet jitter. + +This smoothing is performed using N_EWMA[27], which is an Exponential +Moving Average with alpha = 2/(N+1): + + N_EWMA = BDP*2/(N+1) + N_EWMA_prev*(N-1)/(N+1). + +Flow control rate limiting uses this function + +For both RTT and SENDME BDP estimation, N is the number of SENDME acks +between congestion window updates, divided by the value of consensus +parameter 'cc_ewma_cwnd_pct', and then capped at a max of 'cc_ewma_max', +but always at least 2: + + N = MAX(MIN(CWND_UPDATE_RATE(cc)*cc_ewma_cwnd_pct/100, cc_ewma_max), 2); + +CWND_UPDATE_RATE is normally just round(CWND/cc_sendme_inc), but after +slow start, it is round(CWND/(cc_cwnd_inc_rate*cc_sendme_inc)). + 2.2. SENDME behavior changes We will make four major changes to SENDME behavior to aid in computing @@ -174,10 +198,9 @@ congestion, since the RTT will be measured more often. If experimentation in Shadow shows that more frequent SENDMEs reduce congestion and improve performance but add significant overhead, we can reduce SENDME overhead by allowing SENDME cells to carry stream data, as -well, using Proposal 325. - - TODO: Refer to or include final version of the negotiation proposal for - this: https://gitlab.torproject.org/tpo/core/tor/-/issues/40377 +well, using Proposal 325. The method for negotiating a common value of +cc_sendme_inc on a circuit is covered in [ONION_NEGOTIATION] and +[EXIT_NEGOTIATION]. Third, authenticated SENDMEs can remain as-is in terms of protocol behavior, but will require some implementation updates to account for @@ -294,23 +317,11 @@ BDP. We specify all three because they are all useful in various cases. These cases are broken up and combined to form the Piecewise BDP estimator. -The SENDME estimator is smoothed through N-EWMA averaging on these -estimators[27], to smooth out temporary effects. This is accomplished by using -an EWMA function with alpha = 2/(N+1): - - N_EWMA = BDP*2/(N+1) + N_EWMA_prev*(N-1)/(N+1). - -N is specified in terms of the number of current congestion windows worth of -SENDMEs to average, via consensus parameter 'cc_ewma_cwnd_cnt'. - -The cwnd and inflight estimators also use N-EWMA smoothing in the same way, -but only smooth the current RTT estimate, not the congestion window value. - 3.1.1. SENDME arrival BDP estimation -The most accurate way to estimate BDP is to measure the amount of time between -SENDME acks. In this period of time, we know that the endpoint successfully -received 'cc_sendme_inc' cells. +It is possible to directly measure BDP via the amount of time between SENDME +acks. In this period of time, we know that the endpoint successfully received +'cc_sendme_inc' cells. This means that the bandwidth of the circuit is then calculated as: @@ -343,17 +354,22 @@ truncation, we compute the BDP using multiplication first: BDP = (num_sendmes-1) * cc_sendme_inc * RTT_min / num_sendme_timestamp_delta -Note that the SENDME BDP estimation will only work after two (2) SENDME acks -have been received. Additionally, it tends not to be stable unless at least -five (5) num_sendme's are used, due to ack compression. This is controlled by -the 'cc_bwe_min' consensus parameter. Finally, if [CLOCK_HEURISTICS] have -detected a clock jump or stall, this estimator is not updated. +After all of this, the BDP is smoothed using [N_EWMA_SMOOTHING]. + +This smoothing means that the SENDME BDP estimation will only work after two +(2) SENDME acks have been received. Additionally, it tends not to be stable +unless at least 'cc_bwe_min' sendme's are used. This is controlled by the +'cc_bwe_min' consensus parameter. Finally, if [CLOCK_HEURISTICS] have detected +a clock jump or stall, this estimator is not updated. If all edge connections no longer have data available to send on a circuit and all circuit queues have drained without blocking the local orconn, we stop updating this BDP estimate and discard old timestamps. However, we retain the actual estimator value. +Unfortunately, even after all of this, SENDME BDP estimation proved unreliable +in Shadow simulation, due to ack compression. + 3.1.2. Congestion Window BDP Estimation Assuming that the current congestion window is at or above the current BDP, @@ -422,8 +438,9 @@ and RTT_current. These are measured using the time delta between every measured arbitrarily, so long as it is larger than what we would get from SENDME. -RTT_current is N-EWMA smoothed over 'cc_ewma_cwnd_cnt' congestion windows -worth of SENDME acks. +RTT_current is N-EWMA smoothed over 'cc_ewma_cwnd_pct' percent of +congestion windows worth of SENDME acks, up to a max of 'cc_ewma_max' acks, as +described in [N_EWMA_SMOOTHING]. Recall that BOOTLEG_RTT_TOR emits a congestion signal when the current RTT falls below some fractional threshold ('cc_westwood_rtt_thresh') fraction @@ -502,27 +519,29 @@ Thus, Vegas estimates estimates the queue use caused by congestion as: queue_use = cwnd - BDP -Original TCP Vegas used a cwnd BDP estimator only. However, because the SENDME -BDP estimate is more accurate, and because Piecewise BDP allows us to back off -more when the local OR connection is blocked, we use Piecewise BDP here. - -For testing, we also parameterize this queue_use calculation as a tunable +Original TCP Vegas used a cwnd BDP estimator only. We added the ability to +switch this BDP estimator in the implementation, and experimented with various +options. We also parameterized this queue_use calculation as a tunable weighted average between the cwnd-based BDP estimate and the piecewise -estimate (consensus parameter 'cc_vegas_bdp_mix'). +estimate (consensus parameter 'cc_vegas_bdp_mix'). After much testing of +various ways to compute BDP, we were still unable to do much better than the +original cwnd estimator. So while this capability to change the BDP estimator +remains in the C implementation, we do not expect it to be used. -Additionally, if the local OR connection is blocked at the time of SENDME ack -arrival, this is treated as an immediate congestion signal. +However, it was useful to use a local OR connection block at the time of +SENDME ack arrival, as an immediate congestion signal. -(We can also optionally use the ECN signal described in -ideas/xxx-backward-ecn.txt, to exit Slow Start.) +(As an additional optimization, we could also use the ECN signal described in +ideas/xxx-backward-ecn.txt, but this is not implemented. It is likely only of +any benefit during Slow Start, and even that benefit is likely small.) Congestion signals from RTT, blocked OR connections, or ECN are processed only once per congestion window. This is achieved through the next_cc_event flag, which is initialized to a cwnd worth of SENDME acks, and is decremented each ack. Congestion signals are only evaluated when it reaches 0. -Here is the complete pseudocode for TOR_VEGAS, which is run once per SENDME -ack: +Here is the complete pseudocode for TOR_VEGAS, which is run every time +an endpoint receives a SENDME ack: # Update acked cells inflight -= cc_sendme_inc @@ -543,18 +562,30 @@ ack: if in_slow_start: if queue_use < cc_vegas_gamma and not orconn_blocked: - cwnd = MAX(cwnd * cc_cwnd_inc_pct_ss, BDP) # Exponential or BDP + # Increment by slow start %, or at least 2 sendme_inc's worth + cwnd = cwnd + MAX(cwnd * cc_cwnd_inc_pct_ss, 2*cc_sendme_inc) + # If our BDP estimator thinks the BDP is still larger, use that + cwnd = MAX(cwnd, BDP) else: - cwnd = BDP + cwnd = BDP + cc_vegas_gamma in_slow_start = 0 else: - if queue_use > cc_vegas_beta or orconn_blocked: - cwnd += cc_cwnd_inc - elif queue_use < cc_vegas_alpha: + if queue_use > cc_vegas_delta: + cwnd = BDP + cc_vegas_delta - cc_cwnd_inc + elif queue_use > cc_vegas_beta or orconn_blocked: cwnd -= cc_cwnd_inc + elif queue_use < cc_vegas_alpha: + cwnd += cc_cwnd_inc cwnd = MAX(cwnd, cc_circwindow_min) - next_cc_event = cwnd / (cc_cwnd_inc_rate * cc_sendme_inc) + + # Count the number of sendme acks until next update of cwnd, + # rounded to nearest integer + if in_slow_start: + next_cc_event = round(cwnd / cc_sendme_inc) + else + # Never increment faster in slow start, only steady state. + next_cc_event = round(cwnd / (cc_cwnd_inc_rate * cc_sendme_inc)) 3.4. Tor NOLA: Direct BDP tracker [TOR_NOLA] @@ -1081,6 +1112,11 @@ These are sorted in order of importance to tune, most important first. values, and even the optimal algorithm itself, will likely depend upon how much fixed sendme traffic is in competition. See the algorithm-specific parameters for additional tuning notes. + - Shadow Tuning Results: + Westwood exhibited responsiveness problems, drift, and overshoot. + NOLA exhibited ack compression resulting in over-estimating the + BDP. Vegas, when tuned properly, kept queues low and throughput + high, but even. cc_bwe_min: - Description: @@ -1100,11 +1136,15 @@ These are sorted in order of importance to tune, most important first. when the congestion window is small. If we need small congestion windows, we should also lower cc_sendme_inc, which will get us more frequent acks with less data. + - Shadow Tuning Results: + Regarless of how high this was set, there were still cases where + queues built up, causing BDP over-estimation. As a result, we disable + use of the BDP estimator, and only use the Vegas CWND estimator. cc_sendme_inc: - Description: Specifies how many cells a SENDME acks - - Range: [1, 5000] - - Default: 50 + - Range: [1, 255] + - Default: 31 - Tuning Values: 25,33,50 - Tuning Notes: Increasing this increases overhead, but also increases BDP @@ -1112,14 +1152,22 @@ These are sorted in order of importance to tune, most important first. and the old code sent sendmes at both every 50 cells, and every 100, we can set this as low as 33 to have the same amount of overhead. + - Shadow Tuning Results: + This was optimal at 31-32 cells, which is also the number of + cells that fit in a TLS frame. Much of the rest of Tor has + processing values at 32 cells, as well. + - Consensus Update Notes: + This value MUST only be changed by a factor of 2, every 4 hours. + If greater changes are needed, they MUST be spread out over + multiple consensus updates. cc_cwnd_init: - Description: Initial congestion window for new congestion control Tor clients. This can be set much higher than TCP, since actual TCP to the guard will prevent buffer bloat issues at local routers. - - Range: [100, 10000] - - Default: 500 + - Range: [31, 10000] + - Default: 4*31 - Tuning Values: 150,200,250,500 - Tuning Notes: Higher initial congestion windows allow the algorithms to @@ -1127,10 +1175,16 @@ These are sorted in order of importance to tune, most important first. and latency. Ultimately, the ICW should be set to approximately 'cc_bwe_min'*'cc_sendme_inc', but the presence of competing fixed window clients may require higher values. + - Shadow Tuning Results: + Setting this too high caused excessive cell queues at relays. + 4*31 ended up being a sweet spot. + - Consensus Update Notes: + This value must never be set below cc_sendme_inc. cc_cwnd_min: - Description: The minimum allowed cwnd. - - Range: [cc_sendme_inc, 1000] + - Range: [31, 1000] + - Default: 31 - Tuning Values: [100, 150, 200] - Tuning Notes: If the cwnd falls below cc_sendme_inc, connections can't send @@ -1138,10 +1192,14 @@ These are sorted in order of importance to tune, most important first. cc_bwe_min*cc_sendme_inc, connections can't use SENDME BDP estimates. Likely we want to set this around cc_bwe_min*cc_sendme_inc, but no lower than cc_sendme_inc. + - Shadow Tuning Results: + We set this at 31 cells, the cc_sendme_inc. + - Consensus Update Notes: + This value must never be set below cc_sendme_inc. cc_cwnd_max: - Description: The maximum allowed cwnd. - - Range: [cc_sendme_inc, INT32_MAX] + - Range: [500, INT32_MAX] - Default: INT32_MAX - Tuning Values: [5000, 10000, 20000] - Tuning Notes: @@ -1151,6 +1209,8 @@ These are sorted in order of importance to tune, most important first. queues large enough to cause ack compression should become rare. This parameter exists primarily to verify this in Shadow, but we preserve it as a consensus parameter for emergency use in the live network, as well. + - Shadow Tuning Results: + We kept this at INT32_MAX. circwindow: - Description: Initial congestion window for legacy Tor clients @@ -1175,39 +1235,69 @@ These are sorted in order of importance to tune, most important first. only be updated once every cwnd worth of packets. We may find it better to update more frequently, but this is probably unlikely to help a great deal. + - Shadow Tuning Results: + Increasing this during slow start caused overshoot and excessive + queues. Increasing this after slow start was suboptimal for + performance. We keep this at 1. - cc_ewma_cwnd_cnt: + cc_ewma_cwnd_pct: - Description: This specifies the N in N-EWMA smoothing of RTT and BDP - estimation. It allows us to average these values over 1 - or more congestion windows. - - Range: [1, 100] - - Default: 2 - - Tuning Values: [1,2,3] + estimation, as a percent of the number of SENDME acks + in a congestion window. It allows us to average these RTT + values over a percentage of the congestion window, + capped by 'cc_ewma_max' below, and specified in + [N_EWMA_SMOOTHING]. + - Range: [1, 255] + - Default: 50,100 + - Tuning Values: [25,50,100] - Tuning Notes: Smoothing our estimates reduces the effects of ack compression and other ephemeral network hiccups; changing this much is unlikely to have a huge impact on performance. + - Shadow Tuning Results: + Setting this to 50 seemed to reduce cell queues, but this may also + have impacted performance. + + cc_ewma_max: + - Description: This specifies the max N in N_EWMA smoothing of RTT and BDP + estimation. It allows us to place a cap on the N of EWMA + smoothing, as specified in [N_EWMA_SMOOTHING]. + - Range: [2, INT32_MAX] + - Default: 10 + - Tuning Values: [10,20] + - Shadow Tuning Results: + We ended up needing this to make Vegas more responsive to + congestion, to avoid overloading slow relays. Values of 10 or 20 + were best. cc_cwnd_inc: - Description: How much to increment the congestion window by during steady state, every cwnd. - Range: [1, 1000] - - Default: 50 + - Default: 31 - Tuning Values: 25,50,100 - Tuning Notes: We are unlikely to need to tune this much, but it might be worth trying a couple values. + - Shadow Tuning Results: + Increasing this negatively impacted performance. Keeping it at + cc_sendme_inc is best. cc_cwnd_inc_pct_ss: - Description: Percentage of the current congestion window to increment by during slow start, every cwnd. - - Range: [10, 300] - - Default: 100 + - Range: [1, 500] + - Default: 50 - Tuning Values: 50,100,200 - Tuning Notes: On the current live network, the algorithms tended to exit slow start early, so we did not exercise this much. This may not be the case in Shadow, or once clients upgrade to the new algorithms. + - Shadow Tuning Results: + Setting this above 50 caused excessive queues to build up in + Shadow. This may have been due to imbalances in Shadow client + allocation, though. Values of 50-100 will be explored after + examining Shadow Guard Relay Utilization. cc_bdp_alg: - Description: The BDP estimation algorithm to use. @@ -1215,6 +1305,8 @@ These are sorted in order of importance to tune, most important first. - Default: 7 (Piecewise EWMA) - Tuning Notes: We don't expect to need to tune this. + - Shadow Tuning Results: + We leave this as-is, but disable it in Vegas instead, below. 6.5.2. Westwood parameters @@ -1273,13 +1365,18 @@ These are sorted in order of importance to tune, most important first. 6.5.3. Vegas Parameters - cc_vegas_alpha: - cc_vegas_beta: - cc_vegas_gamma: + cc_vegas_alpha_{exit,onion,sos,vg,sbws}: + cc_vegas_beta_{exit,onion,sos,vg,sbws}: + cc_vegas_gamma_{exit,onion,sos,vg,sbws}: + cc_vegas_delta_{exit,onion,sos,vg,sbws}: - Description: These parameters govern the number of cells that [TOR_VEGAS] can detect in queue before reacting. - - Range: [1, 1000] - - Defaults: 6*cc_sendme_inc for gamma and beta; 3*cc_sendme_inc for alpha + - Range: [0, 1000] (except delta, which has max of INT32_MAX) + - Defaults: + alpha: path_len*2*31-31 + beta: path_len*2*31 + gamma: path_len*2*31 + delta: path_len*2*31 + 2*31 - Tuning Notes: The amount of queued cells that Vegas should tolerate is heavily dependent upon competing congestion control algorithms. The specified @@ -1288,18 +1385,30 @@ These are sorted in order of importance to tune, most important first. clients using fixed windows is reduced (or circwindow is lowered), we can reduce these parameters, which will result in less overall queuing and congestion on the network. + - Shadow Tuning Results: + We found that the best values for 3-hop Exit circuits was to set + beta and gamma to the size of the outbufs times the number of hops. + This has the effect that Vegas detects congestion and backs off + when this much queue delay is detected. Alpha is set to one TLS + record/sendme_inc below this value. If the queue length is detected + to be below that, we increase the congestion window. We still + need to verify that the path length multiplier still holds for + other types of circuits, specifically onion services. cc_vegas_bdp_mix: - Description: This parameter allows us to specify a weighted percent average between the cwnd BDP estimator and the piecewise estimator. - Range: [0, 100] - - Default: 0 (use 100% Piecewise EWMA) + - Default: 100 (use 100% CWND estimator) - Tuning Notes: The original Vegas literature specified the CWND estimator, but the Piecewise estimator is very likely more suited for our use case. This parameter allows us to average them. We're unlikely to need it. + - Shadow Tuning Results: + Because the BDP estimator had ack compression and over-estimation, + we the CWND estimator. 6.5.4. NOLA Parameters @@ -1358,7 +1467,7 @@ These are sorted in order of importance to tune, most important first. cc_xon_change_pct - Description: Specifies how much the edge drain rate can change before we send another advisory cell. - - Range: [1, 100] + - Range: [1, 99] - Default: 25 - Tuning values: [25, 50, 75] - Tuning Notes: @@ -1465,6 +1574,9 @@ These are sorted in order of importance to tune, most important first. expensive. We will need to trace or monitor epoll() invocations in Shadow or on a Tor exit to verify that low values do not lead to more mainloop invocations. + - Shadow Tuning Results: + After extensive tuning, it turned out that the defaults were optimal + in terms of throughput. orconn_high orconn_low @@ -1658,85 +1770,96 @@ also be used as a side channel. So we must limit its use to a couple of cells per circuit, at most. https://blog.torproject.org/tor-security-advisory-relay-early-traffic-confirmation-attack -9. Onion Services + +9. Onion Service Negotiation [ONION_NEGOTIATION] Onion service requires us to advertise the protocol version and congestion control parameters in a different way since the end points do not know each -other like a client knows all the relays and what they support. +other like a client knows all the relays and what they support. Additionally, +we cannot use ntorv3 for onion service negotiation, because it is not +supported at all rendezvous and introduction points. To address this, this is done in two parts. First, the service needs to -advertise to the world that it supports congestion control. This is done -through a new line in the descriptor, see section 9.1 below. +advertise to the world that it supports congestion control, and its view of +the current cc_sendme_inc consensus parameter. This is done through a new +line in the onion service descriptor, see section 9.1 below. Second, the client needs to inform the service that it wants to use congestion -control on the rendezvous circuit and with wich parameters. This is done -through the INTRODUCE cell as an extension, see section 9.2 below. +control on the rendezvous circuit. This is done through the INTRODUCE cell as +an extension, see section 9.2 below. -9.1. Descriptor +9.1. Onion Service Descriptor -We propose to add a new line to advertise the flow control protocol version: +We propose to add a new line to advertise the flow control protocol version, +in the encrypted section of the onion service descriptor: - "flow-control" SP version-number NL + "flow-control" SP version-range SP sendme-inc NL - The "version-number" value is the same as the protocol version FlowCtrl - that relay advertises which is defined earlier in this proposal. Current - value can only be "2". + The "version-range" value is the same as the protocol version FlowCtrl + that relay advertises which is defined earlier in this proposal. The + current value is "1-2". -Clients that are able to parse this line and know the protocol version can then -send in the INTRODUCE1 cell congestion control parameters that they would like -to use which is detailed in the next section. + The "sendme-inc" value comes from the service's current cc_sendme_inc + consensus parameter. -This line MUST be removed from the descriptor if the consensus disables -congestion control by setting "cc_alg=0". In other words, a service should only -advertise its flow control version if congestion control is enabled network -wide. +Clients MUST ignore additional unknown versions in "version-range", and MUST +ignore any additional values on this line. -9.2 INTRODUCE cell extension +Clients SHOULD use the highest value in "version-range" to govern their +protocol choice for "FlowCtrl" and INTRODUCE cell format, as per Section 9.2 +below. -We propose a new extension to the INTRODUCE cell which can be used to send -congestion control parameters down to the service. It is important to mention -that this is an extension to be used in the encrypted setion of the cell and -not its readable section by the introduction point. +If clients do not support any of the versions in "version-range", they SHOULD +reject the descriptor. (They MAY choose to ignore this line instead, but doing +so means using the old fixed-window SENDME flow control, which will likely be +bad for the network). -If used, it needs to be encoded within the N_EXTENSIONS field of the ENCRYPTED -section of the INTRODUCE1 cell defined in rend-spec-v3.txt section 3.3. The -content is defined as follow: +Clients that are able to parse this line and know the protocol version +MUST validate that the "sendme-inc" value is within a multiple of 2 of the +"cc_sendme_inc" in the consensus that they see. If "sendme-inc" is not within +range, they MUST reject the descriptor. - EXT_FIELD_TYPE: +If their consensus also lists a non-zero "cc_alg", they MAY then send in the +INTRODUCE1 cell congestion control request extention field, which is detailed +in the next section. - [01] -- Congestion Control Parameters. +A service should only advertise its flow control version if congestion control is +enabled. It MUST remove this line if congestion control is disabled. - If this flag is set, the extension should be used by the service to learn - what are the congestion control parameters to use on the rendezvous - circuit. +If the service observes a change in 'cc_sendme_inc' consensus parameter since +it last published its descriptor, it MUST immediately close its introduction +points, and publish a new descriptor with the new "sendme-inc" value. The +additional step of closing the introduction points ensures that no clients +arrive using a cached descriptor, with the old "sendme-inc" value. - EXT_FIELD content format is: +9.2 INTRODUCE cell extension - N_PARAMS [1 byte] - N_PARAMS times: - PARAM_TYPE [1 byte] - PARAM_VALUE [8 byte] +We propose a new extension to the INTRODUCE cell which can be used to send +congestion control parameters down to the service. It is important to mention +that this is an extension to be used in the encrypted setion of the cell and +not its readable section by the introduction point. - The PARAM_TYPE possible values are: +If used, it needs to be encoded within the ENCRYPTED section of the INTRODUCE1 +cell defined in rend-spec-v3.txt section 3.3. The content is defined as follow: - [01] -- Newest protocol version supported - The newest protocol version that the client supports. + EXT_FIELD_TYPE: - [02] -- SENDME increment - The initial SENDME increment that should be used by both end points - when using congestion control. + [01] -- Congestion Control Request. - The PARAM_VALUE size is 8 bytes in order to accomodate 64bit values. It - MUST match the specified limits for the following PARAM_TYPE: +This field is has zero payload length. Its presence signifies that the client wants to +use congestion control. The client MUST NOT set this field, or use +ntorv3, if the service did not list "2" in the "FlowCtrl" line in the +descriptor. The client SHOULD NOT provide this field if the consensus parameter +'cc_alg' is 0. - [01] -- Min: 2, Max: 255 - [02] -- Min: 1, Max: 5000 (same as "cc_sendme_inc") +The service MUST ignore any unknown fields. 9.3 Protocol Flow First, the client reads the "flow-control" line in the descriptor and gets the -maximum value from what it supports and the service supports. As an example, if -the client supports 2-3-4 and the service supports 2-3, then 3 is chosen. +maximum value from that line's "version-range" and the service supports. As an +example, if the client supports 2-3-4 and the service supports 2-3, then 3 is +chosen. It then sends that value along its desired cc_sendme_inc value in the INTRODUCE1 cell in the extension. @@ -1747,7 +1870,7 @@ then applied to the rendezvous circuit. 9.4 Circuit Behavior -If the extension is not found in the cell, the service MUST not use congestion +If the extension is not found in the cell, the service MUST NOT use congestion control on the rendezvous circuit. Any invalid values received in the extension should result in closing the @@ -1765,15 +1888,159 @@ everyone looks the same again. The new extension is located in the encrypted part of the INTRODUCE1 cell and thus the introduction point can't learn its content. -10. Acknowledgements + +10. Exit negotiation [EXIT_NEGOTIATION] + +Similar to onion services, clients and exits will need to negotiate the +decision to use congestion control, as well as a common value for +'cc_sendme_inc', for a given circuit. + +10.1. When to negotiate + +Clients decide to initiate a negotiation attempt for a circuit if the +consensus lists a non-zero 'cc_alg' parameter value, and the protover line +for their chosen exit includes a value of 2 in the "FlowCtrl" field. + +If the FlowCtrl=2 subprotocol is absent, a client MUST NOT attempt negotiation. + +If 'cc_alg' is absent or zero, a client SHOULD NOT attempt +negotiation, or use ntorv3. + +If the protover and consensus conditions are met, clients SHOULD negotiate +with the Exit if the circuit is to be used for exit stream activity. Clients +SHOULD NOT negotiate congestion control for one-hop circuits, or internal +circuits. + +10.2. What to negotiate + +Clients and exits need not agree on a specific congestion control algorithm, +or any aspects of its behavior. Each endpoint's management of its congestion +window is independent. However, because the new algorithms no longer use +stream SENDMEs or fixed window sizes, they cannot be used with an endpoint +expecting the old behavior. + +Additionally, each endpoint must agree on the the SENDME increment rate, in +order to synchronize SENDME authentication and pacing. + +For this reason, negotiation needs to establish a boolean: "use congestion +control", and an integer value for SENDME increment. + +No other parameters need to be negotiated. + +10.3. How to negotiate + +Negotiation is performed by sending an ntorv3 onionskin, as specified in +Proposal 332, to the Exit node. The encrypted payload contents from the +clients are encoded as an extension field, as in the onion service INTRO1 +cell: + + EXT_FIELD_TYPE: + + [01] -- Congestion Control Request. + +As in the INTRO1 extension field, this field is has zero payload length. + +Its presence signifies that the client wants to use congestion control. +Again, the client MUST NOT set this field, or use ntorv3, if this exit did not +list "2" in the "FlowCtrl" version line. The client SHOULD NOT set this to 1 +if the consensus parameter 'cc_alg' is 0. + +The Exit MUST ignore any additional unknown extension fields. + +The server's encrypted ntorv3 reply payload is encoded as: + + EXT_FIELD_TYPE: + + [02] -- Congestion Control Response. + + If this flag is set, the extension should be used by the service to learn + what are the congestion control parameters to use on the rendezvous + circuit. + + EXT_FIELD content payload is a single byte: + + sendme_inc [1 byte] + +The Exit MUST provide its current view of 'cc_sendme_inc' in this payload if it +observes a non-zero 'cc_alg' consensus parameter. Exits SHOULD only include +this field once. + +The client MUST use the FIRST such field value, and ignore any duplicate field +specifiers. The client MUST ignore any unknown additional fields. + +10.5. Client checks + +The client MUST reject any ntorv3 replies for non-ntorv3 onionskins. + +The client MUST reject an ntorv3 reply with field EXT_FIELD_TYPE=02, if the +client did not include EXT_FIELD_TYPE=01 in its handshake. + +The client SHOULD reject a sendme_inc field value that differs from the +current 'cc_sendme_inc' consensus parameter by more than a factor of 2, in +either direction. + +If a client rejects a handshake, it MUST close the circuit. + +10.6. Managing consenus updates + +The pedantic reader will note that a rogue consensus can cause all clients +to decide to close circuits by changing 'cc_sendme_inc' by a large margin. + +As a matter of policy, the directory authorities MUST NOT change +'cc_sendme_inc' by more than a factor of two (2), within a four (4) hour +window, for this reason. + +In Shadow simulation, the optimal 'cc_sendme_inc' value to be ~31 cells, or +one (1) TLS record worth of cells. We do not expect to change this value +significantly. + + +11. Acknowledgements Immense thanks to Toke Høiland-Jørgensen for considerable input into all aspects of the TCP congestion control background material for this proposal, as well as review of our versions of the algorithms. +12. Glossary [GLOSSARY] + +ACK - Acknowledgment. In congestion control, this is a type of packet that +signals that the endpoint received a packet or packet set. In Tor, ACKs are +called SENDMEs. + +BDP - Bandwidth Delay Product. This is the quantity of bytes that are actively +in transit on a path at any given time. Typically, this does not count packets +waiting in queues. It is essentially RTT*BWE - queue_delay. + +BWE - BandWidth Estimate. This is the estimated throughput on a path. + +CWND - Congestion WiNDow. This is the total number of packets that are allowed +to be "outstanding" (aka not ACKed) on a path at any given time. An ideal +congestion control algorithm sets CWND=BDP. + +EWMA - Exponential Weighted Moving Average. This is a mechanism for smoothing +out high-frequency changes in a value, due to temporary effects. + +ICW - Initial Congestion Window. This is the initial value of the congestion +window at the start of a connection. -11. [CITATIONS] +RTT - Round Trip Time. This is the time it takes for one endpoint to send a +packet to the other endpoint, and get a response. + +SS - Slow Start. This is the initial phase of most congestion control +algorithms. Despite the name, it is an exponential growth phase, to quickly +increase the congestion window from the ICW value up the path BDP. After Slow +Start, changes to the congestion window are linear. + +XOFF - Transmitter Off. In flow control, XOFF means that the receiver is +receiving data too fast and is beginning to queue. It is sent to tell the +sender to stop sending. + +XON - Transmitter On. In flow control, XON means that the receiver is ready to +receive more data. It is sent to tell the sender to resume sending. + + +13. [CITATIONS] 1. Options for Congestion Control in Tor-Like Networks. https://lists.torproject.org/pipermail/tor-dev/2020-January/014140.html @@ -1866,4 +2133,3 @@ as well as review of our versions of the algorithms. 31. KIST: Kernel-Informed Socket Transport for Tor https://matt.traudt.xyz/static/papers/kist-tops2018.pdf - diff --git a/proposals/328-relay-overload-report.md b/proposals/328-relay-overload-report.md index e9634ae..e4069b0 100644 --- a/proposals/328-relay-overload-report.md +++ b/proposals/328-relay-overload-report.md @@ -43,6 +43,7 @@ state" which can be one or many of the following load metrics: - Any ntor onionskins are dropped - TCP port exhaustion - DNS timeout reached (X% of timeouts over Y seconds). + [Removed in tor-0.4.7.3-alpha] - CPU utilization of Tor's mainloop CPU core above 90% for 60 sec [Never implemented] - Control port overload (too many messages queued) @@ -73,7 +74,7 @@ this 72 hour period restarts. The 'version' field is set to '1' for the initial implementation of this proposal which includes all the above overload metrics except from the CPU and -control port overload. +control port overload. # 1.2. Token bucket size diff --git a/proposals/332-ntor-v3-with-extra-data.md b/proposals/332-ntor-v3-with-extra-data.md index 207bc07..25ae0ba 100644 --- a/proposals/332-ntor-v3-with-extra-data.md +++ b/proposals/332-ntor-v3-with-extra-data.md @@ -3,7 +3,7 @@ Filename: 332-ntor-v3-with-extra-data.md Title: Ntor protocol with extra data, version 3. Author: Nick Mathewson Created: 12 July 2021 -Status: Open +Status: Accepted ``` # Overview @@ -338,20 +338,30 @@ We use the following meta-encoding for the contents of client and server messages. [Any number of times]: - TYPE [one byte] - LEN [one byte] - BODY [LEN bytes] + EXTENSION + EXT_FIELD_TYPE [one byte] + EXT_FIELD_LEN [one byte] + EXT_FIELD [EXT_FIELD_LEN bytes] -We do not specify specific TYPE semantics here; we leave those for -other proposals. +(`EXT_FIELD_LEN` may be zero, in which case EXT_FIELD is absent.) All parties MUST reject messages that are not well-formed per the rules above. -To avoid partitioning, clients MUST reject messages with TYPEs that -they do not recognize. (Therefore, whenever we specify a new server -message TYPE, we must say that it can only be included if the client -signals that it understands it.) +We do not specify specific TYPE semantics here; we leave those for +other proposals and specifications. + +Parties MUST ignore extensions with `EXT_FIELD_TYPE` bodies they do not +recognize. + +Unless otherwise specified in the documentation for an extension type: +* Each extension type SHOULD be sent only once in a message. +* Parties MUST ignore any occurrences all occurrences of an extension + with a given type after the first such occurrence. +* Extensions SHOULD be sent in numerically ascending order by type. + +(The above extension sorting and multiplicity rules are only defaults; +they may be overridden in the description of individual extensions.) # A.3 How much space is available? diff --git a/proposals/333-vanguards-lite.md b/proposals/333-vanguards-lite.md index 998bb4a..5e62b03 100644 --- a/proposals/333-vanguards-lite.md +++ b/proposals/333-vanguards-lite.md @@ -3,7 +3,8 @@ Filename: 333-vanguards-lite.md Title: Vanguards lite Author: George Kadianakis, Mike Perry Created: 2021-05-20 -Status: Draft +Status: Finished +Implemented-In: 0.4.7.1-alpha ``` # 0. Introduction & Motivation diff --git a/proposals/334-middle-only-flag.txt b/proposals/334-middle-only-flag.txt index ed5de42..823e927 100644 --- a/proposals/334-middle-only-flag.txt +++ b/proposals/334-middle-only-flag.txt @@ -2,7 +2,8 @@ Filename: 334-middle-only-flag.txt Title: A Directory Authority Flag To Mark Relays As Middle-only Author: Neel Chauhan Created: 2021-09-07 -Status: Open +Status: Superseded +Superseded-by: 335-middle-only-redux.md 1. Introduction diff --git a/proposals/335-middle-only-redux.md b/proposals/335-middle-only-redux.md index 3329afe..b308e76 100644 --- a/proposals/335-middle-only-redux.md +++ b/proposals/335-middle-only-redux.md @@ -3,7 +3,8 @@ Filename: 335-middle-only-redux.md Title: An authority-only design for MiddleOnly Author: Nick Mathewson Created: 2021-10-08 -Status: Open +Status: Closed +Implemented-In: 0.4.7.2-alpha ``` # Introduction diff --git a/proposals/338-netinfo-y2038.md b/proposals/338-netinfo-y2038.md new file mode 100644 index 0000000..a1a0385 --- /dev/null +++ b/proposals/338-netinfo-y2038.md @@ -0,0 +1,79 @@ +``` +Filename: 338-netinfo-y2038.md +Title: Use an 8-byte timestamp in NETINFO cells +Author: Nick Mathewson +Created: 2022-03-14 +Status: Open +``` + +# Introduction + +Currently Tor relays use a 4-byte timestamp (in seconds since the Unix +epoch) in their NETINFO cells. Notoriously, such a timestamp will +overflow on 19 January 2038. + +Let's get ahead of the problem and squash this issue now, by expanding +the timestamp to 8 bytes. (8 bytes worth of seconds will be long enough +to outlast the Earth's sun.) + +# Proposed change + +I propose adding a new link protocol version. (The next one in +sequence, as of this writing, is version 6.) + +I propose that we change the text of tor-spec section 4.5 from: + +``` + TIME (Timestamp) [4 bytes] +``` + +to + +``` + TIME (Timestamp) [4 or 8 bytes *] +``` + +and specify that this field is 4 bytes wide on link protocols 1-5, but 8 +bytes wide on link protocols 6 and beyond. + +# Rejected alternatives + +Our protocol specifies that parties MUST ignore extra data at the end of +cells. Therefore we _could_ add additional data at the end of the +NETINFO cell, and use that to store the high 4 bytes of the timestamp +without having to increase the link protocol version number. I propose +that we don't do that: it's ugly. + +As another alternative, we could declare that parties must interpret the +timestamp such that its high 4 bytes place it as close as possible to +their current time. I'm rejecting this kludge because it would give +confusing results in the too-common case where clients have their clocks +mis-set to Jan 1, 1970. + +# Impacts on our implementations + +Arti won't be able to implement this change until it supports connection +padding (as required by link protocol 5), which is currently planned for +the next Arti milestone (1.0.0, scheduled for this fall). + +If we think that that's a problem, or if we want to have support for +implementations without connection padding in the future, we should +reconsider this plan so that connection padding support is independent +from 8-byte timestamps. + +# Other timestamps in Tor + +I've done a cursory search of our protocols to see if we have any other +instances of the Y2038 problem. + +There is a 4-byte timestamp in `cert-spec`, but that one is an unsigned +integer counting _hours_ since the Unix epoch, which will keep it from +wrapping around till 478756 C.E. (The rollover date of "10136 CE" +reported in `cert-spec` is wrong, and seems to be based on the +misapprehension that the counter is in *minutes*.) + +The v2 onion service protocol has 4-byte timestamps, but it is +thoroughly deprecated and unsupported. + +I couldn't find any other 4-byte timestamps, but that is no guarantee: +others should look for them too. diff --git a/proposals/BY_INDEX.md b/proposals/BY_INDEX.md index 37a118a..5e48b74 100644 --- a/proposals/BY_INDEX.md +++ b/proposals/BY_INDEX.md @@ -77,7 +77,7 @@ Below are a list of proposals sorted by their proposal number. See * [`157-specific-cert-download.txt`](/proposals/157-specific-cert-download.txt): Make certificate downloads specific [CLOSED] * [`158-microdescriptors.txt`](/proposals/158-microdescriptors.txt): Clients download consensus + microdescriptors [CLOSED] * [`159-exit-scanning.txt`](/proposals/159-exit-scanning.txt): Exit Scanning [INFORMATIONAL] -* [`160-bandwidth-offset.txt`](/proposals/160-bandwidth-offset.txt): Authorities vote for bandwidth offsets in consensus [FINISHED] +* [`160-bandwidth-offset.txt`](/proposals/160-bandwidth-offset.txt): Authorities vote for bandwidth offsets in consensus [CLOSED] * [`161-computing-bandwidth-adjustments.txt`](/proposals/161-computing-bandwidth-adjustments.txt): Computing Bandwidth Adjustments [CLOSED] * [`162-consensus-flavors.txt`](/proposals/162-consensus-flavors.txt): Publish the consensus in multiple flavors [CLOSED] * [`163-detecting-clients.txt`](/proposals/163-detecting-clients.txt): Detecting whether a connection comes from a client [SUPERSEDED] @@ -149,7 +149,7 @@ Below are a list of proposals sorted by their proposal number. See * [`229-further-socks5-extensions.txt`](/proposals/229-further-socks5-extensions.txt): Further SOCKS5 extensions [REJECTED] * [`230-rsa1024-relay-id-migration.txt`](/proposals/230-rsa1024-relay-id-migration.txt): How to change RSA1024 relay identity keys [OBSOLETE] * [`231-migrate-authority-rsa1024-ids.txt`](/proposals/231-migrate-authority-rsa1024-ids.txt): Migrating authority RSA1024 identity keys [OBSOLETE] -* [`232-pluggable-transports-through-proxy.txt`](/proposals/232-pluggable-transports-through-proxy.txt): Pluggable Transport through SOCKS proxy [FINISHED] +* [`232-pluggable-transports-through-proxy.txt`](/proposals/232-pluggable-transports-through-proxy.txt): Pluggable Transport through SOCKS proxy [CLOSED] * [`233-quicken-tor2web-mode.txt`](/proposals/233-quicken-tor2web-mode.txt): Making Tor2Web mode faster [REJECTED] * [`234-remittance-addresses.txt`](/proposals/234-remittance-addresses.txt): Adding remittance field to directory specification [REJECTED] * [`235-kill-named-flag.txt`](/proposals/235-kill-named-flag.txt): Stop assigning (and eventually supporting) the Named flag [CLOSED] @@ -159,7 +159,7 @@ Below are a list of proposals sorted by their proposal number. See * [`239-consensus-hash-chaining.txt`](/proposals/239-consensus-hash-chaining.txt): Consensus Hash Chaining [OPEN] * [`240-auth-cert-revocation.txt`](/proposals/240-auth-cert-revocation.txt): Early signing key revocation for directory authorities [OPEN] * [`241-suspicious-guard-turnover.txt`](/proposals/241-suspicious-guard-turnover.txt): Resisting guard-turnover attacks [REJECTED] -* [`242-better-families.txt`](/proposals/242-better-families.txt): Better performance and usability for the MyFamily option [RESERVE] +* [`242-better-families.txt`](/proposals/242-better-families.txt): Better performance and usability for the MyFamily option [SUPERSEDED] * [`243-hsdir-flag-need-stable.txt`](/proposals/243-hsdir-flag-need-stable.txt): Give out HSDir flag only to relays with Stable flag [CLOSED] * [`244-use-rfc5705-for-tls-binding.txt`](/proposals/244-use-rfc5705-for-tls-binding.txt): Use RFC5705 Key Exporting in our AUTHENTICATE calls [CLOSED] * [`245-tap-out.txt`](/proposals/245-tap-out.txt): Deprecating and removing the TAP circuit extension protocol [NEEDS-REVISION] @@ -190,7 +190,7 @@ Below are a list of proposals sorted by their proposal number. See * [`270-newhope-hybrid-handshake.txt`](/proposals/270-newhope-hybrid-handshake.txt): RebelAlliance: A Post-Quantum Secure Hybrid Handshake Based on NewHope [OBSOLETE] * [`271-another-guard-selection.txt`](/proposals/271-another-guard-selection.txt): Another algorithm for guard selection [CLOSED] * [`272-valid-and-running-by-default.txt`](/proposals/272-valid-and-running-by-default.txt): Listed routers should be Valid, Running, and treated as such [CLOSED] -* [`273-exit-relay-pinning.txt`](/proposals/273-exit-relay-pinning.txt): Exit relay pinning for web services [DRAFT] +* [`273-exit-relay-pinning.txt`](/proposals/273-exit-relay-pinning.txt): Exit relay pinning for web services [RESERVE] * [`274-rotate-onion-keys-less.txt`](/proposals/274-rotate-onion-keys-less.txt): Rotate onion keys less frequently [CLOSED] * [`275-md-published-time-is-silly.txt`](/proposals/275-md-published-time-is-silly.txt): Stop including meaningful "published" time in microdescriptor consensus [CLOSED] * [`276-lower-bw-granularity.txt`](/proposals/276-lower-bw-granularity.txt): Report bandwidth with lower granularity in consensus documents [DEAD] @@ -199,13 +199,13 @@ Below are a list of proposals sorted by their proposal number. See * [`279-naming-layer-api.txt`](/proposals/279-naming-layer-api.txt): A Name System API for Tor Onion Services [NEEDS-REVISION] * [`280-privcount-in-tor.txt`](/proposals/280-privcount-in-tor.txt): Privacy-Preserving Statistics with Privcount in Tor [SUPERSEDED] * [`281-bulk-md-download.txt`](/proposals/281-bulk-md-download.txt): Downloading microdescriptors in bulk [RESERVE] -* [`282-remove-named-from-consensus.txt`](/proposals/282-remove-named-from-consensus.txt): Remove "Named" and "Unnamed" handling from consensus voting [FINISHED] +* [`282-remove-named-from-consensus.txt`](/proposals/282-remove-named-from-consensus.txt): Remove "Named" and "Unnamed" handling from consensus voting [ACCEPTED] * [`283-ipv6-in-micro-consensus.txt`](/proposals/283-ipv6-in-micro-consensus.txt): Move IPv6 ORPorts from microdescriptors to the microdesc consensus [CLOSED] * [`284-hsv3-control-port.txt`](/proposals/284-hsv3-control-port.txt): Hidden Service v3 Control Port [CLOSED] * [`285-utf-8.txt`](/proposals/285-utf-8.txt): Directory documents should be standardized as UTF-8 [ACCEPTED] * [`286-hibernation-api.txt`](/proposals/286-hibernation-api.txt): Controller APIs for hibernation access on mobile [REJECTED] * [`287-reduce-lifetime.txt`](/proposals/287-reduce-lifetime.txt): Reduce circuit lifetime without overloading the network [OPEN] -* [`288-privcount-with-shamir.txt`](/proposals/288-privcount-with-shamir.txt): Privacy-Preserving Statistics with Privcount in Tor (Shamir version) [ACCEPTED] +* [`288-privcount-with-shamir.txt`](/proposals/288-privcount-with-shamir.txt): Privacy-Preserving Statistics with Privcount in Tor (Shamir version) [RESERVE] * [`289-authenticated-sendmes.txt`](/proposals/289-authenticated-sendmes.txt): Authenticating sendme cells to mitigate bandwidth attacks [CLOSED] * [`290-deprecate-consensus-methods.txt`](/proposals/290-deprecate-consensus-methods.txt): Continuously update consensus methods [META] * [`291-two-guard-nodes.txt`](/proposals/291-two-guard-nodes.txt): The move to two guard nodes [NEEDS-REVISION] @@ -218,7 +218,7 @@ Below are a list of proposals sorted by their proposal number. See * [`298-canonical-families.txt`](/proposals/298-canonical-families.txt): Putting family lines in canonical form [CLOSED] * [`299-ip-failure-count.txt`](/proposals/299-ip-failure-count.txt): Preferring IPv4 or IPv6 based on IP Version Failure Count [SUPERSEDED] * [`300-walking-onions.txt`](/proposals/300-walking-onions.txt): Walking Onions: Scaling and Saving Bandwidth [INFORMATIONAL] -* [`301-dont-vote-on-package-fingerprints.txt`](/proposals/301-dont-vote-on-package-fingerprints.txt): Don't include package fingerprints in consensus documents [FINISHED] +* [`301-dont-vote-on-package-fingerprints.txt`](/proposals/301-dont-vote-on-package-fingerprints.txt): Don't include package fingerprints in consensus documents [OPEN] * [`302-padding-machines-for-onion-clients.txt`](/proposals/302-padding-machines-for-onion-clients.txt): Hiding onion service clients using padding [CLOSED] * [`303-protover-removal-policy.txt`](/proposals/303-protover-removal-policy.txt): When and how to remove support for protocol versions [OPEN] * [`304-socks5-extending-hs-error-codes.txt`](/proposals/304-socks5-extending-hs-error-codes.txt): Extending SOCKS5 Onion Service Error Codes [CLOSED] @@ -227,12 +227,12 @@ Below are a list of proposals sorted by their proposal number. See * [`307-onionbalance-v3.txt`](/proposals/307-onionbalance-v3.txt): Onion Balance Support for Onion Service v3 [RESERVE] * [`308-counter-galois-onion.txt`](/proposals/308-counter-galois-onion.txt): Counter Galois Onion: A New Proposal for Forward-Secure Relay Cryptography [OPEN] * [`309-optimistic-socks-in-tor.txt`](/proposals/309-optimistic-socks-in-tor.txt): Optimistic SOCKS Data [OPEN] -* [`310-bandaid-on-guard-selection.txt`](/proposals/310-bandaid-on-guard-selection.txt): Towards load-balancing in Prop 271 [FINISHED] +* [`310-bandaid-on-guard-selection.txt`](/proposals/310-bandaid-on-guard-selection.txt): Towards load-balancing in Prop 271 [CLOSED] * [`311-relay-ipv6-reachability.txt`](/proposals/311-relay-ipv6-reachability.txt): Tor Relay IPv6 Reachability [ACCEPTED] * [`312-relay-auto-ipv6-addr.txt`](/proposals/312-relay-auto-ipv6-addr.txt): Tor Relay Automatic IPv6 Address Discovery [ACCEPTED] * [`313-relay-ipv6-stats.txt`](/proposals/313-relay-ipv6-stats.txt): Tor Relay IPv6 Statistics [ACCEPTED] -* [`314-allow-markdown-proposals.md`](/proposals/314-allow-markdown-proposals.md): Allow Markdown for proposal format [FINISHED] -* [`315-update-dir-required-fields.txt`](/proposals/315-update-dir-required-fields.txt): Updating the list of fields required in directory documents [OPEN] +* [`314-allow-markdown-proposals.md`](/proposals/314-allow-markdown-proposals.md): Allow Markdown for proposal format [CLOSED] +* [`315-update-dir-required-fields.txt`](/proposals/315-update-dir-required-fields.txt): Updating the list of fields required in directory documents [CLOSED] * [`316-flashflow.md`](/proposals/316-flashflow.md): FlashFlow: A Secure Speed Test for Tor (Parent Proposal) [DRAFT] * [`317-secure-dns-name-resolution.txt`](/proposals/317-secure-dns-name-resolution.txt): Improve security aspects of DNS name resolution [NEEDS-REVISION] * [`318-limit-protovers.md`](/proposals/318-limit-protovers.md): Limit protover values to 0-63 [CLOSED] @@ -249,10 +249,11 @@ Below are a list of proposals sorted by their proposal number. See * [`329-traffic-splitting.txt`](/proposals/329-traffic-splitting.txt): Overcoming Tor's Bottlenecks with Traffic Splitting [DRAFT] * [`330-authority-contact.md`](/proposals/330-authority-contact.md): Modernizing authority contact entries [OPEN] * [`331-res-tokens-for-anti-dos.md`](/proposals/331-res-tokens-for-anti-dos.md): Res tokens: Anonymous Credentials for Onion Service DoS Resilience [DRAFT] -* [`332-ntor-v3-with-extra-data.md`](/proposals/332-ntor-v3-with-extra-data.md): Ntor protocol with extra data, version 3 [OPEN] -* [`333-vanguards-lite.md`](/proposals/333-vanguards-lite.md): Vanguards lite [DRAFT] -* [`334-middle-only-flag.txt`](/proposals/334-middle-only-flag.txt): A Directory Authority Flag To Mark Relays As Middle-only [OPEN] -* [`335-middle-only-redux.md`](/proposals/335-middle-only-redux.md): An authority-only design for MiddleOnly [OPEN] +* [`332-ntor-v3-with-extra-data.md`](/proposals/332-ntor-v3-with-extra-data.md): Ntor protocol with extra data, version 3 [ACCEPTED] +* [`333-vanguards-lite.md`](/proposals/333-vanguards-lite.md): Vanguards lite [FINISHED] +* [`334-middle-only-flag.txt`](/proposals/334-middle-only-flag.txt): A Directory Authority Flag To Mark Relays As Middle-only [SUPERSEDED] +* [`335-middle-only-redux.md`](/proposals/335-middle-only-redux.md): An authority-only design for MiddleOnly [CLOSED] * [`336-randomize-guard-retries.md`](/proposals/336-randomize-guard-retries.md): Randomized schedule for guard retries [OPEN] * [`337-simpler-guard-usability.md`](/proposals/337-simpler-guard-usability.md): A simpler way to decide, "Is this guard usable?" [OPEN] +* [`338-netinfo-y2038.md`](/proposals/338-netinfo-y2038.md): Use an 8-byte timestamp in NETINFO cells [OPEN] diff --git a/proposals/README.md b/proposals/README.md index 95b660c..58aca40 100644 --- a/proposals/README.md +++ b/proposals/README.md @@ -27,11 +27,11 @@ for discussion. * [`287-reduce-lifetime.txt`](/proposals/287-reduce-lifetime.txt): Reduce circuit lifetime without overloading the network * [`295-relay-crypto-with-adl.txt`](/proposals/295-relay-crypto-with-adl.txt): Using ADL for relay cryptography (solving the crypto-tagging attack) * [`296-expose-bandwidth-files.txt`](/proposals/296-expose-bandwidth-files.txt): Have Directory Authorities expose raw bandwidth list files +* [`301-dont-vote-on-package-fingerprints.txt`](/proposals/301-dont-vote-on-package-fingerprints.txt): Don't include package fingerprints in consensus documents * [`303-protover-removal-policy.txt`](/proposals/303-protover-removal-policy.txt): When and how to remove support for protocol versions * [`306-ipv6-happy-eyeballs.txt`](/proposals/306-ipv6-happy-eyeballs.txt): A Tor Implementation of IPv6 Happy Eyeballs * [`308-counter-galois-onion.txt`](/proposals/308-counter-galois-onion.txt): Counter Galois Onion: A New Proposal for Forward-Secure Relay Cryptography * [`309-optimistic-socks-in-tor.txt`](/proposals/309-optimistic-socks-in-tor.txt): Optimistic SOCKS Data -* [`315-update-dir-required-fields.txt`](/proposals/315-update-dir-required-fields.txt): Updating the list of fields required in directory documents * [`319-wide-everything.md`](/proposals/319-wide-everything.md): RELAY_FRAGMENT cells * [`321-happy-families.md`](/proposals/321-happy-families.md): Better performance and usability for the MyFamily option (v2) * [`322-dirport-linkspec.md`](/proposals/322-dirport-linkspec.md): Extending link specifiers to include the directory port @@ -40,11 +40,9 @@ for discussion. * [`325-packed-relay-cells.md`](/proposals/325-packed-relay-cells.md): Packed relay cells: saving space on small commands * [`326-tor-relay-well-known-uri-rfc8615.md`](/proposals/326-tor-relay-well-known-uri-rfc8615.md): The "tor-relay" Well-Known Resource Identifier * [`330-authority-contact.md`](/proposals/330-authority-contact.md): Modernizing authority contact entries -* [`332-ntor-v3-with-extra-data.md`](/proposals/332-ntor-v3-with-extra-data.md): Ntor protocol with extra data, version 3 -* [`334-middle-only-flag.txt`](/proposals/334-middle-only-flag.txt): A Directory Authority Flag To Mark Relays As Middle-only -* [`335-middle-only-redux.md`](/proposals/335-middle-only-redux.md): An authority-only design for MiddleOnly * [`336-randomize-guard-retries.md`](/proposals/336-randomize-guard-retries.md): Randomized schedule for guard retries * [`337-simpler-guard-usability.md`](/proposals/337-simpler-guard-usability.md): A simpler way to decide, "Is this guard usable?" +* [`338-netinfo-y2038.md`](/proposals/338-netinfo-y2038.md): Use an 8-byte timestamp in NETINFO cells ## ACCEPTED proposals: slated for implementation @@ -54,12 +52,13 @@ might or might not have a specific timeframe planned for their implementation. * [`265-load-balancing-with-overhead.txt`](/proposals/265-load-balancing-with-overhead.txt): Load Balancing with Overhead Parameters +* [`282-remove-named-from-consensus.txt`](/proposals/282-remove-named-from-consensus.txt): Remove "Named" and "Unnamed" handling from consensus voting * [`285-utf-8.txt`](/proposals/285-utf-8.txt): Directory documents should be standardized as UTF-8 -* [`288-privcount-with-shamir.txt`](/proposals/288-privcount-with-shamir.txt): Privacy-Preserving Statistics with Privcount in Tor (Shamir version) * [`292-mesh-vanguards.txt`](/proposals/292-mesh-vanguards.txt): Mesh-based vanguards * [`311-relay-ipv6-reachability.txt`](/proposals/311-relay-ipv6-reachability.txt): Tor Relay IPv6 Reachability * [`312-relay-auto-ipv6-addr.txt`](/proposals/312-relay-auto-ipv6-addr.txt): Tor Relay Automatic IPv6 Address Discovery * [`313-relay-ipv6-stats.txt`](/proposals/313-relay-ipv6-stats.txt): Tor Relay IPv6 Statistics +* [`332-ntor-v3-with-extra-data.md`](/proposals/332-ntor-v3-with-extra-data.md): Ntor protocol with extra data, version 3 ## FINISHED proposals: implemented, specs not merged @@ -67,13 +66,8 @@ implementation. These proposals are implemented in some version of Tor; the proposals themselves still need to be merged into the specifications proper. -* [`160-bandwidth-offset.txt`](/proposals/160-bandwidth-offset.txt): Authorities vote for bandwidth offsets in consensus -* [`232-pluggable-transports-through-proxy.txt`](/proposals/232-pluggable-transports-through-proxy.txt): Pluggable Transport through SOCKS proxy * [`260-rend-single-onion.txt`](/proposals/260-rend-single-onion.txt): Rendezvous Single Onion Services -* [`282-remove-named-from-consensus.txt`](/proposals/282-remove-named-from-consensus.txt): Remove "Named" and "Unnamed" handling from consensus voting -* [`301-dont-vote-on-package-fingerprints.txt`](/proposals/301-dont-vote-on-package-fingerprints.txt): Don't include package fingerprints in consensus documents -* [`310-bandaid-on-guard-selection.txt`](/proposals/310-bandaid-on-guard-selection.txt): Towards load-balancing in Prop 271 -* [`314-allow-markdown-proposals.md`](/proposals/314-allow-markdown-proposals.md): Allow Markdown for proposal format +* [`333-vanguards-lite.md`](/proposals/333-vanguards-lite.md): Vanguards lite ## META proposals: about the proposal process @@ -107,13 +101,11 @@ These proposals have been marked as a draft by their author or the editors, indicating that they aren't yet in a complete form. They're still open for discussion. -* [`273-exit-relay-pinning.txt`](/proposals/273-exit-relay-pinning.txt): Exit relay pinning for web services * [`294-tls-1.3.txt`](/proposals/294-tls-1.3.txt): TLS 1.3 Migration * [`316-flashflow.md`](/proposals/316-flashflow.md): FlashFlow: A Secure Speed Test for Tor (Parent Proposal) * [`327-pow-over-intro.txt`](/proposals/327-pow-over-intro.txt): A First Take at PoW Over Introduction Circuits * [`329-traffic-splitting.txt`](/proposals/329-traffic-splitting.txt): Overcoming Tor's Bottlenecks with Traffic Splitting * [`331-res-tokens-for-anti-dos.md`](/proposals/331-res-tokens-for-anti-dos.md): Res tokens: Anonymous Credentials for Onion Service DoS Resilience -* [`333-vanguards-lite.md`](/proposals/333-vanguards-lite.md): Vanguards lite ## NEEDS-REVISION proposals: ideas that we can't implement as-is @@ -182,6 +174,7 @@ necessary. * [`155-four-hidden-service-improvements.txt`](/proposals/155-four-hidden-service-improvements.txt): Four Improvements of Hidden Service Performance * [`157-specific-cert-download.txt`](/proposals/157-specific-cert-download.txt): Make certificate downloads specific * [`158-microdescriptors.txt`](/proposals/158-microdescriptors.txt): Clients download consensus + microdescriptors +* [`160-bandwidth-offset.txt`](/proposals/160-bandwidth-offset.txt): Authorities vote for bandwidth offsets in consensus * [`161-computing-bandwidth-adjustments.txt`](/proposals/161-computing-bandwidth-adjustments.txt): Computing Bandwidth Adjustments * [`162-consensus-flavors.txt`](/proposals/162-consensus-flavors.txt): Publish the consensus in multiple flavors * [`166-statistics-extra-info-docs.txt`](/proposals/166-statistics-extra-info-docs.txt): Including Network Statistics in Extra-Info Documents @@ -217,6 +210,7 @@ necessary. * [`224-rend-spec-ng.txt`](/proposals/224-rend-spec-ng.txt): Next-Generation Hidden Services in Tor * [`227-vote-on-package-fingerprints.txt`](/proposals/227-vote-on-package-fingerprints.txt): Include package fingerprints in consensus documents * [`228-cross-certification-onionkeys.txt`](/proposals/228-cross-certification-onionkeys.txt): Cross-certifying identity keys with onion keys +* [`232-pluggable-transports-through-proxy.txt`](/proposals/232-pluggable-transports-through-proxy.txt): Pluggable Transport through SOCKS proxy * [`235-kill-named-flag.txt`](/proposals/235-kill-named-flag.txt): Stop assigning (and eventually supporting) the Named flag * [`236-single-guard-node.txt`](/proposals/236-single-guard-node.txt): The move to a single guard node * [`237-directory-servers-for-all.txt`](/proposals/237-directory-servers-for-all.txt): All relays are directory servers @@ -241,8 +235,12 @@ necessary. * [`302-padding-machines-for-onion-clients.txt`](/proposals/302-padding-machines-for-onion-clients.txt): Hiding onion service clients using padding * [`304-socks5-extending-hs-error-codes.txt`](/proposals/304-socks5-extending-hs-error-codes.txt): Extending SOCKS5 Onion Service Error Codes * [`305-establish-intro-dos-defense-extention.txt`](/proposals/305-establish-intro-dos-defense-extention.txt): ESTABLISH_INTRO Cell DoS Defense Extension +* [`310-bandaid-on-guard-selection.txt`](/proposals/310-bandaid-on-guard-selection.txt): Towards load-balancing in Prop 271 +* [`314-allow-markdown-proposals.md`](/proposals/314-allow-markdown-proposals.md): Allow Markdown for proposal format +* [`315-update-dir-required-fields.txt`](/proposals/315-update-dir-required-fields.txt): Updating the list of fields required in directory documents * [`318-limit-protovers.md`](/proposals/318-limit-protovers.md): Limit protover values to 0-63 * [`328-relay-overload-report.md`](/proposals/328-relay-overload-report.md): Make Relays Report When They Are Overloaded +* [`335-middle-only-redux.md`](/proposals/335-middle-only-redux.md): An authority-only design for MiddleOnly ## RESERVE proposals: saving for later @@ -260,11 +258,12 @@ confront the problems that they try to solve. * [`211-mapaddress-tor-status.txt`](/proposals/211-mapaddress-tor-status.txt): Internal Mapaddress for Tor Configuration Testing * [`223-ace-handshake.txt`](/proposals/223-ace-handshake.txt): Ace: Improved circuit-creation key exchange * [`226-bridgedb-database-improvements.txt`](/proposals/226-bridgedb-database-improvements.txt): "Scalability and Stability Improvements to BridgeDB: Switching to a Distributed Database System and RDBMS" -* [`242-better-families.txt`](/proposals/242-better-families.txt): Better performance and usability for the MyFamily option * [`255-hs-load-balancing.txt`](/proposals/255-hs-load-balancing.txt): Controller features to allow for load-balancing hidden services * [`256-key-revocation.txt`](/proposals/256-key-revocation.txt): Key revocation for relays and authorities * [`262-rekey-circuits.txt`](/proposals/262-rekey-circuits.txt): Re-keying live circuits with new cryptographic material +* [`273-exit-relay-pinning.txt`](/proposals/273-exit-relay-pinning.txt): Exit relay pinning for web services * [`281-bulk-md-download.txt`](/proposals/281-bulk-md-download.txt): Downloading microdescriptors in bulk +* [`288-privcount-with-shamir.txt`](/proposals/288-privcount-with-shamir.txt): Privacy-Preserving Statistics with Privcount in Tor (Shamir version) * [`307-onionbalance-v3.txt`](/proposals/307-onionbalance-v3.txt): Onion Balance Support for Onion Service v3 @@ -291,12 +290,14 @@ implemented. * [`194-mnemonic-urls.txt`](/proposals/194-mnemonic-urls.txt): Mnemonic .onion URLs * [`210-faster-headless-consensus-bootstrap.txt`](/proposals/210-faster-headless-consensus-bootstrap.txt): Faster Headless Consensus Bootstrapping * [`225-strawman-shared-rand.txt`](/proposals/225-strawman-shared-rand.txt): Strawman proposal: commit-and-reveal shared rng +* [`242-better-families.txt`](/proposals/242-better-families.txt): Better performance and usability for the MyFamily option * [`247-hs-guard-discovery.txt`](/proposals/247-hs-guard-discovery.txt): Defending Against Guard Discovery Attacks using Vanguards * [`249-large-create-cells.txt`](/proposals/249-large-create-cells.txt): Allow CREATE cells with >505 bytes of handshake data * [`252-single-onion.txt`](/proposals/252-single-onion.txt): Single Onion Services * [`266-removing-current-obsolete-clients.txt`](/proposals/266-removing-current-obsolete-clients.txt): Removing current obsolete clients from the Tor network * [`280-privcount-in-tor.txt`](/proposals/280-privcount-in-tor.txt): Privacy-Preserving Statistics with Privcount in Tor * [`299-ip-failure-count.txt`](/proposals/299-ip-failure-count.txt): Preferring IPv4 or IPv6 based on IP Version Failure Count +* [`334-middle-only-flag.txt`](/proposals/334-middle-only-flag.txt): A Directory Authority Flag To Mark Relays As Middle-only ## DEAD, REJECTED, OBSOLETE proposals: not in our plans diff --git a/pt-spec.txt b/pt-spec.txt index 05421c1..45b4c31 100644 --- a/pt-spec.txt +++ b/pt-spec.txt @@ -1,4 +1,3 @@ - Pluggable Transport Specification (Version 1) Abstract @@ -668,7 +667,7 @@ Table of Contents 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 diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt index 6a120eb..fac1395 100644 --- a/rend-spec-v3.txt +++ b/rend-spec-v3.txt @@ -1548,8 +1548,17 @@ Table of contents: authentication key. The EXT_FIELD_TYPE, EXT_FIELD_LEN, EXT_FIELD entries are reserved for - future extensions to the introduction protocol. Extensions with + extensions to the introduction protocol. Extensions with unrecognized EXT_FIELD_TYPE values must be ignored. + (`EXT_FIELD_LEN` may be zero, in which case EXT_FIELD is absent.) + + Unless otherwise specified in the documentation for an extension type: + * Each extension type SHOULD be sent only once in a message. + * Parties MUST ignore any occurrences all occurrences of an extension + with a given type after the first such occurrence. + * Extensions SHOULD be sent in numerically ascending order by type. + (The above extension sorting and multiplicity rules are only defaults; + they may be overridden in the descriptions of individual extensions.) The HANDSHAKE_AUTH field contains the MAC of all earlier fields in the cell using as its key the shared per-circuit material ("KH") @@ -1685,6 +1694,10 @@ Table of contents: Older versions of Tor send back an empty INTRO_ESTABLISHED cell instead. Services must accept an empty INTRO_ESTABLISHED cell from a legacy relay. + The same rules for multiplicity, ordering, and handling unknown types + apply to the extension fields here as described [EST_INTRO] above. + + 3.2. Sending an INTRODUCE1 cell to the introduction point. [SEND_INTRO1] In order to participate in the introduction protocol, a client must @@ -1737,6 +1750,10 @@ Table of contents: INTRODUCE2 cell with exactly the same contents to the service, and sends an INTRODUCE_ACK response to the client. + The same rules for multiplicity, ordering, and handling unknown types + apply to the extension fields here as described [EST_INTRO] above. + + 3.2.2. INTRODUCE_ACK cell format. [INTRO_ACK] An INTRODUCE_ACK cell has the following fields: @@ -1755,6 +1772,10 @@ Table of contents: [00 02] -- Bad message format [00 03] -- Can't relay cell to service + The same rules for multiplicity, ordering, and handling unknown types + apply to the extension fields here as described [EST_INTRO] above. + + 3.3. Processing an INTRODUCE2 cell at the hidden service. [PROCESS_INTRO2] Upon receiving an INTRODUCE2 cell, the hidden service host checks whether @@ -1831,6 +1852,10 @@ Table of contents: shared key with the hidden service client. * A set of shared keys to use for end-to-end encryption. + The same rules for multiplicity, ordering, and handling unknown types + apply to the extension fields here as described [EST_INTRO] above. + + 3.3.1. Introduction handshake encryption requirements [INTRO-HANDSHAKE-REQS] When decoding the encrypted information in an INTRODUCE2 cell, a |