Using corridor, a Tor traffic whitelisting gateway with Whonix.

Introduction[edit]

corridor is a Tor traffic whitelisting gateway. It is a filtering gateway, not a proxying gateway and can also be configured as a BridgeFirewall.

Connecting to corridor before Tor[edit]

Introduction[edit]

corridor configurations are only possible in Qubes-Whonix^™. Non-Qubes-Whonix is unsupported at present. ^[1] ^[2]

It is possible to configure Whonix-Gateway^™ (sys-whonix) to use corridor as a local proxy to establish the following tunnel:
User → corridor → Tor → Internet

This is not necessarily more anonymous, but it does provide an additional fail-safe -- a Tor traffic whitelisting firewall that helps protect against accidental clearnet leaks (hypothetical clearnet leak bugs in Whonix). As corridor's project description states: "... it cannot prevent malware on a client computer from finding out your clearnet IP address."

corridor is mostly useful for developers and auditors of Whonix, along with advanced users who would like to have an additional safety net. Note that it cannot protect from hypothetical bugs affecting Qubes' ProxyVM; a physically-isolated, standalone corridor-Gateway is necessary to cover that leak vector.

corridor does not increase the tunnel length, meaning no more relays are added between a user and the destination. Users interested in this configuration should read Tunnels/Introduction.

Warning[edit]

By default, the following instructions will result in:

The Debian tor package being installed.
Thereby automatically connecting to the Tor public network.
Downloading of corridor from Project-APT-Repository.

This behavior might be dangerous if users need / want to hide Tor and Whonix from the ISP.

If Whonix is already in use, then configuring a second running instance of Tor will ensure that it is independent of the one running inside Whonix-Gateway (sys-whonix). From the ISP's perspective, the user will have a different network Fingerprint. The anonymity impact should be no worse than running Tor Browser, or system-tor and Whonix at the same time.

dom0 Setup[edit]

Create a new standalone ProxyVM called sys-corridor based on the Debian bookworm template:

Qube Manager → Create new Qube → enable 'Standalone qube based on a template' → name: sys-corridor → template: debian → OK

Enable the corridor qvm service:

Qube Manager → left-click sys-corridor → right-click → Qube settings → services → type in the field → corridor → press + → press OK

sys-corridor Setup[edit]

If a BridgeFirewall is required, first configure Tor to use bridges before installing corridor. All the following steps should be applied in Qubes' Debian template.

Install corridor[edit]

Start sys-corridor and open a terminal using Qubes start menu.

There are two different options to enable the Whonix APT repository. Choose one. ^[3]

1. Install package extrepo.

sudo apt install extrepo

2. Enable the stable whonix APT repository. (See footnote for other options.) ^[4]

===

Whonix

sudo extrepo enable whonix

===

Qubes-Whonix Template (whonix-workstation-17)

sudo http_proxy=http://127.0.0.1:8082 https_proxy=http://127.0.0.1:8082 extrepo enable whonix

3. Advanced options.

For advanced options such as clearnet over Tor or onion. ^[5]

Please press on expand on the right side.

Optional.

Install apt-transport-tor.

Install package(s) apt-transport-tor following these instructions

Platform specific notice.

Non-Qubes-Whonix: No special notice.
Qubes-Whonix: In Template.

Update the package lists and upgrade the system .

sudo apt update && sudo apt full-upgrade

Install the apt-transport-tor package(s).

Using apt command line --no-install-recommends option is in most cases optional.

sudo apt install --no-install-recommends apt-transport-tor

Platform specific notice.

Non-Qubes-Whonix: No special notice.
Qubes-Whonix: Shut down Template and restart App Qubes based on it as per Qubes Template Modification .

Done.

The procedure of installing package(s) apt-transport-tor is complete.

Find out filename.

ls -la /etc/apt/sources.list.d/extrepo_*

NOTE: Filename will be different if using a repository other than the stable repository such as the testers repository.

Open file /etc/apt/sources.list.d/extrepo_kicksecure.sources in an editor with root rights.

This box uses sudoedit for better security.

sudoedit /etc/apt/sources.list.d/extrepo_kicksecure.sources

NOTES:

When using Qubes-Whonix, this needs to be done inside the Template.

sudoedit /etc/apt/sources.list.d/extrepo_kicksecure.sources

After applying this change, shutdown the Template.
All App Qubes based on the Template need to be restarted if they were already running.
This is a general procedure required for Qubes and unspecific to Qubes-Whonix^™.

This is just an example. Other tools could achieve the same goal.
If this example does not work for you or if you are not using Whonix, please refer to this link.

sudoedit /etc/apt/sources.list.d/extrepo_kicksecure.sources

Choose either option A) or B).

A) Clearnet over Tor Repository: To enable clearnet over Tor, tor+ needs do be prepended in front of the https. The same in other words, look for Uris: https and replace it with Uris: tor+https .
B) Onion Repository: To enable onion, look for the line starting with Uris:. Delete the whole line. Or out-comment it by adding as hash ("#") in front of it. Then add a new line: Uris: tor+http://deb.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion

4. Done.

The Whonix APT repository has been enabled ^[6]

Add Signing Key

Complete the following steps to add the Whonix Signing Key to the system's APT keyring.

Open a terminal.

1. Package curl needs to be installed.

Install package(s) curl following these instructions

Platform specific notice.

Non-Qubes-Whonix: No special notice.
Qubes-Whonix: In Template.

Update the package lists and upgrade the system .

sudo apt update && sudo apt full-upgrade

Install the curl package(s).

Using apt command line --no-install-recommends option is in most cases optional.

sudo apt install --no-install-recommends curl

Platform specific notice.

Non-Qubes-Whonix: No special notice.
Qubes-Whonix: Shut down Template and restart App Qubes based on it as per Qubes Template Modification .

Done.

The procedure of installing package(s) curl is complete.

2. Download Whonix Signing Key. ^[7]

Choose your operating system.

If you are using Debian, run.

Choose TLS or onion.

TLS (Debian)

sudo curl --tlsv1.3 --output /usr/share/keyrings/derivative.asc --url https://www.whonix.org/keys/derivative.asc

onion (Debian)

Downloading over onion requires an already functional system Tor.

sudo torsocks curl --output /usr/share/keyrings/derivative.asc --url http://www.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion/keys/derivative.asc

If you are using a Qubes Debian Template, run.

Choose TLS or onion.

TLS (Qubes)

sudo http_proxy=http://127.0.0.1:8082 https_proxy=http://127.0.0.1:8082 curl --tlsv1.3 --output /usr/share/keyrings/derivative.asc --url https://www.whonix.org/keys/derivative.asc

onion (Qubes)

Downloading over onion requires an already functional system Tor.

sudo torsocks curl --output /usr/share/keyrings/derivative.asc --url http://www.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion/keys/derivative.asc

3. Users can check Whonix Signing Key for better security.

4. Done.

The procedure of adding the Whonix signing key is now complete.

Add Repository

Add the Whonix APT Repository.

Choose either: Option A, Option B OR Option C

Option A: Add Whonix Onion Repository.

To add Whonix Repository over Onion please install apt-transport-tor from the Debian repository.

sudo apt install apt-transport-tor

Add Whonix APT repository for default Whonix using Debian stable. At the time of writing this was bookworm.

echo "deb [signed-by=/usr/share/keyrings/derivative.asc] tor+http://deb.dds6qkxpwdeubwucdiaord2xgbbeyds25rbsgr73tbfpqpt4a6vjwsyd.onion bookworm main contrib non-free" | sudo tee /etc/apt/sources.list.d/derivative.list

Option B: Add Whonix Clearnet Repository over Tor.

To add Whonix Repository over torified clearnet install apt-transport-tor from the Debian repository.

sudo apt install apt-transport-tor

Add Whonix APT repository for default Whonix using Debian stable. At the time of writing this was bookworm.

echo "deb [signed-by=/usr/share/keyrings/derivative.asc] tor+https://deb.whonix.org bookworm main contrib non-free" | sudo tee /etc/apt/sources.list.d/derivative.list

Option C: Add Whonix Clearnet Repository over clearnet.

NOTE: When later using Whonix repository tool, then this will be upgraded to "Clearnet Rep. via Tor", unless see footnote. ^[8]

To add Whonix Repository over clearnet please add Whonix APT repository for default Whonix using Debian stable. At the time of writing this was bookworm.

echo "deb [signed-by=/usr/share/keyrings/derivative.asc] https://deb.whonix.org bookworm main contrib non-free" | sudo tee /etc/apt/sources.list.d/derivative.list

The procedure of adding the Whonix repository is now complete.

Install corridor.

Install package(s) corridor following these instructions

Platform specific notice.

Non-Qubes-Whonix: No special notice.
Qubes-Whonix: In Template.

Update the package lists and upgrade the system .

sudo apt update && sudo apt full-upgrade

Install the corridor package(s).

Using apt command line --no-install-recommends option is in most cases optional.

sudo apt install --no-install-recommends corridor

Platform specific notice.

Non-Qubes-Whonix: No special notice.
Qubes-Whonix: Shut down Template and restart App Qubes based on it as per Qubes Template Modification .

Done.

The procedure of installing package(s) corridor is complete.

Configuration[edit]

Optional: BridgeFirewall corridor Configuration[edit]

TODO: BridgeFirewall corridor configuration is currently untested.

"Bridges are less reliable and tend to have lower performance than other entry points. If you live in a uncensored area, they are not necessarily more secure than entry guards." ^[9]

In order to use corridor as a BridgeFirewall, configure Tor to use bridges before installing corridor. ^[10]

1. Start sys-corridor and open a terminal using Qubes start menu.
2. Create folder /etc/corridor.d and configuration file /etc/corridor.d/21-bridges-user.conf first. ^[11]
3. Create a bridges configuration file. Open file /etc/corridor.d/21-bridges-user.conf in an editor with root rights.

This box uses sudoedit for better security.

sudoedit /etc/corridor.d/21-bridges-user.conf

NOTES:

When using Qubes-Whonix, this needs to be done inside the Template.

sudoedit /etc/corridor.d/21-bridges-user.conf

After applying this change, shutdown the Template.
All App Qubes based on the Template need to be restarted if they were already running.
This is a general procedure required for Qubes and unspecific to Qubes-Whonix^™.

This is just an example. Other tools could achieve the same goal.
If this example does not work for you or if you are not using Whonix, please refer to this link.

sudoedit /etc/corridor.d/21-bridges-user.conf

4. Review Whonix-Gateway (sys-whonix) Tor bridge settings.

Depending on how Tor bridges are configured on Whonix-Gateway (sys-whonix):

if Anon Connection Wizard was used, see configuration file /usr/local/etc/torrc.d/40_tor_control_panel.conf.
if manual Tor bridge configuration was done, see file /usr/local/etc/torrc.d/50_user.conf.

5. Add the following text. ^[12]

Syntax is similar as Tor configuration as reviewed in previous step. Replace the IPs and ports 1.2.3.4:443, 2.3.4.5:443 with the actual IPs and ports of the bridges in use. All Tor bridges from Tor configuration on Whonix-Gateway (sys-whonix) need to be added below too.

BRIDGES="\ Bridge 1.2.3.4:443 Bridge 2.3.4.5:443 Bridge 3.4.5.6:443 "

Save.

6. Done.

BridgeFirewall corridor configuration is complete.

Daemon Status Test[edit]

While these instructions remain experimental, it is advised to run the following systemctl commands to check everything is functioning correctly.

sudo systemctl --no-pager --full status corridor-data sudo systemctl --no-pager --full status corridor-init-forwarding sudo systemctl --no-pager --full status corridor-init-logged sudo systemctl --no-pager --full status corridor-init-snat

Restart corridor[edit]

Reboot sys-corridor.

Do another Daemon Status Test.

Test corridor[edit]

Test Preparation[edit]

Run the above systemctl commands again.
Create or use an appropriate existing AppVM named corridor-client (or similar).
Install / run either system-tor (from Debian or Fedora package sources) or Tor Browser.
Set Networking of corridor-client to sys-corridor. Tor should be still able to connect.

Testing Steps[edit]

Run a Tor log analysis.

Then restart Tor.

sudo service tor restart

Check if Tor is still able to connect.

To test Tor Browser:

First check Tor Browser can make an initial connection to the Internet while Networking is still set to sys-firewall.
Next set Networking to sys-corridor and confirm it is still able to connect. If so, that is a positive sign.
Finally attempt an untorified connection by using an application like Chromium or Firefox browser. Untorified applications should fail to connect to the Internet.

Test Logging[edit]

Whenever corridor blocks attempted actions (like the tests above), a message will appear in syslog. To inspect /var/log/syslog

Open file /var/log/syslog in an editor with root rights.

This box uses sudoedit for better security.

sudoedit /var/log/syslog

NOTES:

When using Qubes-Whonix, this needs to be done inside the Template.

sudoedit /var/log/syslog

After applying this change, shutdown the Template.
All App Qubes based on the Template need to be restarted if they were already running.
This is a general procedure required for Qubes and unspecific to Qubes-Whonix^™.

This is just an example. Other tools could achieve the same goal.
If this example does not work for you or if you are not using Whonix, please refer to this link.

sudoedit /var/log/syslog

To check for blocks inside sys-corridor, run.

sudo tail -f /var/log/syslog

If corridor blocks anything, the output will be similar to this.

Jul 19 00:58:27 localhost kernel: [ 954.706833] corridor:

Interpreting the Results[edit]

The safest configuration is only setting sys-whonix to use sys-corridor for Networking. The reason is the qubes-update-check.service will try to use the Internet without Tor, and other programs may also try to use clearnet. Therefore, always shut down corridor-client.

Configure sys-whonix[edit]

To set Networking of sys-whonix to sys-corridor:

Qube Manager → left-click sys-whonix → right-click → Qube settings → Networking → sys-corridor → OK

The procedure is now complete.

Debugging[edit]

If problems are encountered, this section provides tips on gathering useful information for debugging.

It is also possible to ignore everything said on this website. Pretend it does not exist. Then acquire corridor from its original upstream and contact upstream for support.

Check if the corridor_relays ipset gets populated.

sudo ipset list corridor_relays

It is recommended to also install the usability-misc package from Whonix repository, since it provides the iptables-save-deterministic command. Alternatively, retrieve the package from elsewhere.

sudo apt install usability-misc

Run iptables-save-deterministic.

sudo iptables-save-deterministic

In Qubes, the output should be similar to the following.

*nat
:PREROUTING ACCEPT [0,0]
:INPUT ACCEPT [0,0]
:OUTPUT ACCEPT [0,0]
:POSTROUTING ACCEPT [0,0]
:CORRIDOR_SNAT - [0,0]
-A POSTROUTING -j CORRIDOR_SNAT
-A CORRIDOR_SNAT -s 10.137.0.0/16 ! -d 10.137.0.0/16 -j MASQUERADE
COMMIT
*filter
:INPUT ACCEPT [0,0]
:FORWARD ACCEPT [0,0]
:OUTPUT ACCEPT [0,0]
:CORRIDOR_FILTER - [0,0]
-A FORWARD -j CORRIDOR_FILTER
-A CORRIDOR_FILTER -m conntrack --ctstate RELATED,ESTABLISHED -j RETURN
-A CORRIDOR_FILTER -m set --match-set corridor_relays dst,dst -j RETURN
-A CORRIDOR_FILTER -m set --match-set corridor_logged src -j LOG --log-prefix "corridor: reject " --log-macdecode
-A CORRIDOR_FILTER -j REJECT --reject-with icmp-host-prohibited
COMMIT

Credits[edit]

The author of corridor is rustybird. Patrick Schleizer is the author of the corridor for Debian fork used in these Whonix instructions.

Footnotes[edit]

↑ Corridor for Whonix KVM ticket.
↑ Without third party contributions to corridor, Non-Qubes-Whonix is unlikely to be supported in the near future.
↑
extrepo vs manual:
- Usability:
  - There are some detail usability differences. Using onion connection might be easier with manual method until Whonix gets ported to Debian 13 / trixie because extrepo might get onion support then.
  - Apart from that, extrepo's usability seems generally better.
- Security:
  - A detailed comparative research of both methods is unavailable.
  - If usability is considered a security feature, then extrepo might be considered more secure. This is because users do not have to learn as much about Verifying Software Signatures, OpenPGP, its many Software Signature Verification Usability Issues. Debian which is already trusted by the user providing a trust path to the Whonix signing key. Manual key fingerprint verification not required.
  - The extrepo project is a huge amount of work adding all the signing keys for many different projects. The code for securely downloading a signing key in the Python is not among the most difficult programming tasks to get correct. Compared with curl (written in C), it might be more secure.
- Keeping support for manual method:
  - Removal of the manual method is not planned. Since already written, the maintenance effort for that very part of documentation is low. In case extrepo signing key is outdated, get deprecated, it's easy to switch back to manual method.
↑ stable-proposed-updates repository: sudo extrepo enable whonix_proposed testers repository: sudo extrepo enable whonix_testers developers repository: sudo extrepo enable whonix_developers
↑ extrepo feature request: extrepo apt-transport-tor and onion support
↑ forum discussion: extrepo - safely adding repos
↑ See Secure Downloads to understand why curl and the parameters --tlsv1.3 are used instead of wget.

Placing an additional signing key into folder /usr/share/keyrings by itself alone has no impact on security as this folder is not automatically used by Debian's APT by default. Only when an APT sources list configuration file points to folder /usr/share/keyrings using the signed-by keyword the signing key will be actually used. Therefore deleting keys in /usr/share/keyrings is optional if intending to disable an APT repository. See also APT Signing Key Folders.
↑ Unless using repository-dist --transport plain-tls. See also man repository-dist.
↑ bridge vs non-bridge users anonymity.
↑ The Whonix Bridges page can help, but the steps do not apply one-to-one.
↑ This skip is stepped if Tor entry guards are preferred.
↑ https://github.com/rustybird/corridor/issues/42

Whonix

The most watertight privacy operating system in the world.

Dark mode

Supported by Power Up Privacy

Whonix is proudly supported until 2025 by Power Up Privacy, a privacy advocacy group that seeks to supercharge privacy projects with resources so they can complete their mission of making our world a better place. (Strictly subject to our sponsorship policy.)

At Whonix we value freedom and trust, supporting Open Source and Freedom Software

By using this website, you acknowledge you have read, understood, and agree to be bound by these agreements: Terms of Service, Privacy Policy, Cookie Policy, E-Sign Consent, DMCA, Imprint

2012- 2024 ENCRYPTED SUPPORT LP

Your support makes
all the difference!

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!

[1] Corridor for Whonix KVM ticket.

[2] Without third party contributions to corridor, Non-Qubes-Whonix is unlikely to be supported in the near future.

[3] extrepo vs manual:
Usability:
There are some detail usability differences. Using onion connection might be easier with manual method until Whonix gets ported to Debian 13 / trixie because extrepo might get onion support then.

Apart from that, extrepo's usability seems generally better.

Security:
A detailed comparative research of both methods is unavailable.

If usability is considered a security feature, then extrepo might be considered more secure. This is because users do not have to learn as much about Verifying Software Signatures, OpenPGP, its many Software Signature Verification Usability Issues. Debian which is already trusted by the user providing a trust path to the Whonix signing key. Manual key fingerprint verification not required.

The extrepo project is a huge amount of work adding all the signing keys for many different projects. The code for securely downloading a signing key in the Python is not among the most difficult programming tasks to get correct. Compared with curl (written in C), it might be more secure.

Keeping support for manual method:
Removal of the manual method is not planned. Since already written, the maintenance effort for that very part of documentation is low. In case extrepo signing key is outdated, get deprecated, it's easy to switch back to manual method.

[4] Usability:
There are some detail usability differences. Using onion connection might be easier with manual method until Whonix gets ported to Debian 13 / trixie because extrepo might get onion support then.

Apart from that, extrepo's usability seems generally better.

[5] There are some detail usability differences. Using onion connection might be easier with manual method until Whonix gets ported to Debian 13 / trixie because extrepo might get onion support then.

[6] Apart from that, extrepo's usability seems generally better.

[7] Security:
A detailed comparative research of both methods is unavailable.

If usability is considered a security feature, then extrepo might be considered more secure. This is because users do not have to learn as much about Verifying Software Signatures, OpenPGP, its many Software Signature Verification Usability Issues. Debian which is already trusted by the user providing a trust path to the Whonix signing key. Manual key fingerprint verification not required.

The extrepo project is a huge amount of work adding all the signing keys for many different projects. The code for securely downloading a signing key in the Python is not among the most difficult programming tasks to get correct. Compared with curl (written in C), it might be more secure.

[8] A detailed comparative research of both methods is unavailable.

[9] If usability is considered a security feature, then extrepo might be considered more secure. This is because users do not have to learn as much about Verifying Software Signatures, OpenPGP, its many Software Signature Verification Usability Issues. Debian which is already trusted by the user providing a trust path to the Whonix signing key. Manual key fingerprint verification not required.

[10] The extrepo project is a huge amount of work adding all the signing keys for many different projects. The code for securely downloading a signing key in the Python is not among the most difficult programming tasks to get correct. Compared with curl (written in C), it might be more secure.

[11] Keeping support for manual method:
Removal of the manual method is not planned. Since already written, the maintenance effort for that very part of documentation is low. In case extrepo signing key is outdated, get deprecated, it's easy to switch back to manual method.

[12] Removal of the manual method is not planned. Since already written, the maintenance effort for that very part of documentation is low. In case extrepo signing key is outdated, get deprecated, it's easy to switch back to manual method.

[4] stable-proposed-updates repository: sudo extrepo enable whonix_proposed testers repository: sudo extrepo enable whonix_testers developers repository: sudo extrepo enable whonix_developers

[5] xtrepo feature request: extrepo apt-transport-tor and onion support

[6] rum discussion: extrepo - safely adding repos

[7] See Secure Downloads to understand why curl and the parameters --tlsv1.3 are used instead of wget.

Placing an additional signing key into folder /usr/share/keyrings by itself alone has no impact on security as this folder is not automatically used by Debian's APT by default. Only when an APT sources list configuration file points to folder /usr/share/keyrings using the signed-by keyword the signing key will be actually used. Therefore deleting keys in /usr/share/keyrings is optional if intending to disable an APT repository. See also APT Signing Key Folders.

[8] Unless using repository-dist --transport plain-tls. See also man repository-dist.

[9] ridge vs non-bridge users anonymity.

[10] The Whonix Bridges page can help, but the steps do not apply one-to-one.

[11] This skip is stepped if Tor entry guards are preferred.

[12] ttps://github.com/rustybird/corridor/issues/42

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

corridor - Tor traffic whitelisting gateway

Introduction[edit]

Connecting to corridor before Tor[edit]

Introduction[edit]

Warning[edit]

dom0 Setup[edit]

sys-corridor Setup[edit]

Install corridor[edit]

Using extrepo

A : Non-Qubes-Whonix™

B : Qubes-Whonix™ Template

Non-Qubes-Whonix™

Qubes-Whonix™

Others and Alternatives

Manually

A : Debian

B : Qubes

A : Onion Rep.

B : Clearnet Rep. via Tor

C : Clearnet Rep.

Configuration[edit]

Optional: BridgeFirewall corridor Configuration[edit]

Non-Qubes-Whonix™

Qubes-Whonix™

Others and Alternatives

Daemon Status Test[edit]

Restart corridor[edit]

Test corridor[edit]

Test Preparation[edit]

Testing Steps[edit]

Test Logging[edit]

Non-Qubes-Whonix™

Qubes-Whonix™

Others and Alternatives

Interpreting the Results[edit]

Configure sys-whonix[edit]

Debugging[edit]

Credits[edit]

Footnotes[edit]

Navigation menu

Search

A : Non-Qubes-Whonix^™

B : Qubes-Whonix^™ Template

Non-Qubes-Whonix^™

Qubes-Whonix^™

Non-Qubes-Whonix^™

Qubes-Whonix^™

Non-Qubes-Whonix^™

Qubes-Whonix^™