This page documents how to setup and use a OpenPGP smartcard in Debian.
Contents
Introduction
The OpenPGP smartcard was conceived by g10 Code, the main group behind GnuPG development. It is worldwide and primarily distributed by the German company Floss Shop (former Kernel Concepts). The Free Software Foundation Europe (FSFE) donated a customized version of the OpenPGP smartcard to all new members, calling it the Fellowship crypto card. In October 2017, the FSFE stopped issuing ?SmartCards for new supporters
Please check the buying page if you plan to buy it.
In 2012, alternative free software implementation of USB Token has been released. That's Gnuk, which conforms to OpenPGPcard specification 2.0. It only supports RSA 2048-bit keys, but it works great. It takes about 1.5sec to make a signature. Please see FST-01 WiKi for hardware product information.
Setting up PGP and smartcards manually requires many steps. The PGP master key and smartcard environment can be managed conveniently and securely, without using the command line, using the Clean Room Live CD image
Card Features
The OpenPGP smartcard supports (depending on version):
- 3 independent 1024 bit RSA keys (signing, encryption, authentication for SSH or PAM) or
- RSA with up to 3072 bit with the 2.0 version of the card.
RSA with up to 4096 bit with the 2.0 version of the card and GnuPG 2.0.18 1 2
- Key generation on card or import of existing keys.
- Length of PIN between 6 and 254 characters; not restricted to numbers.
- T=1 protocol; compatible with most readers.
Specification freely available and usable without any constraints (version 1.1, preliminary version 2).
- OpenPGP card 2.0 is not compatible with GnuPGP 1.x, it needs 2.x
Please refer to the upstream page for a complete list.
Reader Hardware
In theory, any smartcard reader from this list should work.
HowTo
Install Software
The OpenPGP smartcard is supported by gnupg together with pcscd and scdaemon in any recent Debian release.
$ apt-get install gnupg pcscd scdaemon pcsc-tools
Verify that the card and card reader are detected
Using the command
$ pcsc_scan
you should get a list of connected smartcard readers, and the type of card inserted. On my system using a Gemalto Card reader, the interesting bits are
Scanning present readers... 0: Gemalto PC Twin Reader (38738FB6) 00 00
and
Possibly identified card (using /usr/share/pcsc/smartcard_list.txt): GnuPG card V2
at the end.
Key Generation
There are many guides which explain how to generate an OpenPGP key. You can refer to this guide which will help you to create a key which meets the debian keyring security criterias.
Initialise the smartcard
$ gpg --card-edit Reader ...........: Alcor Micro AU9560 00 00 Application ID ...: 0123456789ABCDEF0123456789ABCDEF Version ..........: 1.1 Manufacturer .....: PPC Card Systems Serial number ....: 00000001 Name of cardholder: [not set] Language prefs ...: de Sex ..............: unspecified URL of public key : [not set] Login data .......: [not set] Signature PIN ....: forced Key attributes ...: rsa1024 rsa1024 rsa1024 Max. PIN lengths .: 254 254 254 PIN retry counter : 3 3 3 Signature counter : 0 Signature key ....: [none] Encryption key....: [none] Authentication key: [none] General key info..: [none] gpg/card> admin Admin commands are allowed gpg/card> help quit quit this menu admin show admin commands help show this help list list all available data name change card holder's name url change URL to retrieve key fetch fetch the key specified in the card URL login change the login name lang change the language preferences sex change card holder's sex cafpr change a CA fingerprint forcesig toggle the signature force PIN flag generate generate new keys passwd menu to change or unblock the PIN verify verify the PIN and list all data unblock unblock the PIN using a Reset Code factory-reset destroy all keys and data gpg/card> name Cardholder's surname: Bar Cardholder's given name: Foo gpg/card> lang Language preferences: en gpg/card> sex Sex ((M)ale, (F)emale or space): m gpg/card> url URL to retrieve public key: https://example.com/foobar.pub gpg/card> login Login data (account name): foobar gpg/card> passwd gpg: OpenPGP card no. 0123456789ABCDEF0123456789ABCDEF detected 1 - change PIN 2 - unblock PIN 3 - change Admin PIN 4 - set the Reset Code Q - quit Your selection? 2 PIN unblocked and new PIN set. 1 - change PIN 2 - unblock PIN 3 - change Admin PIN 4 - set the Reset Code Q - quit Your selection? q gpg/card> list Reader ...........: Alcor Micro AU9560 00 00 Application ID ...: 0123456789ABCDEF0123456789ABCDEF Version ..........: 1.1 Manufacturer .....: PPC Card Systems Serial number ....: 00000001 Name of cardholder: Foo Bar Language prefs ...: en Sex ..............: male URL of public key : https://example.com/foobar.pub Login data .......: foobar Signature PIN ....: forced Key attributes ...: rsa1024 rsa1024 rsa1024 Max. PIN lengths .: 254 254 254 PIN retry counter : 3 3 3 Signature counter : 0 Signature key ....: [none] Encryption key....: [none] Authentication key: [none] General key info..: [none] gpg/card> quit
3) add the authentication and signature card subkeys (in this order, the signature key is just for signing, so no backup needed and the authentication key can AFAIK only be generated on the card)
$ gpg --edit-key $KEYID
command> addcardkey [authentication]
command> addcardkey [signature]4) add an encryption subkey
$ gpg --edit-key $KEYID
command> addkey5) backup the whole key!!!
6) move the encryption key above to the card
$ gpg --edit-key $KEYID
command> key $NUMBER [select the encryption key above]
command> keytocard7) remove your main encryption key
Troubleshooting
Error accessing the card reader
Sometimes (seems especially common with USB card readers) you get error messages like:
gpg: selecting openpgp failed: No such device gpg: OpenPGP card not available: No such device
gpg: selecting openpgp failed: ec=6.32848 gpg: OpenPGP card not available: general error
gpg: selecting openpgp failed: ec=6.32848 gpg: signing failed: general error
Usually it is sufficient to kill scdaemon and try again:
$ killall scdaemon
$ pgrep scdaemon
$
Software interaction
Describe here how to configure other software for the OpenPGP smartcard.
Gnome-Keyring
gnome-keyring-daemon breaks smartcard access. To resolve this for a current session, use
- $ killall gnome-keyring-daemon
See also these instructions
For Mate Desktop in Jessie, gnome keyring has to be disabled using dconf-editor changing the key org/mate/desktop/session/gnome-compat-startup to ['smproxy']
SSH
There are several older descriptions how to setup SSH with OpenPGP smartcard. Check these instructions and please report here with working setup with recent Debian version:
1) Authenticating SSH logins with the Fellowship crypto card
3) SSH For Server Administration
PAM
There are several older instructions Login with GnuPG smartcard and OpenPGP smartcard local user authentication which do not always fully work anymore, because poldi-ctrl is no longer maintained and is no longer part of libpam-poldi package and gpg-connect-agent also gives errors. Therefore these described steps to dump the public key to poldi database does not work.
Using the OpenPGP smartcard with PAM now requires some manual extra steps (after creating/importing keys on smartcard):
$ sudo nano /etc/poldi/localdb/users
add following line:
<YourApplicationID> <YourUsername>
and save your changes after editing this file.
Older instructions describes to dump the public key to /etc/poldi/localdb/keys/<YourApplicationID> file with poldi-ctrl or use gpg-connect-agent. Both do not work (on Debian 12). Therefore this file has to be created manually. The format of this file has been describe on this page:
$ cat /etc/poldi/localdb/keys/D27600012401030300050000864A0000 (public-key (rsa (n #00BC6CECC90DA5F329D215FDBF595C1A920374BD172271F394E138FE99C4E995A7ED536A8D79175C4C65D39071955779C181D85E5A86D9BCAE86BE11A742FD856FEB351 2C23911F932098165CDBD3FF0658C288FCC51BC9FF9BFD84E67AB83C3CAF508EC0B5CDC83179B2A781C0CA15A3BA9CF321F4ABD7E8DE234324536258D62D61AE0BF47C25BD776 02B4D0F107F653B706273C01856B885D27CD57F283BA75EC3AAE5BBB98BC393BCA7D605199070C339DCB4DD8D292160102841B9FCA4F26DED33E112B76BAA042BBD6F7E501E44 C020521E92BDD45B9BCC30A7FF840663C90E3C06C5EBA45BDF7A1046330A8ADF07CE8AFF141DD5B518F1915EEBF6527DEAD9F292FC16F6AE74E7CA275991487CAAF0575B594ED 00AF542B60892AA7A727AC77B566E454F6D19CA2D0614251ADB81685308104A297E7353F7489BC1CCADE673C04F1C344562B8514E395E06220595420EBFE5AD9EE11D92E29597 1A5D0D37E971A70828B8321914454B0890D824C1B69DA65CDF6CD15271E6143198E5816B3E22118854409B5898F5D0114CF4D58DA71F6630F87560042B1D863BA18EAAC2792A3 EA1CC696FDDB79F391ADFA3F04EAC97B851203C61898048CE1DEE1221CB1838358B98EE61FB84BB09AE8022C0AA618E95877FBE0EFD58F3E16BC25FCDDD799B089DC6785DCAF3 9B70F2C3EE1EAD7D1B5390F495D292EB25B32315B5C31#) (e #010001#) ) )
The "n" stands for Modulus and and "e" for Exponent. These can be extracted from the public key with the command:
$ pgpdump -i PublicKey.asc | grep -E '(RSA n|RSA e)'
Check very carefully to use the Modulus and Exponent of the Authentication-key, not the other keys as these do not work. The spaces within the output for Modulus have to be removed and then the output can be added:
(public-key (rsa (n #00<Modulus>#) (e #<Exponent>#) ) )
After this, change the required PAM modules carefully (first use "sufficient" option):
$ sudo nano /etc/pam.d/common-auth (for graphical user login) $ sudo nano /etc/pam.d/gdm-password (for logins and unlocks) $ sudo nano /etc/pam.d/login (for console login) $ sudo nano /etc/pam.d/sudo (for sudo authentication)
Add to the files: "auth sufficient pam_poldi.so" (if gmd-password, login and sudo already contains the line "@include common-auth", these conf files need no further adjustment)
When unlocking (screensaver) does not detect the smartcard and can only be unlocked with password instead of pin "pcscd" can be restarted manually to fix this issue
$ sudo service pcscd restart
As this in not possible before login in there seems to be multiple solutions to solve this more structurally, such as:
1) Remove opensc
$ sudo apt remove opensc
2) Add following lines to ~/.gnupg/scdaemon.conf:
disable-ccid pcsc-shared
Automatic screen lock after smartcard removal with Gnome 3: please add working instructions if available.
PKCS#11
Check http://www.scute.org/ if you want to use your OpenPGP card in a PKCS#11 application like Firefox/Iceweasel or Thunderbird/Icedove.
gnupg-pkcs11-scd
Check http://alon.barlev.googlepages.com/gnupg-pkcs11 if you want to use any PKCS#11 provider with GnuPG. You will then NOT use the OpenPGP card but any card supported by a PKCS#11 token like OpenSC.
Further Reading
- Free Software Foundation Europe
- Further links to relevant discussions
License
This document is licensed under the terms of the GNU General Public License (GPL), version 2 or (at your option) any later version.