This page documents how to setup and use a OpenPGP smartcard in Debian.

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):

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> addkey

5) 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> keytocard

7) 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

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

2) Enable SSH authentication

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

License

This document is licensed under the terms of the GNU General Public License (GPL), version 2 or (at your option) any later version.


CategoryHardware CategoryOpenPGP