tor-dev

tor-dev@lists.torproject.org

3581 discussions

Proposal 273: Exit relay pinning for web services
by Philipp Winter 18 Oct '16

18 Oct '16

The proposal is in draft state. We have several open questions that we are still wrestling with in Section 2.6. Any feedback is greatly appreciated. You can track the evolution of our proposal online: <https://github.com/NullHypothesis/exit-pinning> --- 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 Target: n/a 0. Overview To mitigate the harm caused by malicious exit relays, this proposal presents a novel scheme -- exit relay pinning -- to allow web sites to express that Tor connections should preferably originate from a set of predefined exit relays. This proposal is currently in draft state. Any feedback is appreciated. 1. Motivation Malicious exit relays are increasingly becoming a problem. We have been witnessing numerous opportunistic attacks, but also highly sophisticated, targeted attacks that are financially motivated. So far, we have been looking for malicious exit relays using active probing and a number of heuristics, but since it is inexpensive to keep setting up new exit relays, we are facing an uphill battle. Similar to the now-obsolete concept of exit enclaves, this proposal enables web services to express that Tor clients should prefer a predefined set of exit relays when connecting to the service. We encourage sensitive sites to set up their own exit relays and have Tor clients prefer these relays, thus greatly mitigating the risk of man-in-the-middle attacks. 2. Design 2.1 Overview A simple analogy helps in explaining the concept behind exit relay pinning: HTTP Public Key Pinning (HPKP) allows web servers to express that browsers should pin certificates for a given time interval. Similarly, exit relay pinning (ERP) allows web servers to express that Tor Browser should prefer a predefined set of exit relays. This makes it harder for malicious exit relays to be selected as last hop for a given website. Web servers advertise support for ERP in a new HTTP header that points to an ERP policy. This policy contains one or more exit relays, and is signed by the respective relay's master identity key. Once Tor Browser obtained a website's ERP policy, it will try to select the site's preferred exit relays for subsequent connections. The following subsections discuss this mechanism in greater detail. 2.2 Exit relay pinning header Web servers support ERP by advertising it in the "Tor-Exit-Pins" HTTP header. The header contains two directives, "url" and "max-age": Tor-Exit-Pins: url="https://example.com/pins.txt"; max-age=2678400 The "url" directive points to the full policy, which MUST be HTTPS. Tor Browser MUST NOT fetch the policy if it is not reachable over HTTPS. Also, Tor Browser MUST abort the ERP procedure if the HTTPS certificate is not signed by a trusted authority. The "max-age" directive determines the time in seconds for how long Tor Browser SHOULD cache the ERP policy. After seeing a Tor-Exit-Pins header in an HTTP response, Tor Browser MUST fetch and interpret the policy unless it already has it cached and the cached policy has not yet expired. 2.3 Exit relay pinning policy An exit relay pinning policy MUST be formatted in JSON. The root element is called "erp-policy" and it points to a list of pinned exit relays. Each list element MUST contain two elements, "fingerprint" and "signature". The "fingerprint" element points to the hex-encoded, uppercase, 40-digit fingerprint of an exit relay, e.g., 9B94CD0B7B8057EAF21BA7F023B7A1C8CA9CE645. The "signature" element points to an Ed25519 signature, uppercase and hex-encoded. The following JSON shows a conceptual example: { "erp-policy": [ "start-policy", { "fingerprint": Fpr1, "signature": Sig_K1("erp-signature" || "example.com" || Fpr1) }, { "fingerprint": Fpr2, "signature": Sig_K2("erp-signature" || "example.com" || Fpr2) }, ... { "fingerprint": Fprn, "signature": Sig_Kn("erp-signature" || "example.com" || Fprn) }, "end-policy" ] } Fpr refers to a relay's fingerprint as discussed above. In the signature, K refers to a relay's master private identity key. The || operator refers to string concatenation, i.e., "foo" || "bar" results in "foobar". "erp-signature" is a constant and denotes the purpose of the signature. "start-policy" and "end-policy" are both constants and meant to prevent an adversary from serving a client only a partial list of pins. The signatures over fingerprint and domain are necessary to prove that an exit relay agrees to being pinned. The website's domain -- in this case example.com -- is part of the signature, so third parties such as evil.com cannot coerce exit relays they don't own to serve as their pinned exit relays. After having fetched an ERP policy, Tor Browser MUST first verify that the two constants "start-policy" and "end-policy" are present, and then validate the signature over all list elements. If any element does not validate, Tor Browser MUST abort the ERP procedure. If an ERP policy contains more than one exit relay, Tor Browser MUST select one at random, weighted by its bandwidth. That way, we can balance load across all pinned exit relays. Tor Browser could enforce the mapping from domain to exit relay by adding the following directive to its configuration file: MapAddress example.com example.com.Fpr_n.exit 2.4 Defending against malicious websites The purpose of exit relay pinning is to protect a website's users from malicious exit relays. We must further protect the same users from the website, however, because it could abuse ERP to reduce a user's anonymity set. The website could group users into arbitrarily-sized buckets by serving them different ERP policies on their first visit. For example, the first Tor user could be pinned to exit relay A, the second user could be pinned to exit relay B, etc. This would allow the website to link together the sessions of anonymous users. We cannot prevent websites from serving client-specific policies, but we can detect it by having Tor Browser fetch a website's ERP policy over multiple independent exit relays. If the policies are not identical, Tor Browser MUST ignore the ERP policies. If Tor Browser would attempt to fetch the ERP policy over n circuits as quickly as possible, the website would receive n connections within a narrow time interval, suggesting that all these connections originated from the same client. To impede such time-based correlation attacks, Tor Browser MUST wait for a randomly determined time span before fetching the ERP policy. Tor Browser SHOULD randomly sample a delay from an exponential distribution. The disadvantage of this defence is that it can take a while until Tor Browser knows that it can trust an ERP policy. 2.5 Design trade-offs We now briefly discuss alternative design decisions, and why we defined ERP the way we did. Instead of having a web server *tell* Tor Browser about pinned exit relays, we could have Tor Browser *ask* the web server, e.g., by making it fetch a predefined URL, similar to robots.txt. We believe that this would involve too much overhead because only a tiny fraction of sites that Tor users visit will have an ERP policy. ERP implies that adversaries get to learn all the exit relays from which all users of a pinned site come from. These exit relays could then become a target for traffic analysis or compromise. Therefore, websites that pin exit relays SHOULD have a proper HTTPS setup and host their exit relays topologically close to the content servers, to mitigate the threat of network-level adversaries. It's possible to work around the bootstrapping problem (i.e., the very first website visit cannot use pinned exits) by having an infrastructure that allows us to pin exits out-of-band, e.g., by hard-coding them in Tor Browser, or by providing a lookup service prior to connecting to a site, but the additional complexity does not seem to justify the added security or reduced overhead. 2.6 Open questions o How should we deal with selective DoS or otherwise unavailable exit relays? That is, what if an adversary takes offline pinned exit relays? Should Tor Browser give up, or fall back to non-pinned exit relays that are potentially malicious? Should we give site operators an option to express a fallback if they care more about availability than security? o Are there any aspects that are unnecessarily tricky to implement in Tor Browser? If so, let's figure out how to make it easier to build. o Is a domain-level pinning granularity sufficient? o Should we use the Ed25519 master or signing key? o Can cached ERP policies survive a Tor Browser restart? After all, we are not supposed to write to disk, and ERP policies are basically like a browsing history. o Should we have some notion of "freshness" in an ERP policy? The problem is that an adversary could save my ERP policy for example.com, and if I ever give up example.com, the adversary could register it, and use my relays for pinning. This could easily be mitigated by rotating my relay identity keys, and might not be that big a problem. o Should we support non-HTTP services? For example, do we want to support, say, SSH? And if so, how would we go about it? o HPKP also defines a "report-uri" directive to which errors should be reported. Do we want something similar, so site operators can detect issues such as attempted DoS attacks? o It is wasteful to send a 60-70 byte header to all browsers while only a tiny fraction of them will want it. Web servers could send the header only to IP addresses that run an exit relay, but that adds quite a bit of extra complexity. o We currently defend against malicious websites by fetching the ERP policy over several exit relays, spread over time. In doing so, we are making assumptions on the number of visits the website sees. Is there a better solution that isn't significantly more complex?

13 14

Building Torsocks for Armv7 - Build error
by Luca Bertoni 18 Oct '16

18 Oct '16

Goodmorning, I hope this is the correct section where to ask about building Torsocks. If that is the wrong place I apoligize and ask for a reference that can help me. So, I am trying to build torsocks for my armv7 smartphone. What I'm talking about is a cross-compilation, done using autools. After I have generated the configure script executing autogen.sh I configure torsocks using "./configure --host=armv7" and that doesn't raise errors. When I try to build it (using gnu-make) I get an error: ../src/lib/.libs/libtorsocks.a(log.o):(.data+0x0): multiple definition of `tsocks_loglevel' test_connect.o:(.data+0x0): first defined here I know what the error means but I can not figure out if I'm doing something wrong (that is the first time I cross-compile something so I am a newbie) or if there is a bug in the software. If it is a bug in the software I would like to submit it I downloaded torsocks from github (latest tag/release) and I am trying to build it using Debian 8.6 and gcc (Debian 4.9.2-10) 4.9.2. Thanks, Luca. Luca Bertoni

1 0

Re: [tor-dev] Call for help on testing core tor releases
by perky＠sigaint.org 14 Oct '16

14 Oct '16

Heya I'd like to help too - able to test on debian stable and testing. isabela at riseup.net: > > What we are asking volunteers: > > * Validate release signature/checksum > > * Does it build with _no_ Warnings? > > * Does "make test" pass? > > * Does "make test-network-all" pass? (you'll need chutney for this - > chutney does not work on Windows) > > * Does it work as a client? As a relay? As a hidden service ? > > * Does it work if you drop the binary into (eg) torpbrowser? > > > We are hoping to find enough people that we can test the releases on as > many OS's as possible. > Some OS-specific notes: > > * on Linux and BSD, Tor requires some dependencies (read INSTALL). > > * on OS X, you'll need to choose a package manager (HomeBrew, > MacPorts, Fink), or install dependencies from source, > > * either way, you will need to tell configure where the dependencies > are located. > > * on Windows, people sometimes have trouble building Tor. Help us > update our build instructions for Windows! > > > Our goals: > > * We hope to have tor alpha releases tested within a week of it going out > > * We hope to have people testing it on as many OS's as possible > > * Reduce the number of bugs found when we launch a release candidate > and/or stable release > > * We want operating systems and configurations other than the ones we > use in development to get tested BEFORE we declare the release stable. > >

2 1

performance of CREATE/CREATED handshake
by Rob van der Hoeven 13 Oct '16

13 Oct '16

Hi folks, I'm currently thinking about a new scalable network architecture for Tor. In order to get some idea about the performance of this architecture I need some data about the CREATE/CREATED handshake. This handshake involves PK encryption which is of course time consuming, and this probably determines the maximum client-capacity of a node in my new network architecture. I'm interested in two values: 1) The average circuit-rate of a single client (circuits/sec) 2) The average CPU-time it takes to perform a CREATE/CREATED handshake. Any data on these questions is much appreciated. Rob. https://hoevenstein.nl

3 4

prop224: Maximum introduction points in a descriptor
by David Goulet 11 Oct '16

11 Oct '16

Hello Tor-Dev! As part of some discussions that happened at the Seattle Tor Meeting few weeks ago, we've talked about the number of introduction points in an hidden service descriptor for proposal 224 (next generation HS). I've attached a spec change with the values ranging: Minimum: 0 - Default: 3 - Maximum: 20 The changes from what we have right now is basically the maximum. We would like to go from 10 to 20. It's arbitrary for now but one of the main reasons is to allow tools like OnionBalance to be able to scale more as we heard from large HS operators that they would like to go above 60 (10 * 6 HSDirs). Let us know what you think! Cheers! David

2 1

Re: [tor-dev] Proposal 274: A Name System API for Tor Onion Services
by 61wxgp60＠vfemail.net 10 Oct '16

10 Oct '16

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, Why run a separate process instead of using unix socket or TCP socket? > Since a Namecoin domain can point to IP addresses and ICANN-based DNS > names in addition to onion service names, and a Namecoin domain owner > might wish to switch between these configurations without causing > downtime or forcing their users to change behavior, I recommend against > this. However, see the open question below: > Open question: If a Namecoin domain points to an onion service, end > users might expect encryption to be built in, and this assumption will > be violated if the Namecoin domain switches to using an IP address. > However, Namecoin domains can include TLS fingerprints, which would be > enforced for both the IP address and the onion service address. Is it > sufficient to tell users that TLS is required if they want encryption > for Namecoin-addressed services, or is some additional mechanism > needed here to avoid bad things? How about specifying whether the Namecoin domain should point to .onion or clearnet in the domain? We can require that TLDs for such service must end in either: o o: The name points to a .onion name. o i: The name points to an IP address. o a: The name points to a clearnet domain name. So example.zkeyo points to 66tluooeeyni5x6y.onion. example.zkeyi points to 192.0.2.1 or (and?) 2001:db8::1. example.zkeya points to example.com. -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAEBCAAGBQJX+OqnAAoJEOoKZxebCIumIh0P/RaIZj9XYNngI6fVIcwQRGt9 OV9xPWNKkf53TcDi7HkkQLw5QerSe+Qmu6aMYBJ1J3s32QliX6Za+/AAfXwQ+051 JxOZKcg0RKGbTrjPMkF6mptkfSf+Xjkc8C5/BQp9TNcuy/CYmG88Soud7GidngW4 6lNvgJumxlP6YxpDvVg+VXpk8ry7k8kugoiKsFBKKFWYoEXUkDGRSXXLUiqC7hpv N6UleRnK7eeHBFu3K76l9j8tuW33xohomKdLf33BB4E1XBUQnPfw6DRdRns0IlqX BnWed7GGdd9ToQcWFKbRopYLRyTT7VX9IpgP1DJ689xchad8xnWcEz57aevyUlZ3 WaP5Vdrd3n/btYxAMbX65smAR98bkxSSr3NlFlpnympGnlgNW8bXtB6bjD2OQvmU uBLTXZsJWyCZAWGmVk5XJUU6leieZz6DLCQTRk36qWfHT5/0E6bDsvdUUQAWfw9M uHMoNKmVMXxTUhmQx3AVifQZ1w30jD/7ZsyF/Us3L0RpcUrCZKLvoDs5SIfD/VVe SCGFXYPC9VMxF+ElrmyrRC/IEGxEOgegdRwdSnnVi73PuOU2cxIR2iYyj845AE8f /JMN2rwULDVaxyREAhDafZRojkcJmQgv/prqN8U890Ihc2MUiGhgIqeDxCSAfwqN w6sZ30pOL9/BiBKzmTto =mMR3 -----END PGP SIGNATURE----- ------------------------------------------------- 75% of Americans don't like Clinton or Trump. Don't waste your vote, say 'No' to the US Oligarchy and give it to Gary Johnson. (paid for by VFEMail) ONLY AT VFEmail! - Use our Metadata Mitigator to keep your email out of the NSA's hands! $24.95 ONETIME Lifetime accounts with Privacy Features! 15GB disk! No bandwidth quotas! Commercial and Bulk Mail Options!

3 2

archive.is alternative for CFC addon
by bancfc＠openmailbox.org 09 Oct '16

09 Oct '16

Since there were plans to use this service to circumvent Cloudflare CAPTCHAs and now its behind Cloudflare itself (it requires users to execute JS to access content) what alternative is planned for the upcoming CFC addon? *** PS. My username was around long before this addon and is not related to it in any way.

2 1

Tor Browser downloads and updates graphs
by Georg Koppen 09 Oct '16

09 Oct '16

Hi all! So, Karsten, Nicolas and I were sitting together for a while and were looking at past data for figuring out how many users downloaded and updated their Tor Browser over time. We actually got more questions than we were able to answer but I guess that's fine for a start. Here are the graphs showing initial downloads, update pings and update requests over time: https://people.torproject.org/~karsten/volatile/torbrowser-annotated-2016-0… We annotated the grapgs a bit highlighting things we wanted people to point to. The initial downloads are the number of package downloads from the website for all supported platforms (Windows, OS X and Linux). Apart from spike (5) all events seem to be non-Tor Browser related. * On the downloads graph we seem to have a spike (5) in new downloads with the release of Tor Browser 6.0. Maybe because it was much more widely publicized in the media than previous/later releases? * On the same graph, a big spike (6) can be seen at the same day the new board got announced. * There are other spikes on the initial downloads graph (1, 3, 4) where we have no idea what happened while (2) is probably just an outlier. The update pings are made by Tor Browser instances roughly twice a day and they indicate the number of active Tor Browser users. More importantly, one can see the decrease or increase of Tor Browser usage over time. * As (2) in the downloads graph (7) seems to be an outlier as well. * We don't know what (8) or (9) is but it seems to us we are losing users over time and are only getting them back slowly if at all. A weekday/weekend pattern is visible there as well. The graph with the update requests is basically showing how fast users are updating to newly released Tor Browser versions. * (10) shows a large spike correlating to the 6.0 release. It is not clear to us where all those update requests were coming from given the update request pattern before/after 6.0. One plausible explanation could be that our infrastructure was heavily overloaded causing clients to retry fetching the update. We'd love to hear feedback, especially those that could shed light on the events we did not have an explanation for. Georg

11 21

Re: [tor-dev] Onioncat and Prop224
by str4d 08 Oct '16

08 Oct '16

On 27/04/16 22:31, grarpamp wrote: > On 4/25/16, Tim Wilson-Brown - teor <teor2345(a)gmail.com> wrote: >> >>> On 22 Apr 2016, at 17:03, grarpamp <grarpamp(a)gmail.com> wrote: >>> >>> FYI: The onioncat folks are interested in collaborating >>> with tor folks regarding prop224. >>> >>> https://gitweb.torproject.org/torspec.git/tree/proposals/224-rend-spec-ng.t… >> >> I'm interested in what kind of collaboration onioncat would like to do on >> prop224, next-generation hidden services. >> It would be great to work this out in the next few weeks, as we're coding >> parts of the proposal right now. > > Yep :) And I know Bernhard was hoping to get in touch with Roger > on this before long. > > Basically, prop224 HS being wider than 80 bits will break onioncat's > current HS onion <---> IPv6 addressing mechanism. > > They're looking at various backward compatibility options, as well > as possibly making side use of the HSDir DHT, or even integrating > more directly with the tor client. > Just FYI, I recently migrated all of I2P's spec proposals to the website, and came across a seven-year-old proposal that Bernhard wrote about improving I2P support in GarliCat: https://geti2p.net/spec/proposals/105-garlicat-name-translation I don't know how well it has aged, but given that Tor is now facing the same issues that I2P has, perhaps it can be of some use if resurrected from the dead :) > >> But the tor-onions mailing list is to discuss the technical details running >> onion services. > > Readers of tor-onions / newbies may have been unfamiliar with > onioncat. It's a way to get non-TCP between TorHS onions, thus in > the thread "Hidden datagram service". > > I think there are a nontrivial number of users interested in, and > using, non-strictly-TCP transport over an IPv6 tunnel interface. > For example, look at users of CJDNS... > > For which we should try to continue a way, in v2, to do that over > anonymous overlay network Tor / I2P. > There is already some work on doing this in I2P: https://github.com/majestrate/i2p-tools/tree/master/i2tun https://github.com/majestrate/i2p-tools/tree/master/pyi2tun I2P also natively supports non-TCP protocols if that helps (only datagrams implemented thus far). str4d

9 20

Re: [tor-dev] Proposal 274: A Name System API for Tor Onion Services
by Hugo Maxwell Connery 08 Oct '16

08 Oct '16

Hi, I think that this work is extremely important, and I applaud the authors and contributors for their work. It seems that it will also be complicated, semantically. What lies where, and which thing does what? The example recently about what is sent in the Host header is a good example of this challenge. I have below, in situ, made a few suggested corrections, and offered my suggestions on a few topics. I am not precious about my opinions and am happy to have them shot down by people with a deeper understanding of the challenge at hand. My overriding suggestion is to keep this as simple as possible in its initial iteration. It will almost certainly get more complex down the line, and working out what the core principles are early on will help guard against "feature creep". Well done, and good luck, Hugo NB: all comments prefixed with '> ' --- Filename: 274-naming-layer-api.txt Title: A Name System API for Tor Onion Services Author: George Kadianakis, Yawning Angel, David Goulet Created: 04-Oct-2016 Status: Draft Table Of Contents: 1. Introduction 1.1. Motivation 1.2. Design overview and rationale 2. System Specification 2.1. System overview [SYSTEMOVERVIEW] 2.2. System Illustration 2.3. System configuration [TORRC] 2.3.1. Tor name resolution logic 2.4. Name system initialization [INITPROTOCOL] 2.5. Name resolution using NS API 2.5.1. Message format 2.5.2. RESOLVED status codes 2.5.3. Further name resolution behavior 2.6. Cancelling a name resolution request 2.7. Launching name plugins [INITENVVARS] 2.8. Name plugin workflow [NSBEHAVIOR] 2.8.1. Name plugin shutdown [NSSHUTDOWN] 2.9. Further details of stdin/stdout communication 2.9.1. Message Format 3. Discussion 3.1. Using second-level domains instead of tld 3.2. Name plugins handling all tlds '*' 3.3. Deployment strategy 3.4. Miscellaneous discussion topics 4. Acknowledgements A.1: Example communication Tor <-> name plugin [PROTOEXAMPLE] A.2: Example plugins [PLUGINEXAMPLES] 1. Introduction This proposal specifies a modular API for integrating name systems with Tor. 1.1. Motivation Tor onion service addresses are decentralized and self-authenticated but they are not human-memorable (e.g. 3g2upl4pq6kufc4m.onion). This is a source of poor usability, since Internet users are familiar with the convenient naming of DNS and are not used to addresses being random text. In particular, onion addresses are currently composed of 16 random base32 characters, and they look like this: 3g2upl4pq6kufc4m.onion vwakviie2ienjx7t.onion idnxcnkne4qt76tg.onion vwakviie2ienjx6t.onion When Proposal 224 get deployed, onion addresses will become even bigger: 53 base32 characters. That's: llamanymityx4fi3l6x2gyzmtmgxjyqyorj9qsb5r543izcwymle.onion lfels7g3rbceenuuqmpsz45z3lswakqf56n5i3bvqhc22d5rrsza.onion odmmeotgcfx65l5hn6ejkaruvai222vs7o7tmtllszqk5xbysola.onion qw3yvgovok3dsarhqephpu2pkiwzjdk2fgdfwwf3tb3vgzxr5kba.onion Over the years Tor users have come up with various ad-hoc ways of handling onion addresses. For example people memorize them, or use third-party centralized directories, or just google them everytime. > Additionally, onion service providers have sometimes placed effort > in creating more readable and memorable names, for example: > > facebookcorewwwi.onion We believe that the UX problem of non-human-memorable problems is not actually solved with the above ad-hoc solutions and remains a critical usability barrier that prevents onion services from being used by a wider audience. 1.2. Design overview and rationale During the past years there has been lots of research on secure naming and various such systems have been proposed (e.g. GNS, Namecoin, etc.). Turns out securely naming things is a very hard research problem, and hence > It turns out that .. none of the proposed systems is a clear winner: all of them carry various trade-offs. Furthermore, none of the proposed systems has seen widespread use so far, which makes it even harder to pick a single project. Given the plenitude of options, one approach to decide which system > Given the plentitude ... is best is to make various decent name systems available and let the Tor community and the sands of time pick the winner. Also, it might be that there is no single winner, and perhaps different specialized name system should be used in different situations. We believe that by getting secure name systems actually get utilized by real users, the whole field will mature and existing systems will get battle-hardened. Hence, the contribution of this proposal is a modular Name System API (NSA) that allows developers to integrate their own name systems in Tor. The interface design is name-system-agnostic, and it's heavily based on the pluggable transports API (proposal 180). It should be flexible enough to accommodate all sorts of name systems (see [PLUGINEXAMPLES]). 2. System Specification A developer that wants to integrate a name system with Tor needs to first write a wrapper that understands the Tor Name System API (NS API). Using the Name System API, Tor asks the name system to perform name queries, and receives the query results. The NS API works using environment variables and stdin/stdout communication. It aims to be portable and easy to implement. 2.1. System overview [SYSTEMOVERVIEW] Here is an overview of the Tor name system: Alice, a Tor user, can activate various name systems by editing her torrc file and specifying which tld each name system is responsible for. For this section, let's consider a simple fictional name system, unicorn, which magically maps domains with the .corn tld to the correct onion address. Here it is: OnionNamePlugin 0 .corn /usr/local/bin/unicorn After Alice enables the unicorn plugin, she attempts connecting to elephantforum.corn. Tor will intercept the SOCKS request, and use the executable at /usr/local/bin/unicorn to query the unicorn name system for elephantforum.corn. Tor communicates with the unicorn plugin using the Tor NS API through which name queries and their results can be transported using stdin/stdout. If elephantforum.corn corresponds to an onion address in the unicorn name system, unicorn should return the onion address to Tor using the Tor NS API. Tor must then internally rewrite the elephantforum.corn address to the actual onion address, and initiate a connection to it. 2.2. System Illustration Here is a diagram illustrating how the Tor Name System API works. The name system used in this example is GNS, but there is nothing GNS-specific here and GNS could be swapped for any other name system (like hosts files, or Namecoin). The example below illustrates how a user who types debian.zkey in their Tor browser gets redirected to sejnfjrq6szgca7v.onion after Tor consults the GNS network. Please revisit this illustration after reading the rest of the proposal. | $~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~$ | 1. $ 4. GNS magic!! $ | User: SOCKS CONNECT to $ debian.zkey -> sejnfjrq6szgca7v.onion$ | http://debian.zkey/ $~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~$~~~~~~~$ | $ +-----|-----------------------------------------+ $ |+----v-----+ 2. +---------+| 3. $ ||Tor | debian.zkey |Tor || debian.zkey +-$-------+ ||Networking------------------------->Naming -------------------------> | ||Submodule | |Submodule|| Tor Name System API | GNS | || <------------------------- <------------------------- wrapper| || | 6. | ||5. | | |+----|-----+ sejnfjrq6szgca7v.onion +---------+|sejnfjrq6szgca7v.onion +---------+ +-----|-----------------------------------------+ | 7. | Tor: Connect to | http://sejnfjrq6szgca7v.onion/ v > Points for the phrase "GNS magic!!" (A little humor goes a long way in technical > specification documents) 2.3. System configuration [TORRC] As demonstrated in [SYSTEMOVERVIEW], a Tor user who wants to use a name system has to edit their configuration file appropriately. Here is the torrc line format: OnionNamePlugin <priority> <tld> <path> where <priority> is a positive integer denoting the priority with which this > where <priority> is a non-negative integer ... name plugin should be consulted. <tld> is a string which restricts the scope of this plugin to a particular tld. Finally, <path> is a filesystem path to an executable that speaks the Tor Name System API and can act as an intermediary between Tor and the name system. For example here is a snippet from a torrc file: OnionNamePlugin 0 .hosts /usr/local/bin/local-hosts-file OnionNamePlugin 1 .zkey /usr/local/bin/gns-tor-wrapper OnionNamePlugin 2 .bit /usr/local/bin/namecoin-tor-wrapper OnionNamePlugin 3 .scallion /usr/local/bin/community-hosts-file 2.3.1. Tor name resolution logic When Tor receives a SOCKS request to an address that has a name plugin assigned to it, it needs to perform a query for that address using that name plugin. If there are multiple name plugins that correspond to the requested address, Tor queries all relevant plugins sorted by their priority value, until one of them returns a successful result. If two plugins have the same priority value, Tor MUST abort. If all plugins fail to successfuly perform the name resolution, Tor SHOULD default to using the exit node for name resolution. XXX or not? because of leaks? > I suggest that the decision of whether to fallback to "DNS at exit node" may > be a domain specific choice. i.e Yes for .scallion and .hosts, but No for > .zkey and .bit. Thus, perhaps an additional, mandatory configuration for each > OnionNamePlugin configuration line of Yes|No to indicate if fallback should > occur. > > Thus: > OnionNamePlugin 0 .hosts Yes /usr/local/bin/local-hosts-file yes > OnionNamePlugin 1 .zkey No /usr/local/bin/gns-tor-wrapper no > OnionNamePlugin 2 .bit No /usr/local/bin/namecoin-tor-wrapper > OnionNamePlugin 3 .scallion Yes /usr/local/bin/community-hosts-file > > Another way to handle this is for the NS API to provide "please use DNS at exit > node" as a valid response type. E.g Tor asks the Banana Name API to resolve > orange.banana and the Banana Name API responses with an NS API status code which > means "please use DNS at exit node". > > This second idea may be the best, as each Name system will have its own idea > as to whether this is a good idea or not and thus Tor does not need to decide > and no configuration is required. > > Additionally this makes writing the "No Op" name api as trivial as responding > successfully to INIT and then just always returning the status code for "please > use DNS at exit node". > > Furthermore, it allows a name system to be able to choose this behaviour based > on context. i.e the name system knows that the orange.banana domain/service > is happy to have its name resolved with normal DNS but also knows that > pear.banana does not wish to have normal DNS ever used to resolve it. > > This distinction is something that Tor will never be able to make by itself. 2.4. Name system initialization [INITPROTOCOL] When Tor finds OnionNamePlugin lines in torrc, it launches and initializes their respective executables. When launching name plugins, Tor sets various environment variables to pass data to the name plugin (e.g. NS API version, state directory, etc.). More information on the environment variables at [INITENVVARS]. After a name plugin initializes and parses all needed environment variables, it communicates with Tor using its stdin/stdout. The first line that a name plugin sends to stdout signifies that it's ready to receive name queries. This line looks like this: INIT <VERSION> <STATUS_CODE> [<STATUS_MSG>] where VERSION is the Tor NS API protocol version that the plugin supports, > where VERSION is a comma-separated list of the Tor NS API protocol versions ... STATUS_CODE is an integer status code, and STATUS_MSG is an optional string error message. STATUS_CODE value 0 is reserved for "success", and all other integers are error codes. See [PROTOEXAMPLE] for an example of this protocol. 2.5. Name resolution using NS API Here is how actual name resolution requests are performed in NS API. 2.5.1. Message format When Tor receives a SOCKS request to an address with a tld that has a name plugin assigned to it, Tor performs an NS API name query for that address. Tor does this by printing lines on the name plugin stdout as follows: RESOLVE <QUERY_ID> <NAME_STRING> where QUERY_ID is a unique integer corresponding to this query, and NAME_STRING is the name to be queried. When the name plugin completes the name resolution, it prints the following line in its stdout: RESOLVED <QUERY_ID> <STATUS_CODE> <RESULT> where QUERY_ID is the corresponding query ID and STATUS_CODE is an integer status code. RESULT is the resolution result (an onion address) or an error message if the resolution was not succesful. See [PROTOEXAMPLE] for an example of this protocol. XXX Should <RESULT> be optional in the case of failure? > Yes. In the case of failure the name service will almost certainly not be > able to provide a valid onion address. Thus, it cannot provide this field. 2.5.2. RESOLVED status codes Name plugins can deliver the following status codes: 0 -- The name resolution was successful. 1 -- Name resolution generic failure. 2 -- Name tld not recognized. 3 -- Name not registered. 4 -- Name resolution timeout exceeded. XXX add more status codes here as needed > As mentioned above, I suggest that one of these RESOLVED status codes is > > <some number> -- Name use DNS at the exit node > > I suggest that the number is 1. 2.5.3. Further name resolution behavior Tor and name plugins MAY cache name resolution results in memory as needed. Caching results on disk should be avoided. > ... Caching results on disk SHOULD be avoided. > perhaps even MUST be avoided. Tor SHOULD abort (or cancel) an ongoing name resolution request, if it takes more than NAME_RESOLUTION_TIMEOUT seconds. XXX NAME_RESOLUTION_TIMEOUT = ??? > 4 seconds ? Tor MUST validate that the resolution result is a valid .onion name. XXX should we also accept IPs and regular domain results??? > A very good question. I suggest that the answer is No for both. > The NS API is designed to allow people to map various domain systems > into onion addresses, and thus, only onion addresses should be accepted. > > What is happening here is similar to the getent(1) and /etc/nsswitch.conf > We dont want getent passwd foo to return data about groups, but only those > about user accounts. XXX perhaps we should make sure that results are not names that need additional name resolution to avoid endless loops. e.g. imagine some sort of loop like this: debian.zkey -> debian-bla.zkey -> debian.zkey -> etc. > Yes, as expressed above. 2.6. Cancelling a name resolution request Tor might need to cancel an ongoing name resolution request (e.g. because a timeout passed, or the client is not interested in that address anymore). In this case, Tor sends the following line to the plugin stdout as follows: CANCEL <QUERY_ID> to which the name plugin, after performing the cancellation, SHOULD answer with: CANCELED <QUERY_ID> 2.7. Launching name plugins [INITENVVARS] As described in [INITPROTOCOL], when Tor launches a name plugin, it sets certain environment variables. At a minimum, it sets (in addition to the normal environment variables inherited from Tor): "TOR_NS_STATE_LOCATION" -- A filesystem directory path where the plugin should store state if it wants to. This directory is not required to exist, but the plugin SHOULD be able to create it if it doesn't. The plugin MUST NOT store state elsewhere. Example: TOR_NS_STATE_LOCATION=/var/lib/tor/ns_state/ > Where does Tor get this information? torrc I suppose. Thus, you need to > define the namespaces in torrc for setting these things. "TOR_NS_PROTO_VERSION" -- To tell the plugin which versions of this configuration protocol Tor supports. Future versions will give a comma-separated list. Plugins MUST accept comma-separated lists containing any version that they recognize, and MUST work correctly even if some of the versions they don't recognize are non-numeric. Valid version characters are non-space, non-comma printing ASCII characters. Example: TOR_NS_PROTO_VERSION=1,1a,2,4B "TOR_NS_PLUGIN_OPTIONS" -- Specifies configuration options for this name plugin as a semicolon-separated list of k=v strings with options that are to be passed to the plugin. Colons, semicolons, equal signs and backslashes MUST be escaped with a backslash. If there are no arguments that need to be passed to any of the plugins, "TOR_NS_PLUGIN_OPTIONS" MAY be omitted. For example consider the following options for the "banana" name plugin: TOR_NS_PLUGIN_OPTIONS=timeout=5;url=https://bananacake.com Will pass to banana the parameters 'timeout=5' and 'url=https://bananacake.com'. XXX Do we like this option-passing interface? Do we have any lessons from our PT experiences? XXX Add ControlPort/SocksPort environment variables. > Yes, this is almost certainly required. A name service may wish to use Tor's > network services to perform communication with its external name services. > OnioNS is a good example of this. It uses other onion services to do name services :) See [PROTOEXAMPLE] for an example of this environment 2.8. Name plugin workflow [NSBEHAVIOR] Name plugins follow the following workflow: 1) Tor sets the required environment values and launches the name plugin as a sub-process (fork()/exec()). See [INITENVVARS]. 2) The name plugin checks its environment, and determines the supported NS API versions using the env variable TOR_NS_PROTO_VERSION. 2.1) If there are no compatible versions, the name plugin writes an INIT message with a failure status code as in [INITPROTOCOL], and then shuts down. 3) The name plugin parses and handles the rest of the environment values. 3.1) If the environment variables are malformed, or otherwise invalid, the name plugin writes an INIT message with a failure status code as in [INITPROTOCOL], and then shuts down. 4) After the name plugin completely initializes, it sends a successful INIT message to stdout as in [INITPROTOCOL]. Then it continues monitoring its stdin for incoming RESOLVE messages. 6) When the name plugin receives a RESOLVE message, it performs the name resolution and replies with the appropriate RESOLVED message. 7) Upon being signaled to terminate by the parent process [NSSHUTDOWN], the name plugin gracefully shuts down. 2.8.1. Name plugin shutdown [NSSHUTDOWN] To ensure clean shutdown of all name plugins when Tor shuts down, the following rules apply for name plugins: Name plugins MUST handle OS specific mechanisms to gracefully terminate (e.g. SIGTERM). > I think that it would be valuable to be a little more specific here. Name plugins SHOULD monitor their stdin and exit gracefully when it is closed. > A very important point. This may obviate the need for "being more explicit" > as called for above. 2.9. Further details of stdin/stdout communication 2.9.1. Message Format Tor communicates with its name plugins by writing NL-terminated lines to stdout. The line metaformat is <Line> ::= <Keyword> <OptArgs> <NL> <Keyword> ::= <KeywordChar> | <Keyword> <KeywordChar> <KeyWordChar> ::= <any US-ASCII alphanumeric, dash, and underscore> <OptArgs> ::= <Args>* <Args> ::= <SP> <ArgChar> | <Args> <ArgChar> <ArgChar> ::= <any US-ASCII character but NUL or NL> <SP> ::= <US-ASCII whitespace symbol (32)> <NL> ::= <US-ASCII newline (line feed) character (10)> Tor MUST ignore lines with keywords that it doesn't recognize. 3. Discussion 3.1. Using second-level domains instead of tld People have suggested that users should try to connect to reddit.zkey.onion instead of reddit.zkey. That is, we should always preserve .onion as the tld, and only utilize second-level domains for naming. The argument for this is that this way users cannot accidentally leak addresses to DNS, as the .onion domain is reserved by RFC 7686. The counter-argument here is that this might be confusing to users since they are not used to the second-level domain being special (e.g. co.uk). Also, what happens when someone registers a 16-character name, that matches the length of a vanilla onion address? We should consider the concerns here and take the right decision. > As mentioned several times above, my opinion is that the NS API is > a mechanism for mapping other name systems into onion addresses. > If people want to do other "more interesting things" then they are > welcome to do that with their own overlay networks (e.g p2p, gnunet etc.). > > i.e what NS API is doing is allowing them to utilise their name system > through Tor if they have set up an onion service within Tor. If they have > just set up their service within their overlay network, then they can just > use its own infrastructure to assist people in reaching that service. > > I am rather confident that other people will have other opinions, > and I am happy to be "wrong" about this. 3.2. Name plugins handling all tlds '*' In [TORRC], we assigned a single tld to each name plugin. Should we also accept catch-all tlds using '*'? I'm afraid that this way a name system could try to resolve even normal domains like reddit.com . Perhaps we trust the name plugin itself, but maybe the name system network could exploit this? Also, the catch-all tld will probably cause some engineering complications in this proposal (as it did for PTs). > The only existing name system that can "reliably" handle * is DNS. > Thus, this is the 'no configuration required default' (DNS-at-exit-node). > However, it may be some peoples desire to override this 'no configuration > default'. So, perhaps allow it to be specificed in torrc. 3.3. Deployment strategy [snip ; no further comment by me].

1 0

Jump to page:

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

tor-dev