Actions

How-to: Ledger Hardware Wallet in Whonix ™

From Whonix



Ledger Nano S - Hard Wallet - Cold Storage for Cryptocurrency 04.jpg
Ledger Hardware Wallet Logo

Introduction[edit]

Ambox warning pn.svg.png Testers only!

Info Documentation status: Successful connection to a Ledger hardware wallet from within a Kicksecure VirtualBox VM confirmed on 25 February 2021.

Ambox warning pn.svg.png The concepts in this chapter are still valid but the applications and corresponding installation instructions may have changed in the meantime.

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 Factors[edit]

Essentials[edit]

Learn from Ledger and/or other authoritative sources:

Ambox warning pn.svg.png Never enter the seed phrase on any electronic device except the hardware wallet!

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]

  • 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.
  • 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.
  • Insecure Random Number Generator (RNG): Security is reliant upon 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]
  • 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.

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]

It is definitely safer to have at least two Ledger hardware wallets. During initial setup the Ledger does not verify all words of the seed; it only verifies two words of the 24-word seed. This means if one word is mistyped, it will be difficult later on to regain access to personal coins. On the other hand, two Ledgers using the same seed should generate the same addresses, which proves the seed was correctly backed up.

Seed testing applications are available like BOLOS Seed Utility App [archive]. [6] [7] It is probably safer to avoid these tools since they are maintained by a third party and this adds complexity to the procedure.

Another alternative is to:

  1. note some generated addresses
  2. reset the Ledger
  3. re-setup with the seed and see if it still uses the same addresses

Wallet Testing Security[edit]

Before storing any significant funds in a wallet, it is recommended to first test sending a small amount there and then trying to send it back. The reason is software bugs could potentially lead to the presentation of an address where the user does not own the corresponding private key.

The threat of losing funds due to software bugs is not just hypothetical. For instance, this user [archive] [8] utilizing MyEtherWallet.com lost over one thousand dollars due to a historical bug in the Ethereum Javascript implementation.

Threat Model[edit]

Ambox warning pn.svg.png Highly recommended reading: Hardware Wallet Security

Installation[edit]

USB[edit]

Info A USB port is required if using the Nano S, Nano or HW1 Ledger hardware wallets.

Info Ledger USB device will not be detected by the computer before the PIN has been entered. [9] Before proceeding:

  1. Physically connect the Ledger hardware wallet to a USB port.
  2. Turn on Ledger.
  3. Enter the PIN on the Ledger.

Virtualizer Specific Settings[edit]

VirtualBox[edit]

Whonix ™ VirtualBox users only:

Add the Ledger hardware wallet to the virtual machine (VM).

  1. Power off the VM.
  2. Virtual machine → Menu → Settings → USB → USB → check Enable USB Controller → press + → check Ledger → OK
  3. Power on the VM.
  4. Repeat the above after you open an app on Ledger device, ie: Bitcoin, Ethereum, Litecoin etc. It turns out that Ledger device has distinct hardware ID for each app you open on the hardware wallet.

VirtualBox Oracle VM VirtualBox Extension Pack not required.

KVM[edit]

Whonix ™ KVM users only:

Add the Ledger hardware wallet to the virtual machine (VM).

Undocumented.

Qubes[edit]

Qubes-Whonix ™ users note:

For better usability, it is discouraged to start with a Ledger hardware wallet. First learn how to pass any other, "simpler"; USB device to an AppVM and attempt that procedure in order to iron out any eventual Qubes USBVM issues. Any eventual Qubes USBVM issues are Qubes support issues. Not Whonix ™ support issues.

Install Qubes USB Proxy. This step is mandatory for Qubes users. [10]

Install qubes-usb-proxy.

1. Update the package lists. 

sudo apt update

2. Upgrade the system. 

sudo apt full-upgrade

3. Install the qubes-usb-proxy package.

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

sudo apt install --no-install-recommends qubes-usb-proxy

4. Done.

The procedure of installing qubes-usb-proxy is complete.

Electrum Installation[edit]

This step is optional and only necessary if you intend to use Electrum.

Electrum is installed by default in Whonix-Workstation ™, but several dependencies are required for a hardware wallet. [11] [12]

Install libudev-dev libusb-1.0-0-dev python3-btchip.

1. Update the package lists. 

sudo apt update

2. Upgrade the system. 

sudo apt full-upgrade

3. Install the libudev-dev libusb-1.0-0-dev python3-btchip package.

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

sudo apt install --no-install-recommends libudev-dev libusb-1.0-0-dev python3-btchip

4. Done.

The procedure of installing libudev-dev libusb-1.0-0-dev python3-btchip is complete.

[13]

udev Rules[edit]

1. Open a terminal.

[14]

2. Add user user to group plugdev. 

sudo adduser user plugdev

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

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

4. Add the following settings. [15] 

# HW.1 / Nano
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="1b7c|2b7c|3b7c|4b7c", TAG+="uaccess", TAG+="udev-acl"
# Blue
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0000|0000|0001|0002|0003|0004|0005|0006|0007|0008|0009|000a|000b|000c|000d|000e|000f|0010|0011|0012|0013|0014|0015|0016|0017|0018|0019|001a|001b|001c|001d|001e|001f", TAG+="uaccess", TAG+="udev-acl"
# Nano S
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0001|1000|1001|1002|1003|1004|1005|1006|1007|1008|1009|100a|100b|100c|100d|100e|100f|1010|1011|1012|1013|1014|1015|1016|1017|1018|1019|101a|101b|101c|101d|101e|101f", TAG+="uaccess", TAG+="udev-acl"
# Aramis
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0002|2000|2001|2002|2003|2004|2005|2006|2007|2008|2009|200a|200b|200c|200d|200e|200f|2010|2011|2012|2013|2014|2015|2016|2017|2018|2019|201a|201b|201c|201d|201e|201f", TAG+="uaccess", TAG+="udev-acl"
# HW2
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0003|3000|3001|3002|3003|3004|3005|3006|3007|3008|3009|300a|300b|300c|300d|300e|300f|3010|3011|3012|3013|3014|3015|3016|3017|3018|3019|301a|301b|301c|301d|301e|301f", TAG+="uaccess", TAG+="udev-acl"
# Nano X
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0004|4000|4001|4002|4003|4004|4005|4006|4007|4008|4009|400a|400b|400c|400d|400e|400f|4010|4011|4012|4013|4014|4015|4016|4017|4018|4019|401a|401b|401c|401d|401e|401f", TAG+="uaccess", TAG+="udev-acl"

5. Save.

6. Non-Qubes-Whonix ™ users only: 

sudo udevadm trigger

sudo udevadm control --reload-rules

A reboot is not required for Non-Qubes-Whonix ™; skip the next two steps to shutdown and restart the VM.

7. Shut down VM.

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

Ledger Live Application Installation[edit]

Introduction[edit]

notice Digital signatures can increase security but this requires knowledge. Learn more about digital software signature verification.

Ambox warning pn.svg.png Two download methods are available.

  • A) Simplified: Download instructions on this wiki page are simplified and less secure.
  • B) Secure: Higher difficulty, but more secure download and digital software signature verification instructions are available on the How-to: Ledger Live Download with Digital Signature Verification wiki page. Apply those instructions and then return to this page.

Download[edit]

scurl-download https://github.com/LedgerHQ/ledger-live-desktop/releases/download/v2.21.3/ledger-live-desktop-2.21.3-linux-x86_64.AppImage

Make Executable[edit]

Make the Ledger Live AppImage executable. 

chmod +x ledger-live-desktop-2.21.3-linux-x86_64.AppImage

Ledger Live Start Menu Entry[edit]

Info This step is optional.

Inside Whonix-Workstation ™ (Qubes-Whonix ™: App Qubes).

1. Create folder ~/.local/share/applications. 

mkdir -p ~/.local/share/applications

2. Open file ~/.local/share/applications/ledger.desktop in a text editor of your choice as a regular, non-root user.

If you are using a graphical environment, run. 

mousepad ~/.local/share/applications/ledger.desktop

If you are using a terminal, run. 

nano ~/.local/share/applications/ledger.desktop

3. Paste the following contents. 

[Desktop Entry]
Name=Ledger Live
Comment=Ledger Live - Desktop
Exec=bash -c '~/ledger-live-desktop-*-linux-x86_64.AppImage'
Terminal=false
Type=Application
Icon=money-manager-ex
StartupWMClass=Ledger Live
MimeType=x-scheme-handler/ledgerhq;
Categories=Finance;

4. Save.

5. Qubes-Whonix ™ only: perform platform-specific steps.

In dom0:

  • Refresh Qubes dom0 appmenu: VM settings → Applications → Refresh Applications
  • Add desktop shortcut.

Usage[edit]

Ledger Live[edit]

  1. Physically connect the Ledger hardware wallet to a USB port.
  2. Enter the PIN on the Ledger.
  3. Start the Ledger VM.

Start Ledger Live. 

./ledger-live-desktop-2.21.3-linux-x86_64.AppImage

For further actions, refer to upstream Ledger usage instructions.

Electrum[edit]

Same basic steps as for Ledger Live but then start Electrum, not Ledger Live.

Do not attempt to run Electrum and Ledger Live at the same time. This is a Ledger limitation, unrelated to Whonix ™.

An Electrum wallet will only show legacy bitcoin addresses and their balances or segwit wallet bitcoin addresses and their balances, not both. It is possible to have multiple Electrum wallets and switch between them.

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]

BIOS[edit]

The USB device might be passed to the Ledger VM, but Ledger applications may not recognize the Ledger hardware wallet. If that occurs, try the following in BIOS settings:

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

It is unnecessary to reinstall Qubes.

Ledger[edit]

To troubleshoot Ledger problems, try the following:

  • Use the Mananger tab in Ledger Live first.
  • Qubers users note: Update the firmware of the Ledger hardware wallet by connecting it to a non-Qubes Linux computer (where connections are possible using Ledger Live).

Try with Debian First[edit]

Issues which are not caused by Whonix ™:

  1. Using Ledger on (Debian) Linux can be challenging.
  2. Using USB devices with VirtualBox can be challenging.
  3. Using Ledger with a virtualizer such as VirtualBox can be challenging.

Therefore, as per Free Support Principle:

  1. Learn how to use Ledger on a Debian host.
  2. Learn how to use USB devices with your choice of virtualizer.
  3. Learn how to use Ledger with Debian inside VirtualBox.

Only after completing these steps, try to use Ledger in a Whonix ™ VM.

Qubes R4[edit]

The Qubes R4 USB widget formerly had bugs such as showing the USB device was connected to a VM while qvm-usb -- the command line authority whose judgment should be trusted more -- disagreed or showed the same USB device more than once in the menu. [16]

If similar issues re-emerge, follow these steps.

1. Physically connect the Ledger hardware wallet to a USB port.
2. Run the following command to get an overview of USB devices detected by Qubes. 

qvm-usb

3. Check the output is similar to the following. 

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

4. Use the following command to connect the Ledger hardware wallet to the preferred VM.

Replace ledger-debian-buster with the actual name of the VM. 

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

See also: Dev/Ledger Hardware Wallet.

Issues[edit]

Forum Discussion[edit]

Donations[edit]

After setting up a hardware wallet, please consider making a donation to Whonix ™ to keep it running for many years to come.

Donate Bitcoin (BTC) to Whonix ™.

Bitcoin accepted here 35wdTVzyYGzRd7W2Wb2dunw3v5Am14sxPX

Whonix donate bitcoin.png

Monero accepted here Donate Monero (XMR) to Whonix ™. 

49sP9cMQ5jvhzKW477TH6NJJ2z3pqD8pYRqCyCAqN1Y7QYQMxKf7SPq356BBiNcRwzagpcjqkK66LG4wwr37YjSS3kY3x5P

Monero donate Whonix.png

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

    This repository contains an application for the Ledger Nano S that allows the user to verify the backup of their BIP 39 mnemonic by comparing it to the master seed stored on the device.
  7. ↑ https://www.reddit.com/r/ledgerwallet/comments/6ez4qs/ledger_nano_s_seed_utility_app_released/ [archive]
  8. ↑ Web citation [archive].
  9. ↑ This is probably because Ledger does not announce itself before that.
  10. ↑ See: Problem with adding USB device to a VM [archive].
  11. ↑ https://electrum.readthedocs.io/en/latest/hardware-linux.html [archive]
  12. ↑ Broken link: https://ledger.groovehq.com/knowledge_base/topics/how-to-setup-electrum-nano-slash-nano-s [archive]
  13. ↑ This is probably outdated: TODO: bug report against https://packages.debian.org/bullseye/python-btchip [archive] ? python-pip warning: See Avoid Third Party Package Managers! 
    python3 -m pip install btchip-python
  14. ↑ Further research is required to confirm if this step is still necessary. The issue appears to have been fixed, see: Ledger Nano S not detected on Linux [archive].
  15. ↑
  16. ↑ USB devices shown multiple times in devices popup menu #3266 [archive]
Fosshost is sponsors Kicksecure ™ stage server 100px
Fosshost About Advertisements

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

Follow: 1024px-Telegram 2019 Logo.svg.png Iconfinder Apple Mail 2697658.png Twitter.png Facebook.png Rss.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Support: Discourse logo.png

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

Whonix donate bitcoin.png Monero donate Whonix.png United Federation of Planets 1000px.png

Twitter-share-button.png Facebook-share-button.png Telegram-share.png link=mailto:?subject=Ledger Hardware Wallet&body=./Ledger_Hardware_Wallet link=https://reddit.com/submit?url=./Ledger_Hardware_Wallet&title=Ledger Hardware Wallet link=https://news.ycombinator.com/submitlink?u=./Ledger_Hardware_Wallet&t=Ledger Hardware Wallet link=https://mastodon.technology/share?message=Ledger Hardware Wallet%20./Ledger_Hardware_Wallet&t=Ledger Hardware Wallet

Iconfinder Apple Mail 2697658.png Subscribe to Whonix ™ Newsletter.

https link onion link Priority Support | Investors | Professional Support

Whonix ™ | © ENCRYPTED SUPPORT LP | Heckert gnu.big.png Freedom Software / Osi standard logo 0.png Open Source (Why?)

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole.

Retrieved from "https://www.whonix.org/w/index.php?title=Ledger_Hardware_Wallet&oldid=69370"
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.
More information