Ultimate Guide on Using Trezor on Qubes

Written by Ursidae: https://ursidaecyber.com

This guide explains how to use Trezor cryptocurrency hardware wallets on Qubes OS. Unfortunately installing Trezor Suite is not as straight forward as installing other software on Qubes is, so we compiled an exhaustive and ultimate guide on the process.

This guide contains two parts: brief instructions and in-depth instructions. Use whichever is suited to your needs. These are the brief instructions. If you require detailed instructions please see my Github.

Step 1: Install Trezor Suite

  1. Install the Trezor Suite .AppImage from the Trezor website along with the signature and signing key in a new Whonix AppVM dedicated to Trezor.

  2. Verify the download.

  3. Execute code:

sudo chmod u+x /Downloads/Trezor-Suite-23.4.2-linux-x86_64.AppImage
  1. Right click on the .AppImage file and press execute to open the application.

Step 2: Port Listening

In Trezor Whonix AppVM:

  1. Execute command:
sudo nano /rw/config/rc.local
  1. Add the following code to the file:
socat TCP-LISTEN:21325,fork EXEC:"qrexec-client-vm sys-usb trezord-service" &
  1. Save and exit.

Step 3: Dom0 Trezor Policy

In Dom0:

  1. Execute:
sudo nano /etc/qubes-rpc/policy/trezord-service 
  1. Add this code to the new file:
$anyvm $anyvm allow,user=trezord,target=sys-usb 
  1. Save and exit.

Step 4: Fedora Cloning

  1. Clone your current regular fedora-37 template Qube and name it fedora-37-sys.

  2. Clone the fedora-37-dvm Qube and name it fedora-37-sys-dvm.

  3. Set the template for the fedora-37-sys-dvm as fedora-37-sys.

  4. Set sys-usb’s template as fedora-37-sys-dvm.

Step 5: Trezord Service

In fedora-37-sys-dvm:

  1. Execute in terminal:
sudo mkdir /usr/local/etc/qubes-rpc
  1. Execute:
sudo nano /usr/local/etc/qubes-rpc/trezord-service
  1. Add this code to the file:
socat - TCP:localhost:21325 
  1. Save and exit.

  2. Execute:

sudo chmod +x /usr/local/etc/qubes-rpc/trezord-service

Step 6: Trezor Bridge

In fedora-37-sys:

Download the Trezor Bridge .rpm file from Trezor.

  1. Execute:
sudo chmod u+x /Downloads/trezor-bridge-2.0.27-1.x86_64.rpm
  1. Then execute:
sudo rpm -i /Downloads/trezor-bridge-2.0.27-1.x86_64.rpm

Step 7: Udev rules

Note on Udev rpm use: Using the Trezor-provided Udev rpm file does not work for Qubes. See in-depth explanation section below. Use the provided Method 1 or 2 here. Use method 1 if comforable with enabling networking in template and method 2 if not.

Method 1: Manual Build

In fedora-37-sys:

  1. Run:
sudo nano /etc/udev/rules.d/51-trezor.rules

Copy and paste this code into the file:

# Trezor

SUBSYSTEM=="usb", ATTR{idVendor}=="534c", ATTR{idProduct}=="0001", MODE="0660", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl", SYMLINK+="trezor%n"

KERNEL=="hidraw*", ATTRS{idVendor}=="534c", ATTRS{idProduct}=="0001", MODE="0660", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl"

# Trezor v2

SUBSYSTEM=="usb", ATTR{idVendor}=="1209", ATTR{idProduct}=="53c0", MODE="0660", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl", SYMLINK+="trezor%n"

SUBSYSTEM=="usb", ATTR{idVendor}=="1209", ATTR{idProduct}=="53c1", MODE="0660", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl", SYMLINK+="trezor%n"

KERNEL=="hidraw*", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="53c1", MODE="0660", GROUP="plugdev", TAG+="uaccess", TAG+="udev-acl"
  1. Save and exit.

  2. Execute:

sudo chmod +x /etc/udev/rules.d/51-trezor.rules

OR

Method 2: Curl Installation

  1. In fedora-37-sys enable networking.

  2. Install curl:

sudo dnf install curl
  1. Download Udev rules:
sudo curl https://data.trezor.io/udev/51-trezor.rules -o /etc/udev/rules.d/51-trezor.rules
  1. Allow execution:
sudo chmod +x /etc/udev/rules.d/51-trezor.rules
  1. Revoke fedora-37-sys networking permissions.

Step 8: Install Trezor Dependencies

In the Trezor Whonix AppVM:

  1. Install pip:
sudo apt install pip
  1. Execute:
pip3 install --user trezor

AND

In fedora-37-sys:

  1. Allow networking.

  2. Execute:

sudo dnf install trezor-common
  1. Revoke networking permissions in fedora-37-sys.
2 Likes

I followed these instructions to the letter but in step 8 I get an error running “pip3 install -user trezor”. It said -u is not a valid option. I think you were looking for a directory “usr” maybe. But the error I get from Trezor-Suite is “Trezor Bridge” not running. In the USB device list I see Satoshi Labs and I tried to connect it to my Whonix AppVM. Then the error changes to say “Connect your Trezor”. Any thoughts?

Great tutorial though. I learned a lot about Qubes OS by following it.

P.S. I downloaded the Trezor Bridge .rpm file in my personal Qube and then copied the file over to fedora-37-sys. But it seemed to install fine.

P.P.S I am using a Trezor Model T

Would it be recommended to make the Trezor AppVM use Whonix WS or GW for the template?

With the disclaimer that I have no idea about what the guide is about or whether it is any good, the command-line options that are composed of multiple letters (like --user) are often identified by a double hyphen.

Not all tools follow that convention, but pip does. So you’re looking after --user instead of -user, the corresponding documentation is here:

https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-user

The error message complains about -u not being a valid option. In case you wonder why -u and not -user, that’s related to the convention I mention above.

Single letter options can often be “stacked” for convenience (e.g. the following ls commands are equivalent: ls -a -l -h, ls -alh).

If you allow that, there must be a way to tell whether -option is a single option called option or the o, p, t, etc options used together. One way to do that is to establish a convention: single hyphen, single letter options, double hyphen, multi-letter options (and those cannot be stacked).

It turns out that pip install accepts --user as an option, but not the shorthand -u, so that’s where the command you wrote stops making sense to pip.

Thank you, thank you. I thought the longer dash meant something. There is another line in guide that looks like a longer dash: socat - TCP:localhost:21325

could that be a double dash as well?

Not super on topic, but…

Longer dashes may sometimes be the product of the forum’s text formatiing tool. It does convert -- into for convenience and ease of typing.

The tool assumes folks know to mark code as preformatted text using backticks. (Bold assumption…) I’m pretty sure that’s explained in the new user tutorial, but couldn’t find a direct link.

Example: without backticks, 2023--2024 renders as:

2023–2024 which is the right/better way to format a range of dates, assuming that’s your intention!

1 Like

Whonix-gw is the gateway start TOR to communicate with Whonix-ws which is the work station that runs the browser so you can browse anomalously using TOR. So you want to run Tresor-Suite on whonix-ws. Bit I still haven’t got it to talk to the Trezor device yet.

I GOT IT WORKING !!! - I had a few typos in my file but now I’m good. Thanks

1 Like

Yep. This is correct. The text erroneously formatted two dashes (“–”) as an emdash and this is what caused the previous user’s errors. I have fixed this on the post in all places it appears.

1 Like

This was most likely an error. It’s been a while since we wrote this guide but the dash in socat - TCP:localhost:21325 is a single dash, not two. You recently reported that you succeeded in using this method. Did you use a single or double dash here? It is most likely single that is correct.

Step 8 requires --user (two dashes) not one. Make sure to not connect the Trezor USB device to any Qubes. Step 2 and 3 make it so all your Qubes can detect the Trezor. All you need to do is plug it in.

Make the Trezor AppVM using a WhonixWS template. I recommend cloning your standard WhonixWS template to create a WhonixWS template which you will use only for Trezor to avoid unwanted code elsewhere.

I don’t know how wrong I could be, I have tried & retried every single step to the tee, yet all I am left with is an appimage that runs saying either: ‘Trezor Bridge is not running’ or ‘connect your trezor’, my device is definitely attached and I installed the bridge rpm file on the fedora-37-sys, It’s either one or the other.

Make sure to not connect the Trezor (using sys-usb) to any particular Qube. All your running AppVMs are able to detect it as soon as its plugged in, without further action. Let me know if your issue persists and I’ll try to help out.

I can’t get this to work, it either says connect your Trezor or that the bridge is not running. If I go back to the fedora-37-sys which has the bridge after installing the package and restarting qube vm, I can never make the bridge application pop up again.

The trezor device does get recognized by Qubes but that’s about it.

Hello,

As with some of the other responders in this thread, my Trezor Suite displayed a “Bridge Not Running” message after completing the guide. Upon closer inspection, I found that the code in Step 2 (Port Listening) contained non-standard quotation marks. Upon replacing these quotation marks, everything began to work as normal.

2 Likes

Glad to hear everything worked out for you. Can you elaborate what you mean by non-standard quotation marks? What did you change to make this work?

Hi,

I see you have since edited the thread to replace the quotation marks with the proper ones. Originally it was a similar character that looked like a quote but on closer inspection was a bit slanted and not treated like a quote. I have encountered them before, I think certain text editing softwares use them and cause them to be pasted if you copy from them but I am not sure. It would make sense as to why some people would have issues and some didn’t because if you were to manually type out the text instead of pasting it, it would work.

Ex.
" vs ” … very hard to spot

2 Likes

That’s right. Got it figured out. Thanks for pointing it out.