Local browser homepage for Tor Browser in Whonix

Development
61

set from TOR_HOMEPAGE to TOR_DEFAULT_HOMEPAGE as per environment variable to set TorBrowser homepage (#13835) · Issues · Legacy / Trac · GitLab :
set from TOR_HOMEPAGE to TOR_DEFAULT_HOMEPAGE as per https://trac.tor… · Whonix/whonix-welcome-page@2425778 · GitHub

62

Some great news… :smiley:

I’ve got a fully custom branded “about:whonix” Whonix Welcome Page URL successfully implemented…without needing any official TBB patches, environment variables, or Firefox install prompts.

Funny… Patrick reminded me of an approach I briefly considered last week but never attempted and slipped my mind until today.

I saw this page: Dev/Firefox Add-On - Whonix

"Live" Source Code Editing

Install Tor Browser as usual.

Make sure Tor Browser is closed.

Go into this folder:
/home/user/tor-browser_en-US/Browser/TorBrowser/Data/Browser/profile.default/extensions/

There will be a named:
tor-launcher@torproject.org.xpi.

Extract it.

Right Click → Extract Archive Here, Autodetect Subfolder

Now delete:
/home/user/tor-browser_en-US/Browser/TorBrowser/Data/Browser/profile.default/extensions/tor-launcher@torproject.org.xpi

Now you will have this folder:
/home/user/tor-browser_en-US/Browser/TorBrowser/Data/Browser/profile.default/extensions/tor-launcher@torproject.org/

When you now start Tor Browser, that folder will be used. This means, if you make changes, those will be in effect next time you start Tor Browser.

And I immediately remembered that I was going to test this as a method for implementing the Whonix Welcome Page, but had just forgotten about the idea.

And, so it works! :smiley:

Here’s the basic approach:

Whonix’s “tb-updater” and/or “tb-starter” packages could be responsible for extracting and editing the “torbutton@torproject.org.xpi” browser add-on into an expanded extensions directory “torbutton@torproject.org”.

To implement the custom “about:whonix” welcome page, it requires the following edits, which again can be implemented and checked upon each execution of the “tb-updater” and/or “tb-starter” packages.

[hr]

Edit File (append):
/home/user/tor-browser_en-US/Browser/TorBrowser/Data/Browser/profile.default/extensions/torbutton@torproject.org/chrome.manifest

component {23b527fc-ca92-4295-bcc2-cb7a5fe34a84} components/aboutWhonix.js
contract @mozilla.org/network/protocol/about;1?what=whonix {23b527fc-ca92-4295-bcc2-cb7a5fe34a84}

[hr]

Add File: This can be actual file or symlink to the whonix-welcome-page dir:
/home/user/tor-browser_en-US/Browser/TorBrowser/Data/Browser/profile.default/extensions/torbutton@torproject.org/components/aboutWhonix.js

Clone of “aboutTor.js”, based on: https://developer.mozilla.org/en-US/docs/Custom_about:_URLs

const kMODULE_NAME = "about:whonix";
const kMODULE_CONTRACTID = "@mozilla.org/network/protocol/about;1?what=whonix";
const kMODULE_CID = Components.ID("23b527fc-ca92-4295-bcc2-cb7a5fe34a84");

const kAboutWhonixURL = "file:///usr/share/homepage/whonix-welcome-page/whonix.html";

const Cc = Components.classes;
const Ci = Components.interfaces;
const Cu = Components.utils;
 
Cu.import("resource://gre/modules/XPCOMUtils.jsm");

function AboutWhonix() {}

AboutWhonix.prototype = {
  QueryInterface: XPCOMUtils.generateQI([Ci.nsIAboutModule]),
  classDescription: kMODULE_NAME,
  classID: kMODULE_CID,
  contractID: kMODULE_CONTRACTID,
  newChannel: function(aURI) {
    let ioSvc = Cc["@mozilla.org/network/io-service;1"]
                  .getService(Ci.nsIIOService);
    let channel = ioSvc.newChannel(kAboutWhonixURL, null, null);
    channel.originalURI = aURI;
    return channel;
  },
  getURIFlags: function(aURI) {
    return Ci.nsIAboutModule.ALLOW_SCRIPT;
  }
};

const NSGetFactory = XPCOMUtils.generateNSGetFactory([AboutWhonix]);

[hr]

Edit File (browser.startup.homepage):
/home/user/tor-browser_en-US/Browser/TorBrowser/Data/Browser/profile.default/extensions/torbutton@torproject.org/chrome/locale//browser.properties

# Default home page
browser.startup.homepage=about:whonix

[hr]

I have not implemented the dynamic page status changes yet, but, since this method gives us free reign over the entire Torbutton extension, this is doable and opens up any capability we’d like to implement in the browser.

We could really go well beyond just a custom homepage with this method, and achieve any unlimited Firefox extension capability we might please for the browser in Whonix.

Also, in addition to this method, the proposed patches of using environment variables to adjust the homepage URLs can work seamlessly in tandem with this approach. Those patches would just reduce the need for custom file edits of this method.

So, unless there is some showstopping externality that I’m not yet aware of (AppArmor compatible?), then this seems like a fully viable method. And we get a super slick custom “about:whonix” homepage URL for Whonix!

We would just need to program “tb-updater” and/or “tb-starter” to properly maintain the Torbrowser edits.

What do you think?

63

If we end up liking and going with this idea of bootstrapping into Tor Browser to give us unlimited custom browser functionality, along with “about:whonix”, then I’ve initiated a separate package “whonix-browser” for this feature.

[b]https://github.com/WhonixQubes/whonix-browser[/b]

Whonix Browser adds custom functionality to Tor Browser in Whonix OS.
64
Whonix's "tb-updater" and/or "tb-starter" packages could be responsible for extracting and editing the "torbutton@torproject.org.xpi" browser add-on into an expanded extensions directory "torbutton@torproject.org".
There are good and bad news. Good news first. ;)

Good news. tb-updater already has a configurable patch mechanism:

Apparmor probably won’t be an issue.

Bad news. Some issues.

It doesn’t work during times where Tor Browser Updaters are broken and where users need to manually update (Tor Browser: Manual Download) until those are fixed. Happened quite a few times in past.

The long term plan is to switch tor torbrowser-launcher:
https://phabricator.whonix.org/T18

Well, we might be able to add a patch that gives us post-install hooks:

But the worst is robustness, stability. Tor Browser and components are very fast changing. It might work for a while, but it would still be a hack. When they made some changes, this functionality could break. And even worse, it could totally break TorButton then. So any solution that does not require “live patching”, i.e. getting upstream to merge it should really be preferred.

To implement the custom "about:whonix" welcome page, it requires the following edits
Well, the very good news from your side is "very few patches in Tor Browser required for this", no?

Let’s suppose the TOR_DEFAULT_BROWSER environment variable patch gets merged. Just two more file edits required, no?

Three options we could all peruse.

a) the generic alternative distro proposal: custom browser homepage support for derivatives with “state” support

We haven’t posted the old proposal yet?

Haven’t found a link here and/or forgot. Should I do it?

b) Whonix homepage patch for TorButton

Since just two file edits are required. And since most (html) code (and images) can be stored outside the TorButton folder (?)… Couldn’t you turn this into a TPO trac ticket were we present this as alternative to a)? It would not be generic, but a small, easy patch. Perhaps we call it about:distro and then it would even be a generic patch that would implement a)?

c) hook mechanism proposal
When a) and b) fails or for other stuff, we could also propose a mechanism how distributions can plug in their code into TorButton with a clean hook mechanism. (Env vars pointing at source files that get sourced and/or executed by TorButton.)

65

Certainly we would need to handle these issues and have a robust implementation.

I think there may still be potential for this “whonix-browser” add-on.

But I will open a new thread to discuss that as a separate entity, as it should be.

[quote=“Patrick, post:64, topic:347”]Well, the very good news from your side is “very few patches in Tor Browser required for this”, no?

Let’s suppose the TOR_DEFAULT_BROWSER environment variable patch gets merged. Just two more file edits required, no?[/quote]

Yup. Depending upon exact implementation. Most likely, yes, correct.

[quote=“Patrick, post:64, topic:347”]a) the generic alternative distro proposal: custom browser homepage support for derivatives with “state” support

We haven’t posted the old proposal yet?

Haven’t found a link here and/or forgot. Should I do it?[/quote]

After going through the custom “about:whonix” test implementation, I think this proposal should probably be reworked some.

I can rework it, check it with you, and then post it to TPO Trac once good.

[quote=“Patrick, post:64, topic:347”]b) Whonix homepage patch for TorButton

Since just two file edits are required. And since most (html) code (and images) can be stored outside the TorButton folder (?)… Couldn’t you turn this into a TPO trac ticket were we present this as alternative to a)? It would not be generic, but a small, easy patch. Perhaps we call it about:distro and then it would even be a generic patch that would implement a)?[/quote]

A conditionally hardcoded Whonix-only alternative homepage might be too selfish of a patch for inclusion into ALL Tor Browsers to warrant their approval, no?

Generalizing this to an alternative custom homepage for other distributions is probably the way to go here.

With this, we could incorporate an alternative “about:” URL, since modifying content of “about:tor” seems taboo to them. And ensure that Torbutton’s status/state is passed down to the alternative homepage.

While “about:distro” makes sense to us geeks, I think “distro” is too much of a “techno-babble” word for everyday non-technical users. Using a broader term that is more user-friendly is probably best. Like: “about:homepage”, “about:startpage”, etc.

Or maybe it would be possible and enjoyed to support custom branded “about:” URLs that can be set by the distribution. For example, it seems as though Tails is considered and promoted as the king of Tor OS distributions by TPO people, so maybe a desire to have “about:tails” would be a socially influential basis for implementing custom branded “about:” URLs as alternative distro homepages, which we could use to implement “about:whonix”.

[quote=“Patrick, post:64, topic:347”]c) hook mechanism proposal
When a) and b) fails or for other stuff, we could also propose a mechanism how distributions can plug in their code into TorButton with a clean hook mechanism. (Env vars pointing at source files that get sourced and/or executed by TorButton.)[/quote]

Yes.

66
But I will open a new thread to discuss that as a separate entity, as it should be.
Good.
Yup. Depending upon exact implementation. Most likely, yes, correct.
Awesome.
After going through the custom "about:whonix" test implementation, I think this proposal should probably be reworked some.

I can rework it, check it with you, and then post it to TPO Trac once good.


Sounds good.

A conditionally hardcoded Whonix-only alternative homepage might be too selfish of a patch for inclusion into ALL Tor Browsers to warrant their approval, no?

Generalizing this to an alternative custom homepage for other distributions is probably the way to go here.


Indeed. The general proposal should be priority here. But if that fails, we can still submit a Whonix-only thing, if that is simpler. So two ifs here. Let’s start with the general one if possible and think about fallbacks if necessary.

With this, we could incorporate an alternative "about:" URL, since modifying content of "about:tor" seems taboo to them. And ensure that Torbutton's status/state is passed down to the alternative homepage.
Yes.
While "about:distro" makes sense to us geeks, I think "distro" is too much of a "techno-babble" word for everyday non-technical users. Using a broader term that is more user-friendly is probably best.
Agreed.
Like: "about:homepage", "about:startpage", etc.
Looks like "startpage.com" has captured the term "startpage". So I guess "about:homepage" is least confusing here.
Or maybe it would be possible and enjoyed to support custom branded "about:" URLs that can be set by the distribution. For example, it seems as though Tails is considered and promoted as the king of Tor OS distributions by TPO people, so maybe a desire to have "about:tails" would be a socially influential basis for implementing custom branded "about:" URLs as alternative distro homepages, which we could use to implement "about:whonix".
Yeah, if you can develop that and if that's not too difficult, go for it. Otherwise I also find "about:homepage" very good.
67

environment variable to set TorBrowser homepage (#13835) · Issues · Legacy / Trac · GitLab TOR_DEFAULT_HOMEPAGE was merged! :slight_smile:

68

Sounds good.

I don’t think “startpage” = “startpage.com”.

A bit of research shows that “startpage” is a broader term beyond the proprietary company “startpage.com”, which is most likely the broadly established concept that startpage.com just based their business trade name on.

For example:

A home page or index page is the initial or main web page of a website. It is sometimes also called the front page or main page (by analogy with newspapers), or written as "homepage."

A home page can also refer to the first page that appears upon opening a web browser, sometimes called the start page,

Many other references to “startpage” and “start page” in general use:

Just documenting an alternative perspective, in case “startpage” were desirable to use for this URL or more broadly.

I like the term “about:homepage” just the same.

However, any usage of “homepage” goes back to the issue of confusion with the “website homepage” vs. “browser homepage”, which other distributions, like Tails, would be subject to such confusing overlap of “homepage” terms with their project websites.

Which is why I originally thought “Whonix Startpage” would make a good reference name for the custom browser startpage.

Ubuntu already has established the convention of “about:startpage” for their own custom startpage in Firefox. Maybe this convention of “about:startpage” would make sense to port over for custom “browser startpages” of Tor Browser distributions, and simultaneously avoid confusion with distro project “website homepages”.

Another good reference page for “about:” URLs:

69

Good news. Awesome :smiley:

70

Alright. Convinced. “about:startpage” is better than "“about:homepage”.

71

Agreed.

72

I’m looking through the Torbutton add-on and it seems that the Torbutton status/state info is bound to the “about:tor” page URL.

This seems to be accomplished through a complex series of functions inside of the torbutton.js file inside the Torbutton add-on.

I’m trying to figure out a lean and simple patch to suggest for also allowing for this same status/state info to be passed down to other browser startpage URLs.

Will let you know as I make progress. :slight_smile:

73

I have made progress…

I’ve found the primary choke point in “torbutton/chrome/content/torbutton.js” for exclusively binding the status/state information to the “about:tor” URL. And I’ve implemented an example patch for this one function to allow for an alternative “about:startpage” URL.

Original function torbutton_is_abouttor_doc():

function torbutton_is_abouttor_doc(aDoc) {
  return (aDoc && /^about:tor$/i.test(aDoc.documentURI.toLowerCase()));
}

Function patch for “about:startpage” URL:

function torbutton_is_abouttor_doc(aDoc) {
  var aboutTor = new RegExp("^about:tor$", "i");
  var aboutStartpage = new RegExp("^about:startpage$", "i");
  if (aboutTor.test(aDoc.documentURI.toLowerCase()) || aboutStartpage.test(aDoc.documentURI.toLowerCase())) {
    var aboutURL = true;
  } else {
    var aboutURL = false;
  }
  return (aDoc && aboutURL);
}

[hr]

There’s a few key issues that I’ve discovered…

[hr]

1.

It seems Firefox’s sandbox does not let about: URLs call secondary files (css, images, dtd, etc) to the primary HTML file using the local disk “file://” protocol.

For example:

We can successfully call our primary “whonix.html” as the the value of the “kAboutTorURL” javascript constant using “file:///usr/share/homepage/whonix-welcome-page/whonix.html”.

And that “whonix.html” HTML page loads when you open the “about:startpage” URL.

But the secondary “file://” links in that “whonix.html”, such as CSS, images, etc, fail to load due to Firefox’s sandbox.

I know of a few ways to overcome this limitation:

Tested:

a) Include all webpage files into one single HTML file. This is not ideal, as it is less clean, forces use of data: URIs for images, and likely kills usage of DTD files and multi-language capabilities without clunky JavaScript.

b) Put all webpage files into an existing Firefox extension directory to call as “chrome://” links. This is obviously a bad idea.

c) Include a resource registration for our local webpage directory to call as “resource://” links.

This (c) is most likely the right way to go. But, currently, I only know how to do this in the chrome.manifest file, which means that a static registration of “file:///usr/share/homepage” would be universally registered, like this…

torbutton/chrome.manifest

resource startpage file:///usr/share/homepage/

Then webpage resources could be linked to like this “resource://startpage/whonix-welcome-page/filename.ext”.

But it would be more ideal if we could somehow make the registration of this resource directory be dynamic. Otherwise, everyone would be forced to accept it as a standard in Tor Browser.

Untested/Speculative:

d) Another theoretical/speculative/possible way may be using “overlays”, but I have not tested the basic viability of this method.

e) Another theoretical/speculative/possible way may be using “bootstrapped extensions”, but I have not tested the basic viability of this method.

Or maybe some other way I haven’t considered?

[hr]

2.

While I’ve got an alternative “about:startpage” working and passing status/state info down to the Whonix webpage, for some reason, it is not receiving the status/state without JavaScript enabled for the page. Where as, the “about:tor” page does not require JavaScript to be turned on in order to work with the status/state info.

The on-page JavaScript that enables the status/state info to work with the extension:

window.addEventListener("pageshow", function() {
  let evt = new CustomEvent("AboutTorLoad", { bubbles: true });
  document.dispatchEvent(evt);
});

I’m not yet sure why it naturally works, without enabling JavaScript, with “about:tor” but not “about:startpage”.

[hr]

3.

In order to accomplish custom dynamic about: URLs, such as “about:whonix”, “about:tails”, “about:whatever”, it will take finding a way to do dynamic variable chrome registrations.

Maybe “chrome.manifest” can somehow accept variables?

Maybe component registrations can occur in JavaScript files, maybe using something like “nsIComponentManager”?

Maybe bootstrapping in an external “chrome.manifest” file provided by the distro, maybe using something like “nsIComponentManager”?

74

I don’t have answers to most of your questions. Perhaps later I’ll have some more ideas.

[hr]

Yes. Everything in one file is not so pretty. But if all cords break, we could still do it. In that case we wouldn’t have a source file with everything in one file, but have some build script that concatenates those.

[hr]

(c) sounds best indeed.

Then webpage resources could be linked to like this "resource://startpage/whonix-welcome-page/filename.ext".

But it would be more ideal if we could somehow make the registration of this resource directory be dynamic. Otherwise, everyone would be forced to accept it as a standard in Tor Browser.


In that case, we’d have to name it something neutral, not including “whonix”-anything.

For our use case, we might be able to still use the whonix-welcome-page sub folder + a symlink.

[hr]

Could have to do with some other add-on / preference? I.e noscript? Likely they’re using a noscript white listing somewhere so the javascript also works for those who don’t want to use javascript for web?

[hr]

In order to accomplish custom dynamic about: URLs, such as "about:whonix", "about:tails", "about:whatever", it will take finding a way to do dynamic variable chrome registrations.
If you find no way, I think a static about:startpage isn't that bad.
75

No problem. A lot of it was rhetorical just in case somebody had ideas to contribute.

[hr]

Yeah. If all else fails, then dividing up source files for concatenating a single HTML file could make sense.

[hr]

quote=“Patrick, post:74, topic:347” sounds best indeed.

[quote]Then webpage resources could be linked to like this “resource://startpage/whonix-welcome-page/filename.ext”.

But it would be more ideal if we could somehow make the registration of this resource directory be dynamic. Otherwise, everyone would be forced to accept it as a standard in Tor Browser.[/quote]
In that case, we’d have to name it something neutral, not including “whonix”-anything.

For our use case, we might be able to still use the whonix-welcome-page sub folder + a symlink.[/quote]

Actually we could keep our “whonix” directory and page names.

The only forced standard part would be: “file:///usr/share/homepage/”

Then each distribution could use their own sub-directory:

  • resource://startpage/whonix-welcome-page/whonix.html → maps to → /usr/share/homepage/whonix-welcome-page/whonix.html
  • resource://startpage/tails-distro/index.html → maps to → /usr/share/homepage/tails-distro/index.html

Just not sure if they’d want to force everyone into the “/usr/share/homepage” directory?

This “/usr/share/homepage” directory is a convention we made up, not an pre-existing standard, right?

[hr]

[quote=“Patrick, post:74, topic:347”]2.

Could have to do with some other add-on / preference? I.e noscript? Likely they’re using a noscript white listing somewhere so the javascript also works for those who don’t want to use javascript for web?[/quote]

Possibly.

I don’t see “about:tor” in the NoScript Whitelist. Several other “about:” URLs there.

about:
about:addons
about:blocked
about:certerror
about:config
about:crashes
about:home
about:memory
about:neterror
about:plugins
about:privatebrowsing
about:sessionrestore
about:srcdoc
about:support
blob:
chrome:
moz-safe-about:
resource:

Maybe something in the TorLauncher add-on.

Maybe also it is that there is yet another Torbutton extension code injection somewhere that is specific to “about:tor” and the on-page JavaScript code is just there for redundancy.

[hr]

If you find no way, I think a static about:startpage isn’t that bad.[/quote]

Agreed. Accomplishing something generic like “about:startpage” would still be a good outcome.

76
Just not sure if they'd want to force everyone into the "/usr/share/homepage" directory?
Dunno. At some point we have to talk to them about such things. Might be acceptable. I mean, if anyone disagrees and later provides a patch that lifts that hardcoded folder, by all means.
This "/usr/share/homepage" directory is a convention we made up, not an pre-existing standard, right?
Right. (This is the context: https://github.com/micahflee/torbrowser-launcher/issues/152)
Then each distribution could use their own sub-directory:
Sounds good.

[hr]

Discussing this on irc.oftc.net #tor-dev could help. They might be able to answer such detail questions.

If no one is available, there is the tbb dev meeting. They’re discussing it here in this thread:
https://lists.torproject.org/pipermail/tbb-dev/2014-February/000000.html

If meeting up on IRC is okay with you and you have time at that point, we can both attend.

77

Dunno. At some point we have to talk to them about such things. Might be acceptable. I mean, if anyone disagrees and later provides a patch that lifts that hardcoded folder, by all means.[/quote]

Sounds good.

[quote=“Patrick, post:76, topic:347”]Discussing this on irc.oftc.net #tor-dev could help. They might be able to answer such detail questions.

If no one is available, there is the tbb dev meeting. They’re discussing it here in this thread:
https://lists.torproject.org/pipermail/tbb-dev/2014-February/000000.html

If meeting up on IRC is okay with you and you have time at that point, we can both attend.[/quote]

Thanks. I will check out that #tor-dev IRC channel.

Maybe I can generalize some of these issues and look for Firefox development support outlets as well.

[quote=“Patrick, post:76, topic:347”]If no one is available, there is the tbb dev meeting. They’re discussing it here in this thread:
https://lists.torproject.org/pipermail/tbb-dev/2014-February/000000.html

If meeting up on IRC is okay with you and you have time at that point, we can both attend.[/quote]

I am certainly open to this.

The tough part is predicting my availability beforehand.

If needing to use this option, I will let you know, assuming I can setup some availability on my end too.

Thanks Patrick!

78

Update:

I talked to a couple people and got some feedback.

I think I may have found the answer for accomplishing dynamic custom about: URLs for Torbutton.

Probably going to be with: JavaScript code modules

https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules

I still have to work on an implementation.

If successful, we will have a solution for proposing dynamic custom about: URLs for the browser startpage. Where the distro can set their own about: URL and local webpage path in environment variables.

Examples:

  • about:whonix
  • about:tails
79

Sounds good.

One thing to keep in mind: the more generic and [sometimes contradicting goals] smaller and simpler the proposed change, the more likely it is to have upstream review and merge the patch.

80

[quote=“Patrick, post:79, topic:347”]Sounds good.

One thing to keep in mind: the more generic and [sometimes contradicting goals] smaller and simpler the proposed change, the more likely it is to have upstream review and merge the patch.[/quote]

Totally agree! :smiley:

Trying to make it as lean of a modification as I can.

And trying to also play to the interests of Tails community and the general distro concept as well.