2.3. Installation of Card Reader

Two standard protocols are used by GnuPG to access card readers.

2.3.1. CCID (Chip Card Interface Description)

The driver to access CCID cards is built into GnuPG. This driver will be used by default.

To use this driver follow the instructions and make sure you have sufficient permission (see below) to access the USB device for reading and writing.

With udev (preferred installation)

First of all, you will need to download two files for udev and copy them to the udev configuration directories, in order to let it identify your card reader:

Now, open a terminal and become root (you will be asked for your root password):

archi@foobar:~ > su -
                

On Ubuntu systems, you should run (and then you will be asked for the user password):

archi@foobar:~ > sudo su -
                

Then you will have to move the files from the directory you have saved them to, to the udev configuration directories:

# cd /home/directory/where/you/saved/the/file (change for the right path)
# cp gnupg-ccid.rules /etc/udev/gnupg-ccid.rules
# cp gnupg-ccid /etc/udev/scripts/gnupg-ccid
# chmod +x /etc/udev/scripts/gnupg-ccid
# ln -s /etc/udev/gnupg-ccid.rules /etc/udev/rules.d/gnupg-ccid.rules
                

All the configuration files are in the right place and with the right permissions by now.

You will now create a group scard, give this group permission to access the smart card reader, and include the users who should have access to the card reader to this group.

# addgroup scard
# addgroup yourusername scard (change for the right username)
# exit (to logout the root user) 
                

With hotplug (deprecated in modern systems)

The described hotplugging mechanism assigns permission for all CCID devices to the users in scard group.

Create the following two files. The first file is a mapping file which decides on the script to run when detecting a CCID device. The second file is the script that should be run if a device with the matching parameters is plugged in. This script is the one to actually assign the permissions.


                        /etc/hotplug/usb/gnupg-ccid.usermap
# The entries below are used to detect CCID devices and run a script
#
# USB_MATCH_VENDOR            0x0001
# USB_MATCH_PRODUCT           0x0002
# USB_MATCH_DEV_LO            0x0004
# USB_MATCH_DEV_HI            0x0008
# USB_MATCH_DEV_CLASS         0x0010
# USB_MATCH_DEV_SUBCLASS      0x0020
# USB_MATCH_DEV_PROTOCOL      0x0040
# USB_MATCH_INT_CLASS         0x0080
# USB_MATCH_INT_SUBCLASS      0x0100
# USB_MATCH_INT_PROTOCOL      0x0200
#
# script   match_flags idVendor idProduct bcdDevice_lo bcdDevice_hi
#          bDeviceClass bDeviceSubClass bDeviceProtocol
#          bInterfaceClass bInterfaceSubClass bInterfaceProtocol driver_info
#
#           flags  V       P     Bcd C S Prot Clas Sub  Prot Info
#
# Generic CCID device
gnupg-ccid  0x0080 0x0    0x0    0x0 0x0 0x0 0x0 0x00 0x0B 0x00 0x00 0x00000000
# SPR532 is CCID but without the proper CCID class
gnupg-ccid  0x0003 0x04e6 0xe003 0x0 0x0 0x0 0x0 0x00 0x0B 0x00 0x00 0x00000000
# SCR33x is CCID but without the proper CCID class
gnupg-ccid  0x0003 0x04e6 0x5115 0x0 0x0 0x0 0x0 0x00 0x0B 0x00 0x00 0x00000000
                    

script states the script that should be run if a device matching the parameters is plugged in via USB.

match_flags is one of the given USB_MATCH_XXX options. The idVendor and the idProduct can be figured out by calling lsusb. The output looks something like this:

archi@foobar:~ > lsusb
Bus 001 Device 009: ID 04e6:5115 SCM Microsystems, Inc.
                   

The values given behind ID are idVendor:idProduct and with a leading 0x could be used in gnupg-ccid.usermap in combination with USB_MATCH_VENDOR or USB_MATCH_PRODUCT.


                        /etc/hotplug/usb/gnupg-ccid
#!/bin/bash
#
# taken from libgphoto2
#
# Sets up newly plugged in card reader so that only members of the
# group can access it

GROUP=scard

# can access it from user space. (Replace scard with the name of the
# group you want to have access to the card reader.)
#
# Note that for this script to work, you'll need all of the following:
# a) a line in the file /etc/hotplug/gnupg-ccid.usermap that corresponds
#    to the card reader you are using.
# b) a group "scard" where all users allowed access to the
#    card reader are listed
# c) a Linux kernel supporting hotplug and usbdevfs
# d) the hotplug package (http://linux-hotplug.sourceforge.net/)
#
# In the usermap file, the first field "usb module" should be named
# "gnupg-ccid" like this script.
#

if [ "${ACTION}" = "add" ] && [ -f "${DEVICE}" ]
then
    chmod o-rwx "${DEVICE}"
    chgrp "${GROUP}" "${DEVICE}"
    chmod g+rw "${DEVICE}"
fi            
                    

This script changes the permissions and the ownership of a USB device under /proc/bus/usb to grant acces to this device to users in the specified group. The group in this example is scard. ACTION and DEVICE are passed via the hotplug mechanism.

Note

Do not forget to run chmod +x on the script.

You should also create the group scard and then add the users to access the card reader to the group. This is done by the following commands: addgroup scard and addgroup <user> scard.

Note

Brian Gough <bjg@network-theory.co.uk> made the following remark: The hotplug package in Debian woody requires all the numbers in gnupg-ccid.usermap to have a 0x prefix otherwise it gives an "unparseable line" error and the i.e. gnupg-ccid 0x0003 0x04e6 0xe003 0x0 0x0 0x0 0x0 0x00 0x0B 0x00 0x00 0x00000000 instead of gnupg-ccid 0x0003 0x04e6 0xe003 0 0 0 0 0x00 0x0B 0x00 0x00 0x00000000. After installing the modified file call update-usb.usermap.

With usbdevfs

Please make sure that you can mount a USB device. This can be achieved by accessing the USB stack via libusb through the usbfs (USB filesystem). If you are using USB < 2.0 the filesystem is called usbdevfs.

To accomplish this goal please add the following line to your /etc/fstab.

                    
                            /etc/fstab
none  /proc/bus/usb  usbfs defaults,user  0 0                        
                        

To make sure that a specific user has read and write access to the USB device add devuid=[user id] to the defaults, user options. With devgid=[group id] access will be granted to the given group.

This approach creates a major security problem. The owner of the files has full permissions to ALL connected USB devices. It does not matter what kind of device is connected. Therefore it is strongly suggested to use the hotplug method.

2.3.2. PC/SC (Personal computer/Smart Card)

TODO

To use PC/SC make sure you disable CCID by passing the --disable-ccid option to GnuPG.

Note

You can easily check your installation by inserting the card in the card reader and entering gpg --card-status (more about this command in Chapter 3, Administrating the Card).