Actions

HowTo: Ledger Hardware Wallet with Qubes

From Whonix


Info Qubes-Whonix ™ testers only!

Introduction[edit]

Ledger wallets [archive] 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 [archive], 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 [archive] (w [archive]).

Threat Model[edit]

See Hardware Wallet Security.

Installation[edit]

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


This comes with some technical challenges. First attempt to 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. [6]

1. Update the package lists.

sudo apt-get update

2. Upgrade the system.

sudo apt-get dist-upgrade

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

1. Update the package lists.

sudo apt-get update

2. Upgrade the system.

sudo apt-get dist-upgrade

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

Install libudev-dev and python3-pip.

1. Update the package lists.

sudo apt-get update

2. Upgrade the system.

sudo apt-get dist-upgrade

3. 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 [archive] can be installed from Debian backports. This is non-ideal, see footnote. [8]

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 15.0.0.4.9. Later Whonix versions may use a codename different to buster.

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

sudo su -c "echo -e 'deb https://deb.debian.org/debian 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. [9] To proceed, run.

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

[10]

[11]

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 [archive]

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). [12]

sudo adduser user plugdev

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

(Qubes-Whonix ™: In TemplateVM)

This box uses sudoedit for better security [archive]. This is an example and other tools could also 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/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"

Save.

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.

Security

These instructions are more secure, because we are using --host-rules="MAP * 127.0.0.1, 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

Run.

chromium --host-rules="MAP * 127.0.0.1, EXCLUDE *.google.com, EXCLUDE *.googleusercontent.com, EXCLUDE *.gstatic.com" https://chrome.google.com/webstore/detail/ledger-manager/beimhnaefocolcplfimocfiaiefpkgbf

Ledger Wallet Bitcoin

Run.

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

Ledger Wallet Ethereum

Run.

chromium --host-rules="MAP * 127.0.0.1, 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)Xfce Terminal

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

Start MenuXfce Terminal

Run.

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

Usage[edit]

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.

https://www.ledgerwallet.com/apps [archive]

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.

Security

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

Run.

sudo dpkg -i linux_deb_64.deb

electrum[edit]

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

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.

Troubleshooting[edit]

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.

qvm-usb

Should show something like this.

BACKEND:DEVID  DESCRIPTION               USED BY
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

BIOS[edit]

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.

Ledger[edit]

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.

Donations[edit]

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

3CQ2BiFyzfXLv3JYhaBBr8hvLrfpdwZ56f

Footnotes[edit]

  1. https://en.bitcoin.it/wiki/Hardware_wallet [archive]
  2. https://ledger.zendesk.com/hc/en-us/articles/115005198485-Hardware-wallets-FAQ [archive]
  3. https://en.bitcoin.it/wiki/Hardware_wallet [archive]
  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 [archive]
  6. https://github.com/QubesOS/qubes-issues/issues/2473#issuecomment-273634599 [archive]
  7. https://ledger.groovehq.com/knowledge_base/topics/how-to-setup-electrum-nano-slash-nano-s [archive]
  8. 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.
  9. Most often this step applies before attempting major Whonix upgrades; upgrade instructions are also made available at that time (see Stay Tuned).
  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 [archive]
  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 [archive]
  14. 14.0 14.1 14.2 Using --host-rules="MAP * 127.0.0.1, EXCLUDE 127.0.0.1" won't work.
  15. btchip.btchipException.BTChipException: Exception : Invalid status 6d00 https://github.com/spesmilo/electrum/issues/1987 [archive] https://github.com/spesmilo/electrum/commit/4a5bece492876ff6a1cef1102db5572c8065a655#diff-0c426f356aa8b9f429e69bf86ebc422eR153 [archive] 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 [archive]


Want to get involved with Whonix ™? Check out our Contribute [archive] page.

https [archive] | (forcing) onion [archive]
Follow: Twitter.png Facebook.png 1280px-Gab text logo.svg.png Rss.png 1024px-Telegram 2019 Logo.svg.png Discourse logo.svg

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png

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 [archive] of the Open Invention Network [archive]. 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 [archive]. Debian is a registered trademark [archive] owned by Software in the Public Interest, Inc [archive].

Whonix ™ is produced independently from the Tor® [archive] anonymity software and carries no guarantee from The Tor Project [archive] 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.

Monero donate whonix.png