HowTo: Ledger Hardware Wallet with Qubes

From Whonix

Info Qubes-Whonix ™ testers only!


Ledger wallets are a special type of commercial bitcoin wallet whereby a user's private keys are stored in a secure hardware device. Other commercial alternatives include Pi Wallet, TREZOR, BWALLET, KeepKey, Opendime, CoolWallet and others.

The major advantages of hardware wallets over software wallets include: [1]

  • Usually private keys are stored in a protected area of a microcontroller, and cannot be transferred out of the device in plaintext.
  • Resistance to computer viruses that target theft from software wallets.
  • More secure and interactive than paper wallets that require importation to software.
  • Usually software on the device is open source.

The main principle is that cryptographic secrets (private keys) are fully isolated from easy-to-hack computers or smartphones. Ledger wallets use secure chips that are similar to the technology used in chip and PIN payment cards or SIM cards. [2]

Security Risks[edit]

Ambox warning pn.svg.png Warning: Hardware wallets are not bulletproof. The user must be sure to purchase a good-quality, authentic device manufactured by a trustworthy and technically competent company with a good reputation in security.

Potential risks of hardware wallets include: [3]

  • Malware swapping recipient Bitcoin addresses. Malware on a PC could potentially trick the user into sending Bitcoin to the wrong address. Multi-factor confirmation of a recipient's Bitcoin address mitigates this risk.
  • Insecure RNG (Random Number Generator). Security is reliant on true randomness being generated by the source of entropy for the RNG, since it generates the wallet's private keys. This is hard to verify, and attackers may be able to recreate wallet keys if the RNG is insecure. [4]
  • Imperfect implementation. If bugs are present in the software, firmware or hardware, then attackers may be able to gain unauthorized access to the hardware wallet.
  • Compromised production process. Hardware backdoors could be introduced via intentional or unintentional actions that leaves security holes in the final product.
  • Device interdiction. No hardware wallet solution can deal with the threat of government programs that intercept hardware and modify them in transit to introduce backdoors.

Despite these risks, hardware wallets are considered a higher security solution than software wallets, since the latter must make private keys available in plain text in the computer's memory when transactions are signed - any compromise by Bitcoin-targeting malware would enable theft of Bitcoins. [5]

Seed Backup Security[edit]

Definitively good to have at least two ledger hardware wallets. During initial setup, the ledger does not verify all words of the seed. It only verifies 2 words of the 24 words seed. Meaning, when mistyping one word, one will later have trouble regaining access to ones coins. Two ledgers using the same seed should be generating the same addresses, which would proof, that one made a correct backup of the seed.

There is a seed testing app, but by a third party, which adds complications and therefore is probably best avoided.

Alternatively, one could note some generated addresses, reset its ledger, re-setup with the seed and see if it still uses the same addresses.

Wallet Testing Security[edit]

Before storing any non-petty cash in a wallet, it is a good idea to send there only a small amount and then trying to send it back. This is because software bugs could lead to showing an address where one does not own its corresponding private key.

Such an incident where someone lost money because of such a software bug already happened with a different wallet, see the following user story (w).

Threat Model[edit]

The term account number will be used rather than address to avoid confusion in the following writeup.

Hardware wallets seek to secure the funds of users under the sane assumption, that the computer that the user is using may be compromised, i.e. infected by Malware. Once infected by malware, the malware can see everything the user can see without the user noticing, manipulate the user's screen (showing one account number while it should show another account number), see all key strokes (sniff passwords), download files and other things.

Therefore the computer display is considered untrusted. The display of the hardware device is considered trusted. This is because only the vendor enforce that only software signed by the hardware vendor can be used. Therefore unless these cryptographic verification process can be subverted, the hardware wallet is considered to be free of malware and therefore a secure display. This security concept is called in other areas What You See Is What You Sign (WYSIWYS [6]) or just sign what you see.

The user wants to do things in a secure way. Secure meaning here, that the user does not want to loose crypto currency to attackers.

Once funds are on the devices they are safe, but getting the funds safely onto the device is not easy under this threat model.

recipient account number discovery risk

  • Threat: It is difficult to view one's recipient account number on the hardware wallet's secure display.
    • The Ledger Wallet Bitcoin has a "show address on device" ("show account number") button, which shows the account number on the secure hardware wallet display.
    • The Ledger Wallet Ethereum and other wallets had no such function at the time of writing.
    • myetherwallet has a show account number on device feature.
      • But myetherwallet is browser based and should therefore be avoided (even when running locally).
      • The online version of myetherwallet should obviously be avoided at all cost since the myetherwallet server is a supreme target for hackers.
      • Usage of myetherwallet locally in conjunction with ledger hardware wallet is very difficult due to browser issues. [7]
    • In some devices, even if the account number is shown, it is difficult to read from the display.
      • The ledger nano s has only a small display, the account number, which can be 35 - 45 random characters long, is displayed as ticker text, automatically scrolling over the display in a high speed. This leads to users at best only viewing the first few and last few characters skipping those in the middle. This gives the attacker the opportunity to try to create an address where the start and end of the address matches, however the middle part is under the control of the attacker.
      • The ledger nano blue does not have the above problem and shows the full account number at once giving the user a proper chance to verify it in full.
  • Conclusion: The regular user of the ledger hardware wallet will have a hard time figuring out its own recipient account number in a secure manner not fraudulently modified by malware running on its computer. Therefore the user will have a hard time, telling senders its correct own recipient account number and not being scammed by Malware potentially running on its computer.
  • Workaround: Using multiple computers (that are hopefully not all compromised) to find out one's account number.

receiving account number transmission risk

  • Threat: When receiving coins (such as withdrawing crypto currency from crypto currency exchange) the user's recipient account number is entered into the user's computer shown only on the insecure display.
  • Conclusion: It could be modified by malware to fraudulently redirected the withdraw to an account number hold in a wallet owned by the attacker.
  • Workarounds:
    • Using withdraw account number whitelists if offered by the sender.
    • This issue does not apply when the user can transmit the recipient account number through a trusted channel.

account balance discovery risk

  • Threat: Even if crypto currency has been received on the device, the balance is not shown on the hardware wallet secure display.
  • Conclusion: The user might believe to have received more value than the user did actually receive.
  • Workaround: Using multiple computers (that are hopefully not all compromised) check the balance (watch-only accounts).

recipient account number transmission risk

  • Threat: When sending crypto currency (to merchants or crypto currency exchanges), the recipient account number is shown on the computer's insecure display. It could be modified by malware to redirect the receiving account number to the attacker. Since the hardware wallet secure display will ask for confirmation (account number and amount), at least smaller transactions are protected. For example if the user has 1 Bitcoin but only wants to send 0.1 Bitcoin, the user has a chance to abort the transaction if the ledger display asks to confirm a transaction of more than expected.
  • Workarounds:
    • This issue does not apply when the user can verify the recipient account number through a trusted channel. (Such as a personal meetup with the sender trusts receiver not to attempt to be fraudulent or by using multiple devices which are unlikely to be all compromised.)
    • Sending funds in small installments and asking the recipient through a trusted channel if funds have been received. This limits the amount of funds that may be lost to the size of the installment.

time of compromise matters

  • Once funds are on the hardware wallet these are safe until the user attempts to spent them.
  • So when the user's computer gets compromised later after stocking up funds, the user looses less but is then affected by the above risks.

physical security

  • When the hardware wallet and/or computer gets stolen, all funds are safe. (Under the assumption that the attacker is unable to circumvent the hardware wallet PIN entry and/or to otherwise extract the keys from the device.)
  • If the user stored its hardware wallet and PIN in the same place and loose it, all funds will be lost.
  • If the mnemonic phrase gets lost, all funds will be lost.
  • Easier to keep private keys secured than computer full disk encryption. (Protections by hardware wallet secure element are not necessarily stronger than computer full disk encryption such as linux with luks.)


  • easier to safely spit bitcoin / bitcoin cash / bitcoin gold
  • easy to carry: yes
  • easy to backup: yes
  • easy to replace device: yes
  • easier than Qubes OS (offline vault VM): yes

usability issues

  • browser support on/off
  • ledger device apps do not auto start


  • more obscure to attack than "simple trojan horse": yes

impracticality of workarounds risk

  • Threat: A workaround is not a fix, but only a workaround. Such workarounds need awareness, which there probably is very little, so very few people are applying these, are cumbersome (bad usability) and therefore likely to be neglected during phases of limited concentration or time pressure.


Info If using the Nano S, Nano or HW1 ledger hardware wallets, a USB port is required.

Info Comes with some technical challenges. Try first if you can pass a USB device to an AppVM which is easier to use in combination with Qubes to learn how to do that and to iron out eventual Qubes USBVM issues.

Qubes USB Proxy Installation[edit]

Mandatory for Qubes users.

Install Qubes USB Proxy. [8]

Update the package lists.

sudo apt-get update

Upgrade the system.

sudo apt-get dist-upgrade

Install the qubes-usb-proxy package.

sudo apt-get install qubes-usb-proxy

The procedure is complete.

Chromium Installation[edit]

Chromium is required to use the run the Chrome applications ledger bitcoin and ledger ethereum. No additional software installation or account creation is needed.

In Qubes TemplateVM.

Open a terminal (konsole).

Install Chromium.

Update the package lists.

sudo apt-get update

Upgrade the system.

sudo apt-get dist-upgrade

Install the chromium package.

sudo apt-get install chromium

The procedure is complete.

electrum Installation[edit]

Optional. Only in case you want to install electrum.

Install electrum and dependencies for electrum ledger hardware wallet support. [9]

Install libudev-dev and python3-pip.

Update the package lists.

sudo apt-get update

Upgrade the system.

sudo apt-get dist-upgrade

Install the libudev-dev python3-pip package.

sudo apt-get install libudev-dev python3-pip

The procedure is complete.

Install electrum from Debian Backports repository.

Package libusb-1.0-0-dev python-btchip electrum libusb-1.0-0-dev python-btchip can be installed from Debian backports. This is non-ideal, see footnote. [10]

1. Boot Whonix-Workstation ™ (whonix-ws-15) TemplateVM.

2. Add the current Debian stable backports codename buster-backports to Debian apt sources.

Note: this applies to Whonix Later Whonix versions may use a codename different to buster.

In Whonix-Workstation ™ (whonix-ws-15) TemplateVM, run.

sudo su -c "echo -e 'deb buster-backports main contrib non-free' > /etc/apt/sources.list.d/backports.list"

Alternatively, users who like Onionizing Repositories can set the .onion mirror.

sudo su -c "echo -e 'deb tor+http://vwakviie2ienjx6t.onion/debian buster-backports main contrib non-free' > /etc/apt/sources.list.d/backports.list"

3. Update the package lists.

sudo apt-get update

4. Install the select software.

sudo apt-get -t buster-backports install electrum libusb-1.0-0-dev python-btchip

The procedure is now complete.

5. Undo.

On occasion it is necessary to undo this configuration, for example when upgrading from Debian buster to bullseye. [11] To proceed, run.

sudo rm /etc/apt/sources.list.d/backports.list



Install python3-btchip. Unfortunately it is not available from Debian's repository. Therefore we have to install it using python-pip.

TODO: bug report against

python-pip warning: See Avoid Third Party Package Managers!

python3 -m pip install btchip-python

udev Rules[edit]

In Qubes TemplateVM.

Open a terminal (konsole). [14]

sudo adduser user plugdev

Open /etc/udev/rules.d/20-hw1.rules in an editor with root rights.

This box uses lxsu for root privilege escalation and mousepad as editor. These are examples. Other tools could archive the same goal too. If these example tools do not work for you or if you are not using Whonix, please press on Expand on the right side.

The easiest would be to install these example tools lxsu mousepad so you can keep copying and pasting these instructions.

Update the package lists.

sudo apt-get update

Upgrade the system.

sudo apt-get dist-upgrade

Install the --no-install-recommends lxsu mousepad package.

sudo apt-get install --no-install-recommends lxsu mousepad

The procedure is complete.

Alternatively you could also use other tools which may already be installed by default.

gksudo gedit /etc/udev/rules.d/20-hw1.rules

sudoedit /etc/udev/rules.d/20-hw1.rules

If you are using a graphical Whonix or Qubes-Whonix ™ with XFCE, run.

lxsu mousepad /etc/udev/rules.d/20-hw1.rules

If you are using a terminal-only Whonix, run.

sudo nano /etc/udev/rules.d/20-hw1.rules

Add. [15]

SUBSYSTEMS=="usb", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="1b7c", MODE="0660", OWNER="user", GROUP="plugdev"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="2b7c", MODE="0660", OWNER="user", GROUP="plugdev"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="3b7c", MODE="0660", OWNER="user", GROUP="plugdev"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="4b7c", MODE="0660", OWNER="user", GROUP="plugdev"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="1807", MODE="0660", OWNER="user", GROUP="plugdev"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="1808", MODE="0660", OWNER="user", GROUP="plugdev"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0000", MODE="0660", OWNER="user", GROUP="plugdev"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0001", MODE="0660", OWNER="user", GROUP="plugdev"

KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0660", OWNER="user", GROUP="plugdev", ATTRS{idVendor}=="2c97"
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0660", OWNER="user", GROUP="plugdev", ATTRS{idVendor}=="2581"


Shut down Qubes TemplateVM.

Start the VM which is supposed to interact with the ledger hardware wallet, which we will call ledger VM.

Ledger App Installation[edit]

For graphical user interface instructions, which are easier but less secure, click on expand on the right.

For graphical user interface instructions, which are easier but less secure, click on expand on the right.


These instructions are more secure, because we are using --host-rules="MAP *, EXCLUDE *, EXCLUDE *, EXCLUDE *", which results in only connections to Google (i.e. the Chrome Web Store) are allowed. Any other (accidental) connections to other destinations which could be harmful for privacy or security are prevented.

Ledger Manager


chromium --host-rules="MAP *, EXCLUDE *, EXCLUDE *, EXCLUDE *"

Ledger Wallet Bitcoin


chromium --host-rules="MAP *, EXCLUDE *, EXCLUDE *, EXCLUDE *"

Ledger Wallet Ethereum


chromium --host-rules="MAP *, EXCLUDE *, EXCLUDE *, EXCLUDE *"

Ledger Wallet Ripple

Open a terminal.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q")Whonix-Workstation ™ AppVM (commonly named anon-whonix)Xfce Terminal

If you are using a graphical Whonix with XFCE, run.

Start MenuXfce Terminal


curl --tlsv1.2 --proto =https --location --remote-name


Physically connect the ledger hardware wallet to a USB port.

Enter the PIN.

Info Qubes won't detect ledger before the PIN has been entered. Guess: ledger does not announce itself before that.

Start your ledger VM.

Ledger Apps[edit]

Using Graphical user Interface

For graphical user interface instructions, which are easier but less secure, click on expand on the right.

Ledger Manger / Ledger Wallet Bitcoin / Ledger Wallet Ethereum

Start chromium.

Click apps.

Choose a ledger app and start it.

You can also refer to the instructions on the ledger hardware wallet website.

Ledger Wallet Ripple

Undocumented. Please refer to command line instructions below or to instructions on the ledger hardware wallet homepage.

Using Command Line

For command line instructions, which have worse usability but are more secure, click on expand on the right.


These instructions are more secure, because we are using chromium command line switch --app-id=app-id, which results in only starting the ledger app, so we limit outgoing connections to a minimum.

Ledger Manager

Run. [16]

chromium --app-id=beimhnaefocolcplfimocfiaiefpkgbf

Ledger Wallet Bitcoin

Run. [16]

chromium --app-id=kkdpmhnladdopljabkgpacgpliggeeaf

Ledger Wallet Ethereum

Run. [16]

chromium --app-id=hmlhkialjkaldndjnlcdfdphcgeadkkm

Ledger Wallet Ripple


sudo dpkg -i linux_deb_64.deb


Info INFO: electrum crash bug in Debian stretch / Whonix ™ 13 / 14 when trying to use a hardware wallet: Ledger Bitcoin App must be opened on the Ledger Hardware Wallet, otherwise electrum will crash. [17]

An electrum wallet will only show legacy bitcoin addresses and their balances or segwit bitcoin addresses and their balances. Not both. You can have multiple electrum wallets and switch between them, though.

Electrum will ask for derivation path.

  • The default is m/44'/0'/0' for legacy bitcoin addresses.
  • You should use m/49'/0'/0' for segwit bitcoin addresses.


Qubes R4[edit]

Qubes R4 USB widget has some (maybe yet to be reported) bugs such as showing that USB device is connected to a VM while qvm-usb (the command line authority who's judgment should be trusted more) disagrees or showing the same USB device more than once in the menu. [18]

Physically connect the ledger hardware wallet to a USB port.

Run the following command to get an overview of USB devices detected by Qubes.


Should show something like this.

sys-usb:2-1.1  Logitech_USB_Keyboard     
sys-usb:2-1.2  PixArt_USB_Optical_Mouse  
sys-usb:2-1.4  Ledger_Nano_S_0001        

Use the following command to connect the ledger hardware wallet to a VM of your choice. Replace ledger-debian-stretch with the actual name of your VM.

qvm-usb attach ledger-debian-stretch sys-usb:2-1.4


The USB device might be passed to the ledger VM, but ledger apps might not recognize the ledger hardware wallet. In that case, in BIOS settings...

  • try to disable Legacy USB Support
  • try to disable XHCI Pre-Boot Mode
  • try flipping other USB related BIOS options

No re-installation of Qubes required.


Try to connect to Ledger Manager first.

Try to update the firmware of the Ledger hardware wallet by connecting it to a non-Qubes Linux computer where connections are possibly using Ledger Manager.

See also Dev/Ledger Hardware Wallet.


After having installed ledger set up, please consider making a donation to Whonix ™ to keep it running for the years to come.

Donate Bitcoin (BTC) to Whonix ™.



  4. The attacker generates psuedo-randomness that is indistinguishable from true randomness, but is still predictable.
  10. Users should Prefer Packages from Debian Stable Repository, but using backports is better than manual software installation or using third party package managers since this prefers APT. To contain the risk, Non-Qubes-Whonix ™ users might want to consider using Multiple Whonix-Workstation ™ and Qubes-Whonix ™ users might want to consider using Multiple Qubes-Whonix ™ TemplateVMs or Software Installation in a TemplateBasedVM.
  11. Most often this step applies before attempting major Whonix upgrades; upgrade instructions are also made available at that time (see Stay Tuned).
  12. Was not required. ln -s /lib/x86_64-linux-gnu/ /lib/x86_64-linux-gnu/
  14. Further research is required to confirm this step is required.
  16. 16.0 16.1 16.2 Using --host-rules="MAP *, EXCLUDE" won't work.
  17. btchip.btchipException.BTChipException: Exception : Invalid status 6d00 This bug is in the Debian stretch version of electrum and only fixed in a later version.
  18. USB devices shown multiple times in devices popup menu #3266

No comments for now due to spam. Use Whonix forums instead.

Random News:

Are you proficient with iptables? Want to contribute? Check out possible improvements to iptables. Please come and introduce yourself in the development forum.

https | (forcing) onion

Follow: Twitter | Facebook | | Stay Tuned | Whonix News

Share: Twitter | Facebook

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation.

Copyright (C) 2012 - 2019 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

Whonix ™ is a derivative of and not affiliated with Debian. Debian is a registered trademark owned by Software in the Public Interest, Inc.

Whonix ™ is produced independently from the Tor® anonymity software and carries no guarantee from The Tor Project about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint.