/dev/posts/

Using a Kap&Link smart card reader with CPS3 smart cards on Linux

Published:

Updated:

Tutorial on how to get Carte Professionnel de Santé 3 (CPS3) smart cards work with Firefox under Linux with a Kap&Link smart card reader. It has some information to understand the related lingo, how the different components interact and how you might try to enable support for a PC/SC (Personal computer/Smart Card) / CCID (Chip/Smart Card Interface Devices) smart card reader which is not supported by the driver.

Tested with:

Table of content

Overview

My goal is to use a CPS smart card (French CPS3 card) using a smart card reader (Kap&Link) with my browser (Firefox).

We need mostly two things:

What had to be done:

  1. upgrade the firmware of the smart card reader (needed in order for the device to be compatible with PC/SC / CCID);
  2. switch the smart card reader to PC/SC mode;
  3. install the pcscd daemon and the libccid driver (driver for CCID-based smart card readers);
  4. patch a XML file of the CCID driver in order to add support for this specific model of smart card reader which was not supported by the driver (merged in CID 1.5.2);
  5. download the CPS PKCS#11 driver (driver for the CPS card);
  6. register the CPS PKCS#11 driver in Firefox.

What must not be done:

What need not be done (but could still be useful):

Explanation

Concepts

Integrated Circuit Cards (ICC)

smart/chip card (or similar).

ICC-IFD (Interface Device)

a smart card reader (or similar)

PC/SC (Personal computer/Smart Card)

An architecture for communicating with smart card readers which icludes a Windows-oriented API (WinScard).

On Linux, this is implemented by PC/SC-lite which is made of a system-wide daemon (pcscd) and a library which communicates with this daemon (over the /var/run/pcscd/pcscd.comm UNIX socket). The library implements the WinSCard API. PC/SC-lite has support for several types of smart card readers: the daemon can load drivers (IFD handlers) for different types of smart card readers.

CCID

a standard USB protocol for communicating with smart card readers.

The CCID free software driver implement support for CCID smart card readers in PC/SC-lite.

PKCS#11 (aka Cryptoki)

an API used by applications for communicating with cryptographic tokens (which might be smart cards or other things).

In practice, this API is implemented as shared libraries (smart card drivers) which are dynamically loaded in the application.

Workflow

In this case, the workflow works as follows:

  1. the application (Firefox) loads the PKCS#11 driver (CPS PKCS#11 driver) which is a shared library (.so, in this case libcps3_pkcs11_lux.so) which implements the PKCS#11 API for the smart card;
  2. the application uses this driver to execute (public-key) cryptography operations (in my case a digital signature used in the TLS handshake) on the smart card;
  3. the PKCS#11 driver uses the PC/SC-lite API to communicate with the smart card reader;
  4. the PC/SC library communicates to the pcscd daemon;
  5. the PC/SC daemon delagates to the card reader driver (libccid for CCID smart card readers) which is a shared library (.so) loaded in pcscd;
  6. the smart card reader driver communicates with the smart card reader (over USB);
  7. the smart card reader communicates with the smart card.
Application talking to a smartcard using a PKCS#11 driver and PC/SC-lite

Steps

Enable PC/SC mode on the smart card reader

The smart card reader I used could operate in two modes/protocols:

We need to enable the new standard “PC/SC” mode. This is be done on the user interface of the smart card reader: “Menu / Réglages / Lecteur / Mode USB : mode PC/SS”.

Note: firmware update of the Kap&Link

In my case, this option was not available and I had to apply a firmware update:

  1. choose “Link / Mise à jour Logicielle”;
  2. copy the firmward file (.kap) in the USB drive which appears on your computer.

I used the kaplink_04022901_F446.kap firmware (found on the web).

For some reason, one of the two Kap&Link I tried refused to apply the firmware update.

pcscd configuration

Install PC/SC and the CCID driver. On Debian:

sudo apt install pcscd pcsc-tools libccid

At this point, your smart card reader should appear in pcsc_scan:

pcsc_scan

If your smart card reader is found, you can proceed to the the configuration of the application.

Adding support for the smart card reader

In my case, the smart card reader was not recognized by the CCID driver. I had to patch the /usr/lib/pcsc/drivers/ifd-ccid.bundle/Contents/Info.plist in order to ask it to support the device:

<key>ifdVendorID</key>
<array>
  ...
  <string>0x2947</string>
</array>

<key>ifdProductID</key>
<array>
    ...
    <string>0x0101</string>
</array>

<key>ifdFriendlyName</key>
<array>
    ...
    <string>Kap&amp;Link</string>
</array>

The vendor and product ID can be be found with:

$ lsusb
...
Bus 001 Device 024: ID 2947:0101 KAPELSE KAP-LINK
...

This change has been integrated in ccid v1.5.2 so you will not have to do this for Kap&Link readers in the future.

Restart pcscd:

sudo systemctl stop pcscd.service

Now pcsc_scan should find your smart card reader.

Configure Firefox

Download the CPS PKCS#11 driver:

The RPM contains the PKCS#11 driver for the CPS smart card (libcps3_pkcs11_lux.so).

Note: RPM installation

The installation of the RPM failed on my Debian system but you don't actually need to install the package. You can simply extract the required .so file from the RPM.

We need to ask Firefox to load this driver. In Firefox "Preferences / Security Devices", "Load" a new driver and specify the path to libcps3_pkcs11_lux.so.

You should see your smart card reader listed in this interface with:

Warning: OpenSC PKCS#11 driver not supported

Do not load the OpenSC PKCS#11 driver for CPS cards. Firefox freezes if this driver is loaded while you have a CPS card in the smart card reader.

Test

For CPS cards, you can test that everything is working with:

The first website might tell you that you need a Firefox extension:

L'Extension Firefox n'a pas été détectée. Elle est indispensable sous ce navigateur. Après l'installation, veuillez redémarrer votre navigateur.

but this seems to work well enough without it for me.

References