Guide to using Ledger as an OpenPGP Card under Linux

Yanke G. — Fri, 11 Oct 2024 03:23:05 +0000

Ledger officially provides OpenPGP app, but the configuration process under Linux is a bit troublesome. I spent a lot of effort to overcome the difficulties, thus I recorded it here for reference.

Prepare your Ledger device

1. Install the OpenPGP app on Ledger device

Open Ledger Live desktop application
Turn on Developer Mode to make OpenPGP app available for installation
Install the OpenPGP app to Ledger device

2. Connect Ledger device to Linux host

Connect your Ledger device to a Linux host
Open the OpenPGP app on Ledger device

Prepare your Linux host

1. Install required packages

Ubuntu/Debian for example:

sudo apt update
sudo apt install -y scdaemon pcscd pcsc-tools libccid usbutils

2. Allow current user to access Smart Card Reader

a Polkit rule is required to allow the current user to access the Smart Card Reader.

Create a file at /usr/share/polkit-1/rules.d/allow-smartcard.rules with content below:

// replace YOUR_USERNAME with your username
polkit.addRule(function (action, subject) {
  if (
    (action.id == "org.debian.pcsc-lite.access_card" ||
      action.id == "org.debian.pcsc-lite.access_pcsc") &&
    subject.user == "YOUR_USERNAME"
  ) {
    return polkit.Result.YES;
  }
});

3. Enable and restart `pcscd` service

sudo systemctl enable pcscd
sudo systemctl restart pcscd

4. Ensure Ledger device is recognized by `libccid`

Run following command to check if Ledger device is already recognized as a Smart Card Reader

sudo pcsc_scan -r

If your Ledger device is not listed, you need to do following steps:

1. Gather information of your Ledger device

Execute lsusb, you will find something like this

Bus 002 Device 005: ID 2c97:4009 Ledger Nano X

This means your Ledger device have:

VendorID = 0x2C97
ProductID = 0x4009
DisplayName = Ledger Nano X

2. Edit /etc/libccid_Info.plist

Add VendorID, ProductID and DisplayName to ifdVendorID, ifdProductID and ifdFriendlyName sections.

3. Restart pcscd

sudo systemctl restart pcscd

4. Rerun sudo pcsc_scan -r to check if your Ledger device is recognized

5. Disable built-in `ccid` support for `scdaemon`

# ensure .gnupg directory exists
gpg -k
# create scdaemon.conf file
echo "disable-ccid" >> ~/.gnupg/scdaemon.conf

Check if everything is ready

gpg --card-status

This should show the information of your Ledger device as a OpenPGP Card.

You can do future operations like gpg --edit-key to manage your OpenPGP keys.

Troubleshooting

1. git: gpg failed to sign the data

When you use git commit -S to sign your commit, you may encounter the error gpg: signing failed: No such device.

Maybe you need to set GPG_TTY environment variable to the correct value.

Add these lines to your shell profile file (e.g. ~/.bashrc, ~/.zshrc)

export GPG_TTY=$(tty)

DEV Community: Yanke G.