From 87c848f1a4ef03c08529e6505a7f5f0bda26b686 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 26 Apr 2022 20:13:25 +0200 Subject: [PATCH] Document that opgpcard needs pcscd; troubleshooting cards being locked by scdaemon. --- guide/src/opgpcard.md | 22 ++++++++++++++++++++++ tools/README.md | 3 +++ 2 files changed, 25 insertions(+) diff --git a/guide/src/opgpcard.md b/guide/src/opgpcard.md index 5a1c771..de4530e 100644 --- a/guide/src/opgpcard.md +++ b/guide/src/opgpcard.md @@ -18,6 +18,28 @@ To install the `opgpcard` tool, we [Detailed installation instructions](https://gitlab.com/hkos/openpgp-card/-/tree/main/tools#install). +## Running opgpcard + +### Make sure PC/SC is available + +`opgpcard` uses the PC/SC framework. So on Linux-based systems, you need to make sure the `pcscd` +service is running to be able to access your OpenPGP cards. + +### Troubleshooting "Error: No cards found" + +If `opgpcard` unexpectedly prints `Error: No cards found`, your OpenPGP card might be locked by GnuPG. + +When you use GnuPG with an OpenPGP card, its `scdaemon` service typically opens your card with exclusive access +privileges, for an indefinite duration. This prevents other software from accessing the card. + +To re-gain access to your card, you can: +- mechanically unplug and replug the card, or you can +- tell GnuPG to temporarily shut down its `scdaemon` subsystem (the recommended way to do this is: `gpgconf --kill scdaemon`). + +After this, `opgpcard` should be able to access your OpenPGP card. + +(Note: With recent versions of GnuPG, you can configure `scdaemon` to +[use PC/SC in shared access mode](https://www.gnupg.org/documentation/manuals/gnupg/Scdaemon-Options.html#index-pcsc_002dshared)) # Exploring the state of an OpenPGP card diff --git a/tools/README.md b/tools/README.md index 524c433..e773470 100644 --- a/tools/README.md +++ b/tools/README.md @@ -33,6 +33,9 @@ $ cargo install openpgp-card-tools Finally, add `$HOME/.cargo/bin` to your PATH to be able to run the installed binaries. +`opgpcard` uses the PC/SC framework. So on Linux-based systems, you need to make sure the `pcscd` +service is running, to be able to access your OpenPGP cards. + ## opgpcard A tool to inspect, configure and use OpenPGP cards. All calls of this tool are