How-to: Ledger Hardware Wallet in Kicksecure

From Kicksecure
Jump to navigation Jump to search

Installation, Setup, Security, Ledger Live, Electrum

Update on 25 May 2023: Ledger Recovery key extraction.

Ledger Hardware Wallet Logo

Introduction[edit]

Testers only!

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

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

Ledger walletsarchive.org 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:

Never enter the seed phrase on any electronic device except the hardware wallet!

Security Risks[edit]

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.

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 Apparchive.org. [5] [6] 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 userarchive.org utilizing MyEtherWallet.com lost over one thousand dollars due to a historical bug in the Ethereum Javascript implementation.

Threat Model[edit]

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

Kicksecure 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]

Kicksecure KVM users only:

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

Undocumented.

Qubes[edit]

Kicksecure for Qubes 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 Kicksecure support issues.

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

Install package(s) qubes-usb-proxy following these instructions

1 Platform specific notice.

2 Update the package lists and upgrade the system The Web Archive Onion Version .

sudo apt update && sudo apt full-upgrade

3 Install the qubes-usb-proxy package(s).

Using apt command line --no-install-recommends option The Web Archive Onion Version is in most cases optional.

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

4 Platform specific notice.

5 Done.

The procedure of installing package(s) 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 Kicksecure, but several dependencies are required for a hardware wallet. [9] [10]

Install package(s) libudev-dev libusb-1.0-0-dev python3-btchip following these instructions

1 Platform specific notice.

2 Update the package lists and upgrade the system The Web Archive Onion Version .

sudo apt update && sudo apt full-upgrade

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

Using apt command line --no-install-recommends option The Web Archive Onion Version is in most cases optional.

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

4 Platform specific notice.

5 Done.

The procedure of installing package(s) libudev-dev libusb-1.0-0-dev python3-btchip is complete.

[11]

udev Rules[edit]

1. Open a terminal.

[12]

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.

Kicksecure

See Open File with Root Rights The Web Archive Onion Version for detailed instructions on why to use sudoedit for better security and how to use it.

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

Kicksecure for Qubes

NOTES:

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

  • After applying this change, shutdown the Template.
  • All App Qubes based on the Template need to be restarted if they were already running.
  • This is a general procedure required for Qubes and unspecific to Kicksecure for Qubes.

Others and Alternatives

  • This is just an example. Other tools could achieve the same goal.
  • If this example does not work for you or if you are not using Kicksecure, please refer to this link.

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

4. Add the following settings. [13] 

# 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"
# Nano SP
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0005|5000|5001|5002|5003|5004|5005|5006|5007|5008|5009|500a|500b|500c|500d|500e|500f|5010|5011|5012|5013|5014|5015|5016|5017|5018|5019|501a|501b|501c|501d|501e|501f", TAG+="uaccess", TAG+="udev-acl"
# Ledger Stax
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="6011", TAG+="uaccess", TAG+="udev-acl"

5. Save.

6. Kicksecure users only:

sudo udevadm trigger

sudo udevadm control --reload-rules

A reboot is not required for Kicksecure; 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]

  • Digital signatures are a tool enhancing download security. They are commonly used across the internet and nothing special to worry about.
  • Optional, not required: Digital signatures are optional and not mandatory for using Kicksecure, but an extra security measure for advanced users. If you've never used them before, it might be overwhelming to look into them at this stage. Just ignore them for now.
  • Learn more: Curious? If you are interested in becoming more familiar with advanced computer security concepts, you can learn more about digital signatures here digital software signatures.

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://download.live.ledger.com/ledger-live-desktop-2.73.1-linux-x86_64.AppImage

Make Executable[edit]

Make the Ledger Live AppImage executable.

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

Ledger Live Start Menu Entry[edit]

Info This step is optional.

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. Kicksecure-Qubes 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.73.1-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 Kicksecure.

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 Kicksecure:

  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 Self Support First Policy:

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

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 Kicksecure to keep it running for many years to come.

Bitcoin accepted here Donate Bitcoin (BTC) to Kicksecure.

3DaJWfHyLv4RVnvMD7K2Mz2AX2r3fwiQwV

Monero accepted here Donate Monero (XMR) to Kicksecure.

84ozcSohQfoV6nRgGfaQ8uBvWphXAH8zDTTuotVnJWF1JMNQfvgNFdbEo4ZnJ9hxPMeYfJuUoWGH3MRaXCfbYk8sFFgm4XL

Footnotes[edit]

  1. ↑ https://en.bitcoin.it/wiki/Hardware_walletarchive.org
  2. ↑ https://www.ledger.com/ledger-wallets-always-safe-never-sorryarchive.org
  3. ↑ https://en.bitcoin.it/wiki/Hardware_walletarchive.org
  4. ↑ The attacker generates psuedo-randomness that is indistinguishable from true randomness, but is still predictable.
  5. ↑

    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.
  6. ↑ https://www.reddit.com/r/ledgerwallet/comments/6ez4qs/ledger_nano_s_seed_utility_app_released/archive.org
  7. ↑ This is probably because Ledger does not announce itself before that.
  8. ↑ See: Problem with adding USB device to a VMarchive.org.
  9. ↑ https://electrum.readthedocs.io/en/latest/hardware-linux.htmlarchive.org
  10. ↑ https://web.archive.org/web/20170103032058/https://ledger.groovehq.com/knowledge_base/topics/how-to-setup-electrum-nano-slash-nano-sarchive.org
  11. ↑ This is probably outdated: TODO: bug report against https://packages.debian.org/bookworm/python-btchiparchive.org ? python-pip warning: See Avoid Third Party Package Managers! python3 -m pip install btchip-python
  12. ↑ 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 Linuxarchive.org.
  13. ↑
  14. ↑ USB devices shown multiple times in devices popup menu #3266archive.org
Your support makes
all the difference!

We believe security software like Kicksecure needs to remain Open Source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!

Retrieved from "https://www.kicksecure.com/w/index.php?title=Ledger_Hardware_Wallet&oldid=84575"