{{Header}}
{{#seo:
|description=Installation, Setup, Security, Ledger Live, Electrum
|image=Ledger_Nano_S_-_Hard_Wallet_-_Cold_Storage_for_Cryptocurrency_04.jpg
}}
{{Title|
title=How-to: Ledger Hardware Wallet in {{project_name_long}}
}}
<div class="mininav">
* [[Ledger Hardware Wallet]]
* [[Ledger Live Installation with Verification]]
</div>
{{crypto_hardware_wallets_mininav}}
[[image:Ledger_Nano_S_-_Hard_Wallet_-_Cold_Storage_for_Cryptocurrency_04.jpg|thumb]]
{{intro|
Installation, Setup, Security, Ledger Live, Electrum

Update on 25 May 2023: [[Hardware_Wallet_Security#Key_Extraction|Ledger Recovery key extraction]].
}}
[[image:Ledgericon.png|Ledger Hardware Wallet Logo|thumb]]
= Introduction =
{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = Testers only!
}}

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = Documentation status: Successful connection to a Ledger hardware wallet from within a [[Kicksecure]] VirtualBox VM confirmed on 25 February 2021.
}}

{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = The concepts in this chapter are still valid but the applications and corresponding installation instructions may have changed in the meantime.
}}

[https://www.ledger.com/ 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: <ref>
https://en.bitcoin.it/wiki/Hardware_wallet
</ref>

* 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. <ref>
https://www.ledger.com/ledger-wallets-always-safe-never-sorry
</ref>

= Security Factors =
== Essentials ==
Learn from Ledger and/or other authoritative sources:

* What is a seed phrase?
* [https://blog.kraken.com/post/6746/ledger-phishing-scam-targets-crypto-hardware-wallet-users/ Ledger Phishing Scam Targets Crypto Hardware Wallet Users]
*
{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = Never enter the seed phrase on any electronic device except the hardware wallet!
}}
* [https://support.ledger.com/hc/en-us/articles/4404389367057-Is-my-Ledger-device-genuine-?support=true Check if device is genuine]

== Security Risks ==

{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = '''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: <ref>
https://en.bitcoin.it/wiki/Hardware_wallet
</ref>

* <u>Compromised production process</u>: Hardware backdoors could be introduced via intentional or unintentional actions that leaves security holes in the final product.
* <u>Device interdiction</u>: No hardware wallet solution can deal with the threat of government programs that intercept hardware and modify them in transit to introduce backdoors.
* <u>Imperfect implementation</u>: If bugs are present in the software, firmware or hardware, then attackers may be able to gain unauthorized access to the hardware wallet.
* <u>Insecure Random Number Generator (RNG)</u>: 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. <ref>
The attacker generates psuedo-randomness that is indistinguishable from true randomness, but is still predictable.
</ref>
*  <u>Malware swapping recipient Bitcoin addresses</u>: 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 ==

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 [https://github.com/parkerhoyes/bolos-app-seedutility BOLOS Seed Utility App]. <ref>
<blockquote>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.</blockquote>
</ref> <ref>
https://www.reddit.com/r/ledgerwallet/comments/6ez4qs/ledger_nano_s_seed_utility_app_released/
</ref> 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 ==

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, [https://www.reddit.com/r/ethereum/comments/48rt6n/using_myetherwalletcom_just_burned_me_for/ this user] utilizing MyEtherWallet.com lost over one thousand dollars due to a historical bug in the Ethereum Javascript implementation.

== Threat Model ==
{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = Highly recommended reading: [[Hardware Wallet Security]]
}}

= Installation =
== USB ==
{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = A USB port is required if using the Nano S, Nano or HW1 Ledger hardware wallets.
}}

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = Ledger USB device will not be detected by the computer before the PIN has been entered. <ref>
This is probably because Ledger does not announce itself before that.
</ref> Before proceeding:

# Physically connect the Ledger hardware wallet to a USB port.
# Turn on Ledger.
# Enter the PIN on the Ledger.
}}

== Virtualizer Specific Settings ==
=== VirtualBox ===
{{project_name_short}} [[VirtualBox]] users only:

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

# Power off the VM.
# <code>Virtual machine</code> &rarr; <code>Menu</code> &rarr; <code>Settings</code> &rarr; <code>USB</code> &rarr; <code>USB</code> &rarr; check <code>Enable USB Controller</code> &rarr; press <code>+</code> &rarr; check <code>Ledger</code> &rarr; <code>OK</code>
# 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.

[[Dev/VirtualBox#VirtualBox_Oracle_VM_VirtualBox_Extension_Pack|VirtualBox Oracle VM VirtualBox Extension Pack]] <u>not</u> required.

=== KVM ===
{{project_name_short}} [[KVM]] users only:

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

[[Undocumented]].

=== Qubes ===
{{q_project_name_long}} 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 {{project_name_short}} support issues.

Install Qubes USB Proxy. This step is mandatory for [[Qubes]] users. <ref>
See:
[https://github.com/QubesOS/qubes-issues/issues/2473#issuecomment-273634599 Problem with adding USB device to a VM].
</ref>

{{Install_Package|package=
qubes-usb-proxy
}}

== Electrum Installation ==

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

[[Electrum]] is installed by default in {{project_name_workstation_long}}, but several dependencies are required for a hardware wallet. <ref>
https://electrum.readthedocs.io/en/latest/hardware-linux.html
</ref> <ref>
https://web.archive.org/web/20170103032058/https://ledger.groovehq.com/knowledge_base/topics/how-to-setup-electrum-nano-slash-nano-s
</ref>

{{Install_Package|package=
libudev-dev libusb-1.0-0-dev python3-btchip
}}

<ref>
This is probably outdated:

* Was not required. <code>ln -s /lib/x86_64-linux-gnu/libudev.so.1 /lib/x86_64-linux-gnu/libudev.so</code>
* https://github.com/spesmilo/electrum/issues/3422#issuecomment-348063118
* Install <code>python3-btchip</code> (<code>btchip-python</code> ?). 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/{{Stable project version based on Debian codename}}/python-btchip ?

python-pip warning: See [[Install_Software#Avoid_Third_Party_Package_Managers|Avoid Third Party Package Managers]]!

{{CodeSelect|code=
python3 -m pip install btchip-python
}}
</ref>

== udev Rules ==
{{Box|text=
'''1.''' Open a terminal.

<ref>
Further research is required to confirm if this step is still necessary. The issue appears to have been fixed, see: [https://github.com/spesmilo/electrum/issues/3947 Ledger Nano S not detected on Linux].
</ref>

'''2.''' Add user <code>user</code> to group <code>plugdev</code>.

{{CodeSelect|code=
sudo adduser user plugdev
}}

'''3.''' {{Open with root rights
|filename=/etc/udev/rules.d/20-hw1.rules
}}

'''4.''' Add the following settings. <ref>
* 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
</ref>

<pre>
# 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"
</pre>

'''5.''' Save.

'''6.''' {{non_q_project_name_long}} users only:

{{CodeSelect|code=
sudo udevadm trigger
}}

{{CodeSelect|code=
sudo udevadm control --reload-rules
}}

A reboot is not required for {{non_q_project_name_short}}; 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 <code>Ledger VM</code>.
}}

== Ledger Live Application Installation ==
==== Introduction ====
{{always_verify_signatures_reminder}}

{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = Two download methods are available.

* '''A)''' <u>Simplified</u>: Download instructions on this wiki page are simplified and less secure.
* '''B)''' <u>Secure</u>: Higher difficulty, but more secure download and digital software signature verification instructions are available on the [[Ledger_Live_Installation_with_Verification|How-to: Ledger Live Download with Digital Signature Verification]] wiki page. Apply those instructions and then return to this page.
}}

==== Download ====
{{CodeSelect|code=
scurl-download https://download.live.ledger.com/ledger-live-desktop-{{version_ledger_live}}-linux-x86_64.AppImage
}}

=== Make Executable ===
Make the Ledger Live AppImage executable.

{{CodeSelect|code=
chmod +x ledger-live-desktop-{{version_ledger_live}}-linux-x86_64.AppImage
}}

=== Ledger Live Start Menu Entry ===

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = This step is optional.
}}

'''1.''' Create folder <code>~/.local/share/applications</code>.

{{CodeSelect|code=
mkdir -p ~/.local/share/applications
}}

'''2.''' {{Open File
|filename=~/.local/share/applications/ledger.desktop
}}

'''3.''' Paste the following contents.

{{CodeSelect|code=
[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.''' ''{{q_project_name_short}} only:'' perform platform-specific steps.

In <code>dom0</code>:
* Refresh Qubes <code>dom0</code> appmenu: <code>VM settings</code> &rarr; <code>Applications</code> &rarr; <code>Refresh Applications</code>
* Add desktop shortcut.

= Usage =
== Ledger Live ==
# Physically connect the Ledger hardware wallet to a USB port.
# Enter the PIN on the Ledger.
# Start the <code>Ledger VM</code>.

Start Ledger Live.

{{CodeSelect|code=
./ledger-live-desktop-{{Version_ledger_live}}-linux-x86_64.AppImage
}}

For further actions, refer to upstream Ledger usage instructions.

== Electrum ==
Same basic steps as for [[#Ledger Live|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 {{project_name_short}}.

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 <code>derivation path</code>.

* The default is <code>m/44'/0'/0'</code> for legacy bitcoin addresses.
* You should use <code>m/49'/0'/0'</code> for segwit bitcoin addresses.

= Troubleshooting =
== BIOS ==

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

* disable <code>Legacy USB Support</code>
* disable <code>XHCI Pre-Boot Mode</code>
* attempt flipping other USB-related BIOS options

It is unnecessary to reinstall Qubes.

== Ledger ==

To troubleshoot Ledger problems, try the following:

* Use the <code>Mananger</code> 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 ==
Issues which are not caused by {{project_name_short}}:

# 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|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 {{project_name_short}} VM.

== Qubes R4 ==

The Qubes R4 USB widget formerly had bugs such as showing the USB device was connected to a VM while <code>qvm-usb</code> -- the command line authority whose judgment should be trusted more -- disagreed or showed the same USB device more than once in the menu. <ref>
[https://github.com/QubesOS/qubes-issues/issues/3266 USB devices shown multiple times in devices popup menu #3266]
</ref>

If similar issues re-emerge, follow these steps.

{{Box|text=
'''1.''' Physically connect the Ledger hardware wallet to a USB port.<br />
'''2.''' Run the following command to get an overview of USB devices detected by Qubes.

{{CodeSelect|code=
qvm-usb
}}

'''3.''' Check the output is similar to the following.

<pre>
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
</pre>

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

Replace <code>ledger-debian-buster</code> with the actual name of the VM.

{{CodeSelect|code=
qvm-usb attach ledger-debian-buster sys-usb:2-1.4
}}
}}

See also: [[Dev/Ledger Hardware Wallet]].

= Issues =
* [https://github.com/LedgerHQ/ledger-live-desktop/issues/3672 publish firmware hashes of the unsecured chip on Ledger Nano X]

= Forum Discussion =
* 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 =
After setting up a hardware wallet, please consider making a [[Donate|donation]] to {{project_name_short}} to keep it running for many years to come.

{{Pay_Bitcoin_Specific}}

{{Pay_Monero_Specific}}

= Footnotes =
{{reflist|close=1}}

{{Footer}}

[[Category:Documentation]]