Circuit Display in Tor Browser being Refactored Upstream


I’ve been notified by the Tor Browser Team that, as part of the ongoing effort to deprecate Torbutton and move that functionality into Tor’s Firefox fork, the circuit display functionality is being rewritten. There is a concern that this might introduce compatibility issues for downstream projects like Whonix that need to hide the circuit display. They asked me to reach out to you with the following questions:

  1. What mechanism(s) is Whonix currently using to induce Tor Browser to hide the circuit display? (So that they don’t inadvertently break those mechanisms in the rewrite.)
  2. Since the relevant codebase is being rewritten anyway, are there changes they could introduce to those mechanisms that would make the interaction between Whonix and Tor Browser cleaner?
  3. To your knowledge, do Whonix and Tails do the same thing here, or do they use different mechanisms? If different, are the differences due to different requirements, and are there any changes that Tor Browser could make that would allow Whonix and Tails to use the same mechanism?
  4. Am I correct in guessing that it’s not desirable for Tor Browser to simply hide the circuit display if onion-grater rejects a query for the circuit, since doing so will result in onion-grater logging spurious warnings?
1 Like

If you have references to the plan of modifications/enhancements they plan to make, I’d like to see. I don’t know JavaScript so my input is limited to the desired behavior, but I know enough to understand why the Circuit Display was hidden.

  1. Current state: We fake the reply with onion-grater and TBB doesn’t like it, so it hides. The TBB behaviour of hiding is better than throwing an error, but I believe a short error message would be better because then it would be a handled error instead.

  2. A cleaner way was described above on item 1, but what we considered before, I wrote it here:

For the Tor Circuit View to appear, it requires valid credentials replied from the SENTCONNECT and if they are not the same credentials the Tor Browser sent by that tab, the circuits will not be Tor Browser wants to get the same SOCKS_USERNAME and SOCKS_PASSWORD it send for that tab in the first place, if it doesn,t the whole tab is not shown, you can check the reply with the Browser Console (Ctrl+Shift+J): Torbutton NOTE: no SOCKS credentials found for current document.
The interest is not showing the circuits per se, but at least showing literally Hop1, Hop2 and Hop2 to not confuse users why the tab is not shown. Another side effect is that it also hides the button New circuit for this site, but still available in the supermenu, but less convenient and not expected by the user to be this way.
If someone with JavaScript knowledge could patch upstream, at least showing the New circuit for this site even if the credentials don’t match would be a start, but it currently is not shown because either the Tor Button shows completely or doesn’t show at all. A more difficult task would be to instead of not showing the circuit view, if the browser fails to get the correct credentials, it could show a helpful text that it can’t show the circuits because it could not determine the stream. There is a lower chance of rewriting the countries and IPs of the circuits to fake data if it can’t establish the link because upstream could consider this a workaround. Anyway, a better user experience is expected from the Tor Circuit View, even if an error message, so at least it is understood by non-developers or for people not familiarized with the Tor Button and Tor Browser source code.

  1. To my knowledge, Whonix and Tails do the same thing, via onion-grater. I don’t think linking to the profiles will help because the profiles need to adapt depending on the use case and what TBB sends. TBB profile: Tails and Whonix.

  2. The only spurious warnings I know is to the “Browser Console”: Torbutton NOTE: no SOCKS credentials found for current document. Gateway doesn’t know if the client only is using TBB or is using many other tor applications, therefore the choice of hiding every circuit request was made. This probably doesn’t happen in Tails because they use onion-grater’s option restrict-stream-events and the client address is on a different network namespace but still in the same machine, so they don’t need to worry about circuit leaking to other applications as they are restricted by TBB netns. The desired response from TBB from my point of view is to hide the circuit when it can’t get the desired information and not log to an user facing dialog that it couldn’t get the information. What is:

  • OK: Errors in the Browser Console.
  • NOT desirable: Errors at the Circuit Display, this could cause more confusion to the user. Maybe a warning message in place of the Circuit Display would be better so the error is handled instead of handled by hiding.

Summary: We don’t hide the circuit view directly by modifying TBB, it is a consequence of tor-circuit-display.js not liking the almost blank response it received from onion-grater. A desired behaviour in my point of view would be to handle the error with maybe an error message.

1 Like

That you for bringing this up, it’s much appreciated!

Just the mechanism which was described by @nyxnor. It’s blocked by onion-grater and then Tor Browser (TB) won’t show it. Non-ideal but good enough for years.

An environment variable to hide the circuit display would be cleaner than TB trying to ask for some information and then not receiving it.

I’ll answer more within hopefully 24 hours.

  • file based: I was considering to suggest using configuration files or even /etc/torbrowser.d but that would introduce extra complexity, I guess. Also I think Tor Project wants to keep supporting a similar mechanism for Windows users. Meaning more time to implement it and probably more bugs due to different operating systems needing to parse different folders.
  • environment variables based: Hence, keeping support for the already existing environment variables seems the most compatible and most simple way forward.

Therefore I suggest keep the existing environment variables supported. These are as currently used by Whonix:

export TOR_SOCKS_IPC_PATH="/run/anon-ws-disable-stacked-tor/"
export TOR_CONTROL_IPC_PATH="/run/anon-ws-disable-stacked-tor/"

(TOR_USE_LEGACY_LAUNCHER is likely already or will be obsolete after the rewrite.)

Also used but maybe unrelated but since its about environment variables:


And for 1 thing I would like to make a feature request. The following does not exist yet but would be great if it did:


That would result in:

  • not showing the TB circuit display
  • TB not attempting to ask the Tor ControlProtocol for any information required for the TB circuit display

From grepping Tails’s source code I found:

config/chroot_local-includes/usr/bin/tor-browser:export TOR_CONTROL_HOST=''
config/chroot_local-includes/usr/bin/tor-browser:export TOR_CONTROL_PORT='9051'
config/chroot_local-includes/usr/bin/tor-browser:export TOR_CONTROL_PASSWD='passwd'
config/chroot_local-includes/usr/bin/tor-browser:export TOR_NO_DISPLAY_NETWORK_SETTINGS='yes'

Which means…

  • TB generally (outside of a Whonix or Tails context) is using the newer unix domain socket files.
  • Whonix is using the newer unix domain socket based method.
  • But Tails is still using the old IP/port method.

I don’t know any methods Tor Project (TPO) could make any changes that would help to allow Whonix and Tails to use the same mechanism. The only thing if TPO wants to simplify something would be dropping support for IP based environment variables (TOR_CONTROL_HOST). But that would require Tails ports to the newer unix domain socket based method. And also I don’t know if TPO prefers to keep support for IP based environment variables for the sake of users other than Whonix/Tails users or how much extra complexity this is to keep for TPO. Also years ago there was a ticket at the TPO issue tracker to remove TCP based networking from TB for the sake of better protection from leaks (outside a Whonix/Tails context). If that is coming one day, then Tails needs to port to unix domain sockets anyhow.

I am not too worried about any spurious warnings in Whonix-Gateway onion-grater log which doesn’t log by default. (Can be enabled in settings, which is documented.)

However, the export TOR_NO_CIRCUIT_DISPLAY=1 which I mentioned above would be a much cleaner and very future-proof method.

Happy to elaborate if there are any further questions.

That’s really helpful info, thanks @Patrick . I pondered this a bit more today, and something occurred to me. At the moment, the circuit display in Tor Browser is used to show 3 different types of information to the user:

  1. Non-exit relays. This violates the Whonix threat model, thus Whonix hides this data from Tor Browser via onion-grater.
  2. Exit relays. AFAICT this data is trivially easy for Tor Browser to obtain anyway, since it could simply open a connection to from the same circuit. I don’t think having access to this information is a security risk given the Whonix threat model (am I mistaken?). This data is also useful from a UX perspective, since it helps the user analyze geoblocking by websites.
  3. Name-to-onion mapping for FPF and Namecoin domains. This data is public for both FPF and Namecoin domains. Similarly to exit relays, I don’t think having access to this data violates the Whonix threat model, and it has a UX benefit (also a security benefit if the user wants to manually inspect the onion address to make sure it matches their expectations).

Given the above, I don’t think it’s ideal to hide the entire circuit display in Whonix. I think it would be better UX (and not any worse security-wise) to only hide the non-exit relay information, while still displaying the exit relay data and the FPF/Namecoin data.

I suppose this might require mildly more interesting onion-grater rules in the case of exit relays and Namecoin. Since Namecoin isn’t yet supported in Whonix’s onion-grater rules anyway, that’s not really an issue for the purpose of this discussion, and it’s my job to find a way to make that work (which I have no objection to). FPF naming doesn’t use the control port AFAIK, so Whonix doesn’t need to worry about onion-grater rules there.

So: a few questions for @Patrick :

  1. Do you concur with my above analysis?
  2. Would it be problematically difficult to make onion-grater allow access to exit relays of the workstation but not allow access to either non-exit relays of any circuit or exit relays belonging to a circuit that doesn’t belong to the workstation?
  3. If this is feasible, would it be a good idea for me to suggest to the Tor Browser Team that they keep the circuit display visible in Whonix (via whatever signaling mechanism we agree on) but hide the non-exit relays (and don’t request that info via the control port)?
1 Like


Also agreed.

[1] Probably also yes. Do you have an example?

Generally, yes.

([1] Pending example from above.)

  • A) my basic proposal: My above two posts describe a simple proposal that TPO hopefully could implement with minimal overhead for special technical requirements by Tails, Whonix.
  • B) your more aspiring proposal: The functional Tor circuit display inside Whonix-Workstation would certainly be the better implementation usability wise and of course much nicer to have feature parity in TB, Tails, Whonix. That however I thought might require quite a bit more discussion, planning, development work. I thought probably too much to realistically suggest this.

For B), it’s not even clear to me what feature to request from TPO to suite the “Tor circuit view restricted mode”. Would this require modifications in TB and/or in Tor? Such as patching Tor to provide an option ControlProtocolStrict 1 or so could redact sensitive information. But since C programming language based little-t-tor is as far as I understand in maintenance mode pending TPO currently working on arti, that didn’t seem realistic. Also if I am not mistaken I’ve read on the TPO issue tracker that arti might not re-implement the Tor control protocol and it’s still undecided how that functionality would be re-implemented.

It was previously attempted by @nyxnor to develop an onion-grater profile which does Tor circuit display related redaction of sensitive information. That seems too difficult. That attempt stalled. And I didn’t think this is realistic to ever accomplish.

Therefore I’d suggest to go for the basic implementation (A) which seems very realistic.

Any improvement contributed on top of that would of course be most welcome.


Yes. Failed so far. See above.

I don’t know if it’s feasible but I guess it would be extra effort on the TB development side. Feel free to suggest this (B) but I would prevaricate to mention if that seems difficult, that the more basic implementation (A) can be a fallback.

Hello Jeremy Rand, please read again my post above: Circuit Display in Tor Browser being Refactored Upstream - #2 by nyxnor, it already answers your questions.

The problem is not showing the last exit relay, the problem is that TBB expects the same SOCKS_PASSWORD and SOCKS_USERNAME it sent in the first place via the tor’s control SENTCONNECT stream event.
If we allow that information to the Gateway, as onion-grater runs on a separate host related to the client, we can’t choose which applications have access to that information, therefore every application will have access to the SOCKS_{USERNAME,PASSWORD} sent to tor’s control protocol.

On top of that, onion-grater’s restrict-stream-events does not currently supports remote clients, therefore, any client would be able to see every other client’s streams.

Therefore, we only need that TBB to do not fail, throws errors, on the circuit display if it can’t get the circuit it wanted (that is the way it is know, I just want it to keep that way).

The improvement suggestions by Patrick is to have an environment variable for that, in case it would throw an error if trying to see a circuit display, an environment variable would prevent it from happening, prevent the circuit display from being show.

1 Like

Let’s conjecture that Tor Project is willing to add this variable to Tor Browser, and that its behavior (when added) is to disable the circuit display completely. Let’s also conjecture that Arti adds in the future an API that can safely expose the exit relay and Namecoin name-to-onion mapping given Whonix’s threat model (which seems plausible, though will probably not happen soon).

  1. Am I correct in guessing that we would then desire the environment variable to be repurposed, to only disable the non-exit relay part of the circuit display?
  2. Is there a better name we could give to this environment variable, which accurately conveys that the intent is to disable display/retrieval of non-exit relays, so that we don’t have to deal with renaming the variable after the Arti API is updated?

I’m not sure what you’re asking for an example of. Name-to-onion mapping? UX benefit of seeing it? Security benefit of seeing it?

Agreed that this functionality will probably have to wait for Arti. I suspect that some of the control port API changes that Namecoin proposed (which are also blocked by Arti transition) will be easily adaptable to make this use case more feasible too, but I’d have to inspect the circuit display code in Tor Browser to better understand exactly what changes would be needed.

Suggested spectrum of changes we can request, in ascending order of both complexity and UX quality (Tor Project would pick from these, and could choose one option initially and then iteratively improve later):

  1. If the circuit details are not available via control port, detect that case and hide the entire circuit display. (Basically the same as the status quo before Torbutton was removed.)
  2. Same as (1), but instead of hiding the circuit display, show the display but with placeholder addresses for the relays and the Namecoin onion address. (There’s already a mechanism to show placeholder addresses for relays that only the onion server knows, so this should be pretty easy code-wise.) This is a UX benefit because it allows the user to see FPF onion addresses, and also conveys to the user that multiple relays are being used. (I’m not sure what the circuit display normally does to indicate that Tor2Web mode or Single-Onion mode have fewer relays than usual, but those are unusual edge cases and I don’t see a problem with just displaying the usual number of placeholder relays in such cases.)
  3. Same as (2), but also support an environment variable to disable even attempting to read the circuit details.
  4. Same as (3), but request+show exit relay details if available. Testing the UX on this can be done before the Arti transition, but doing it securely in production will be blocked by the Arti transition.

@Patrick Is this a reasonable spectrum? Are there other options I should include?

Just to make sure I understand the threat model: the security issue with this is that we don’t want one application to be able to inject streams into another application’s circuits, right? Or is there some other reason why this is a problem?

That issue in particular is already on my radar for fixing due to also affecting Namecoin. However, since this issue does not affect Tails, I don’t think it should block work from being done, since if we can get this working properly on Tails, that’s still a benefit, and we can worry about supporting Whonix afterward.

@Patrick The current plan is that I will have a meeting with the Tor Browser Team 2 weeks from today to discuss how to proceed. So it would be ideal to have our proposal(s) figured out by then. Looks like that shouldn’t be a hard deadline to meet.

1 Like

As far as I know, the SOCKS credentials do not have the purpose of authentication, although may seem like it, it is only useful for Applications/Clients to follow along their streams, such as Tor Browser Bundle Tabs, where each tab has a circuit.
About ‘inject’:

  • It can’t manipulate the stream as REDIRECTSTREAM is filtered
  • It will reuse the circuit as the SOCKS credentials are the same, meaning it can confuse the client.
    The SOCKS_USERNAME in the case of TBB is the host the stream is targeted to, so even if trying to not show the host, it will be shown.

As of know, as it is blocked the WS can still try to find every site it is trying to reach, but I prefer not to be the GW to show that information.

See onion-grater development - #58 by nyxnor
And yes, it is not a blocker, just mentioning.

Preferred by me.

Also good but without the item 2.

That is not something the browser knows via external means, such as using an IP checker, rather it tries the tor control method.

1 Like

Yes, this is what I was referring to. I can’t think of any specific attacks here, but it still seems like maybe a bad idea.

OK yes, this is the part I had forgotten about. Best to not share that info.

May I ask what the issue is with item 2?

1 Like

First, I didn’t comment on number two because I don’t understand namecoin’s FPF onion addresses.

The problem I see with placeholder addresses is that they can vary a lot.
Let’s take Vanguards for example, it can make strings some hops (1-2) longer (depending if the client and/or server have it), therefore the hop count on the placeholder circuit would be wrong. You also mentioned about Single-Onion mode, which has the opposite effect, 2 hops less.

Can you link?

I don’t know what FPF means and I am presuming it is related to Namecoin onion addresses.

1 Like

No, please not. That would be a different environment variable. As in A) basic implementation vs B) sophisticated implementation.

Cannot think of one yet. Maybe later. Anyone?



The environment variable to completely disable it seems useful in either case.

Just the “simple” hiding environment variable. Otherwise great!

Namecoin and FPF naming both use human-readable aliases for onion services; the circuit display typically shows both the human-readable alias and the base32 onion address.

I talked to Pier and Duncan from the Tor Browser Team and Tor UX Team. Turns out that Tor Browser (as of a few weeks ago in Nightly) no longer shows multiple placeholder relays; it now collapses the three onion relays into a single row. They are favorable to doing similar collapsing of the guard + middle relay into a single row if Whonix is in use. So that should resolve the UX confusion that Vanguards and Tor2Web mode would have had.

They are also favorable to displaying the FPF name mapping in the circuit display even if all the the relay addresses are redacted. (Namecoin didn’t come up in the discussion with them since Namecoin isn’t supported in Whonix yet, but I assume that once Namecoin is supported in Whonix, the UX would be the same as with FPF naming.)

FPF == Freedom of the Press Foundation; they operate the securedrop.tor.onion eTLD. Similar use case to Namecoin, but totally different implementation and security model (FPF is centralized and acts as a trusted 3rd party).

I’m a little confused why we would need two different variables here. AFAICT the high-level intent of the variable here is to convey to an application (not necessarily Tor Browser) that it’s running under a sandboxed environment that will prevent it from asking the control port for data that could let the application deanonymize itself, so that it won’t bother making such requests (and will optimize its UX to not need that data). It seems that different types of applications will need to make different adjustments to their behavior to accomodate this. Or, put another way: is there any specific high-level use case where the user (or the OS) would explicitly want to tell applications that they shouldn’t try to discover their exit relay?

https://nytimes.securedrop.tor.onion/ is a human-meaningful name that maps to a base32-encoded onion address (I don’t have that base32 onion address on me at the moment, but hopefully you get the idea).

(Side note – due to various AFK issues on my end, this topic got delayed. Hoping to have this all figured out by end of this week, but if it takes longer, such is life.)

1 Like

Sounds all good to me.

Since you said “repurpose”.

TOR_NO_CIRCUIT_DISPLAY=1 shouldn’t be re-purposed. It’s name is simple and non-ambiguous. It’s implementation I expect to would also be rather simple by comparison.

Please don’t re-purpose TOR_NO_CIRCUIT_DISPLAY=1 which is currently very simple to do something more complex.

Yes, that would be TOR_NO_CIRCUIT_DISPLAY=1.

Yes, in case the more complex / different mechanism to get sanitized replies from control protocol is either disabled or broken. Then TOR_NO_CIRCUIT_DISPLAY=1 can safe the day and is better than nothing.

  • A) basic / simple implementation: TOR_NO_CIRCUIT_DISPLAY=1
  • and
  • B) more complex, sophisticated implementation: Tor control protocol sanitizing / redaction. For that, it seems best to use a different named environment variable.

My request was to avoid re-purposing A) TOR_NO_CIRCUIT_DISPLAY=1 for the purpose of B) since that seems confusing.

May I suggest to write a concept proposal here in the wiki? onion-grater, a Tor Control Port Filter Proxy

Editing possible with or without account. Don’t worry about any form requirements. Chapter name or other stylistic choices. Really just a suggestion as a collaborative tool. Not supposed to add unnecessary bureaucratic hurdles.

Then I could edit / make a revision. I doubt we’ll need more 1 or 2 revisions. I am just guessing that proposal and revision editing might conclude this at this stage since I don’t see any disagreeable items.