How-to: Ledger Hardware Wallet in Kicksecure
Installation, Setup, Security, Ledger Live, Electrum
Update on 25 May 2023: Ledger Recovery key extraction.
Introduction[edit]
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 Factors[edit]
Essentials[edit]
Learn from Ledger and/or other authoritative sources:
- What is a seed phrase?
- Ledger Phishing Scam Targets Crypto Hardware Wallet Users
Security Risks[edit]
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 App. [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:
- note some generated addresses
- reset the Ledger
- 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 utilizing MyEtherWallet.com lost over one thousand dollars due to a historical bug in the Ethereum Javascript implementation.
Threat Model[edit]
Installation[edit]
USB[edit]
Virtualizer Specific Settings[edit]
VirtualBox[edit]
Kicksecure VirtualBox users only:
Add the Ledger hardware wallet to the virtual machine (VM).
- Power off the VM.
Virtual machine
→Menu
→Settings
→USB
→USB
→ checkEnable USB Controller
→ press+
→ checkLedger
→OK
- Power on the VM.
- 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).
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
. Follow steps A to E.
A Platform specific notice.
- Kicksecure: No special notice.
- Kicksecure-Qubes: In Template.
B Update the package lists and upgrade the system .
sudo apt update && sudo apt full-upgrade
C Install the qubes-usb-proxy
package(s).
Using apt
command line
--no-install-recommends
option
is in most cases optional.
sudo apt install --no-install-recommends qubes-usb-proxy
D Platform specific notice.
- Kicksecure: No special notice.
- Kicksecure-Qubes: Shut down Template and restart App Qubes based on it as per Qubes Template Modification .
E 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
. Follow steps A to E.
A Platform specific notice.
- Kicksecure: No special notice.
- Kicksecure-Qubes: In Template.
B Update the package lists and upgrade the system .
sudo apt update && sudo apt full-upgrade
C Install the libudev-dev libusb-1.0-0-dev python3-btchip
package(s).
Using apt
command line
--no-install-recommends
option
is in most cases optional.
sudo apt install --no-install-recommends libudev-dev libusb-1.0-0-dev python3-btchip
D Platform specific notice.
- Kicksecure: No special notice.
- Kicksecure-Qubes: Shut down Template and restart App Qubes based on it as per Qubes Template Modification .
E Done.
The procedure of installing package(s) libudev-dev libusb-1.0-0-dev python3-btchip
is complete.
udev Rules[edit]
1. Open a terminal.
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 for Qubes
NOTES:
- When using Kicksecure-Qubes, this needs to be done inside the Template.
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.
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]
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]
- Physically connect the Ledger hardware wallet to a USB port.
- Enter the PIN on the Ledger.
- 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:
- Using Ledger on (Debian) Linux can be challenging.
- Using USB devices with VirtualBox can be challenging.
- Using Ledger with a virtualizer such as VirtualBox can be challenging.
Therefore, as per Self Support First Policy:
- Learn how to use Ledger on a Debian host.
- Learn how to use USB devices with your choice of virtualizer.
- 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]
- general: https://forums.whonix.org/t/ledger-nano-s-support/8521/2
- KVM-specific: https://forums.whonix.org/t/ledger-nano-s-no-device-found/10934
Donations[edit]
After setting up a hardware wallet, please consider making a donation to Kicksecure to keep it running for many years to come.
Donate Bitcoin (BTC) to Kicksecure.
3DaJWfHyLv4RVnvMD7K2Mz2AX2r3fwiQwV
Donate Monero (XMR) to Kicksecure.
84ozcSohQfoV6nRgGfaQ8uBvWphXAH8zDTTuotVnJWF1JMNQfvgNFdbEo4ZnJ9hxPMeYfJuUoWGH3MRaXCfbYk8sFFgm4XL
Footnotes[edit]
- ↑ https://en.bitcoin.it/wiki/Hardware_wallet
- ↑ https://www.ledger.com/ledger-wallets-always-safe-never-sorry
- ↑ https://en.bitcoin.it/wiki/Hardware_wallet
- ↑ The attacker generates psuedo-randomness that is indistinguishable from true randomness, but is still predictable.
- ↑
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.
- ↑ https://www.reddit.com/r/ledgerwallet/comments/6ez4qs/ledger_nano_s_seed_utility_app_released/
- ↑ This is probably because Ledger does not announce itself before that.
- ↑ See: Problem with adding USB device to a VM.
- ↑ https://electrum.readthedocs.io/en/latest/hardware-linux.html
- ↑ https://web.archive.org/web/20170103032058/https://ledger.groovehq.com/knowledge_base/topics/how-to-setup-electrum-nano-slash-nano-s
- ↑
This is probably outdated:
- Was not required.
ln -s /lib/x86_64-linux-gnu/libudev.so.1 /lib/x86_64-linux-gnu/libudev.so
- https://github.com/spesmilo/electrum/issues/3422#issuecomment-348063118
- Install
python3-btchip
(btchip-python
?). Unfortunately it is not available from Debian's repository. Therefore we have to install it using python-pip.
- Was not required.
- ↑ 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.
- ↑
- https://support.ledger.com/hc/en-us/articles/115005165269-Fix-connection-issues
- https://github.com/LedgerHQ/udev-rules
- https://github.com/LedgerHQ/udev-rules/blob/master/20-hw1.rules
- https://github.com/LedgerHQ/udev-rules/blob/master/add_udev_rules.sh
- https://github.com/LedgerHQ/udev-rules/blob/master/LICENSE
- ↑ USB devices shown multiple times in devices popup menu #3266
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!