Jump to: navigation, search

Ledger Hardware Wallet

HowTo: Ledger Hardware Wallet with Qubes


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]

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.


Qubes USB Proxy Installation[edit]

Mandatory for Qubes users.

Update the package lists.

sudo apt-get update

Install Qubes USB Proxy. [8]

sudo apt-get install qubes-usb-proxy

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).

Update the package lists.

sudo apt-get update

Install Chromium.

sudo apt-get install chromium

electrum Installation[edit]

Optional. Only in case you want to install electrum.

Update the package lists.

sudo apt-get update

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

Currently does not work easily in Whonix 13 due to libudev-dev dependency issues. Meanwhile Debian stretch or later Whonix 14 should work.

Install libudev-dev and python3-pip.

sudo apt-get install libudev-dev python3-pip

Add Debian Stretch Backports to repositories sources lists.

sudo su -c "echo -e 'deb http://http.debian.net/debian stretch-backports main' > /etc/apt/sources.list.d/stretch-backports.list"

Install electrum from Debian Stretch Backports repository.

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



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 https://packages.debian.org/stretch/python-btchip

python-pip warning: TODO describe security impact

python3 -m pip install btchip-python

udev Rules[edit]

In Qubes TemplateVM.

Open a terminal (konsole). [12]

sudo adduser user plugdev

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

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

kdesudo kwrite /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. [13]

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 *.google.com, EXCLUDE *.googleusercontent.com, EXCLUDE *.gstatic.com", 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 *.google.com, EXCLUDE *.googleusercontent.com, EXCLUDE *.gstatic.com" https://chrome.google.com/webstore/detail/ledger-manager/beimhnaefocolcplfimocfiaiefpkgbf

Ledger Wallet Bitcoin


chromium --host-rules="MAP *, EXCLUDE *.google.com, EXCLUDE *.googleusercontent.com, EXCLUDE *.gstatic.com" https://chrome.google.com/webstore/detail/ledger-wallet-bitcoin/kkdpmhnladdopljabkgpacgpliggeeaf

Ledger Wallet Ethereum


chromium --host-rules="MAP *, EXCLUDE *.google.com, EXCLUDE *.googleusercontent.com, EXCLUDE *.gstatic.com" https://chrome.google.com/webstore/detail/ledger-wallet-ethereum/hmlhkialjkaldndjnlcdfdphcgeadkkm

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) -> Konsole

If you are using a graphical Whonix-Workstation, complete the following steps.

Start Menu -> Applications -> System -> Konsole


curl --tlsv1.2 --proto =https --location --remote-name https://apps.ledgerwallet.com/ripple/download/linux_deb_64.deb


Physically connect the ledger hardware wallet to a USB port.

Enter the PIN.

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. [14]

chromium --app-id=beimhnaefocolcplfimocfiaiefpkgbf

Ledger Wallet Bitcoin

Run. [14]

chromium --app-id=kkdpmhnladdopljabkgpacgpliggeeaf

Ledger Wallet Ethereum

Run. [14]

chromium --app-id=hmlhkialjkaldndjnlcdfdphcgeadkkm

Ledger Wallet Ripple


sudo dpkg -i linux_deb_64.deb


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 R3.2[edit]

Closing an Ledger app results in the USB device being disconnected from the Ledger VM. You have to re-attach it.

Sometimes the ledger manager app works consistently, but the ledger bitcoin app does not connect. In that case,

1) See overview of USB devices.


2) Remove USB device.

qvm-usb d sys-usb:4-3

3) Physically disconnect the Ledger Hardware Wallet.

4) Physically re-connect the Ledger Hardware Wallet.

5) Connect the Ledger Hardware Wallet to the Ledger VM.

qvm-usb a ledger sys-usb:4-3

6) Start Ledger App.

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. [16]

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.


  1. https://en.bitcoin.it/wiki/Hardware_wallet
  2. https://ledger.zendesk.com/hc/en-us/articles/115005198485-Hardware-wallets-FAQ
  3. https://en.bitcoin.it/wiki/Hardware_wallet
  4. The attacker generates psuedo-randomness that is indistinguishable from true randomness, but is still predictable.
  5. https://ledger.zendesk.com/hc/en-us/articles/115005198485-Hardware-wallets-FAQ
  6. https://en.wikipedia.org/wiki/WYSIWYS
  7. https://github.com/kvhnuke/etherwallet/issues/558#issuecomment-307307105
  8. https://github.com/QubesOS/qubes-issues/issues/2473#issuecomment-273634599
  9. https://ledger.groovehq.com/knowledge_base/topics/how-to-setup-electrum-nano-slash-nano-s
  10. Was not required. ln -s /lib/x86_64-linux-gnu/libudev.so.1 /lib/x86_64-linux-gnu/libudev.so
  11. https://github.com/spesmilo/electrum/issues/3422#issuecomment-348063118
  12. Further research is required to confirm this step is required.
  13. https://ledger.groovehq.com/knowledge_base/topics/ledger-wallet-is-not-recognized-on-linux
  14. 14.0 14.1 14.2 Using --host-rules="MAP *, EXCLUDE" won't work.
  15. btchip.btchipException.BTChipException: Exception : Invalid status 6d00 https://github.com/spesmilo/electrum/issues/1987 https://github.com/spesmilo/electrum/commit/4a5bece492876ff6a1cef1102db5572c8065a655#diff-0c426f356aa8b9f429e69bf86ebc422eR153 This bug is in the Debian stretch version of electrum and only fixed in a later version.
  16. USB devices shown multiple times in devices popup menu #3266

Random News:

Want to get involved with Whonix? Check out our Contribute page.

https | (forcing) onion

Share: Twitter | Facebook

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation.

Whonix is a licensee of the Open Invention Network. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Libre Software license as Whonix itself. (Why?)