SpringCard NetPCSC for PCSC-Lite

Introduction

In 2016, SpringCard introduces a new family of network-attached NFC/RFID couplers, providing PC/SC functionnality on top of TCP/IP. The family is built from the SpringCard E663 module, the Ethernet-world counterpart of H663 (for USB world) and K663 (for serial world). The two first products of the family are the TwistyWriter-IP PC/SC, made for OEMs, and the FunkyGate-IP PC/SC, targetting access-control applications. The second one is also available as a FunkyGate-IP+POE PC/SC, where ‘POE’ stands for ‘power-over-Ethernet’, i.e. the device takes its power from the network cable.

To support all the devices based on the E663 module, SpringCard has developed from scratch a PC/SC driver for Windows (see this page). For the UNIX world, SpringCard provides a fork of the PCSC-Lite’s CCID driver maintained by Ludovic Rousseau. This page explains how-to install and use this driver, code-named ‘NetPCSC for PCSC-Lite’.

Not yet familiar with PC/SC or PCSC-Lite?

PC/SC is the de-facto standard to interface Personal Computers with Smart Cards (and smartcard readers of course). Even if PC/SC has been initially promoted by Microsoft -and has been implemented for long in Windows-, the standard is not limited to MS’ operating systems.

PCSC-Lite is an open source implementation of PC/SC, part of a global project named MUSCLE (Movement for the Use of Smart Cards in a Linux Environment). Despite its name, the PC/SC stack offered by MUSCLE is not limited to GNU/Linux anymore. Their compatibility list now includes other popular UNIXes, including Apple Mac OS X and Solaris.

Supported operating systems

SpringCard develops and runs the tests of the NetPCSC for PCSC-Lite package on Ubuntu 14.04 LTS. You are free -and welcomed- to use the package on other machines. Don’t hesitate to send us your feedback through our contact page (choose ‘Technical support’).

Disclaimer and warning – and an acknowledgement!

The NetPCSC for PCSC-Lite package is provided free-of-charge and without any warranty (see licence below). SpringCard team will make their best effort to support you if you need help installing and using the package, but complex cases or subjects that can’t be investigated on our reference platform (Ubutu 14.04 LTS) will have to go through paid-consultancy service.

There’s no relationship between SpringCard and all the developers involved either in the open source PCSC-Lite project or in the original CCID driver for PCSC-Lite (and supporting mostly USB readers). Apart from this explanation page, SpringCard can’t provide any technical support related to PCSC-Lite middleware nor PCSC-Lite CCID driver. To get support, submit a bug or volunteer to join the project, please visit the project’s home page.

SpringCard would’t write this disclaimer without thanking these guys: their great job brings you -and all of us- the hidden bricks that makes it possible to work with smart cards readers in a UNIX environment.

Licence

As a derived work from the CCID driver for PCSC-Lite, NetPCSC for PCSC-Lite is published under the LGPL licence.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

The complete licence is available at GNU Lesser General Public License, version 2.1

Ready?

OK, enough wording, now the technical part.

Download and installation

Prerequisites

Uninstall any previous version of PCSC-Lite

It is possible to use the tools apt-get, yum … to download and install PCSC-Lite as any other standard package. However, we must make sure that you have the last version of PCSC-Lite, complete with all the files required to compile SpringCard NetPCSC for PCSC-Lite. Therefore, you must use your package manager to uninstall any previous version of PCSC-Lite, before downloading and compiling an up-to-date -and clean- version.

Install the dependencies

You need to install the following packages:

  • build-essential.
  • Libudev-dev.
  • Libusb-1.0-0-dev.
  • Libusb-dev.
  • pkg-config

Note: it is possible to use the tools apt-get, yum … to download and to install these packages.

Download

Download PCSC-Lite

Visit PCSC-Lite download page https://alioth.debian.org/frs/?group_id=30105#title_pcsclite and pick-up the latest version of pcsclite.

This is a .tar.bz2 archive. Save it in a directory where you will be able to uncompress the archive and build the binaries. In the screenshots below, we’re working with version 1.8.13 of pcsclite.

Download pcsc-tools

Ludovic Rousseau has developed a set of utilities to get started with PCSC-Lite -and a PC/SC reader-. We’ll use pcsc_scan, which is supplied in the pcsc-tools archive.

Visit http://ludovic.rousseau.free.fr/softwares/pcsc-tools/ and pick-up the latest version of pcsc-tools.

This is a .tar.gz archive. Save it in the same directory. In the screenshots below, we’re working with version 1.4.26 of pcsc-tools.

Download SpringCard NetPCSC for PCSC-Lite

The SpringCard NetPCSC for PCSC-Lite project is hosted on GitHub: https://github.com/springcard/springcard-ccid-tcp

You may download the complete source code using git clone, or get a zip archive here: https://github.com/springcard/springcard-ccid-tcp/archive/master.zip

Compile and install

Uncompress all the archives

 tar xjf pcsc-lite-1.8.13.tar.bz2
 tar xzf pcsc-tools-1.4.26.tar.gz
 unzip springcard-ccid-tcp-master.zip

 Compile and install PCSC-Lite

  • Open a terminal.
  • Go to the directory where you have uncompressed PCSC-Lite.
  • Enter the commands:
 cd pcsc-lite-1.8.13/
 ./bootstrap
 ./configure
 make
 sudo make install
  • Create a symbolic link for libpcsclite library. As we have removed original pcsclite from the system, we have to add a link to set the pcsc-lite library path.
 sudo ln -s /usr/local/lib/libpcsclite.so.1.0.0 /lib/libpcsclite.so.1

Daemon pcscd is installed into /usr/local/sbin directory.

Configuration file for reader is installed into /usr/local/etc/reader.conf.d file.

PCSCLite library is installed into /usr/local/lib directory.

Notes

You can use ./configure –prefix=/opt/pcsc if you wish to use another base directory for CCID driver. It can allows you to separate CCID USB,TwinSerie driver from SpringCard TCP driver.

If the configure step fails with message error ‘usb.h not found’,  please could you check that you have the libusb library installed. If needed, please install it, and then give the path to this library to the configuration script: ./configure LIBUSB_CFLAGS=….

On Ubuntu or Debian, you may alternatively use apt-get to download and install the libusb-dev package :

 apt-get install libusb-dev

Update library path – make use of our new library:

 rm /usr/lib/arm-linux-gnueabihf/libpcsclite.so.1 (only on Raspbian)
 rm /lib/libpcsclite.so.1
 ln -s /opt/pcsc/lib/libpcsclite.so.1.0.0 /lib/libpcsclite.so.1

Compile and install SpringCard NetPCSC for PCSC-Lite

  • Open a terminal.
  • Go to the directory where you have uncompressed Springcard-ccid-tcp-X.Y.Z.
  • Enter the commands :
 cd springcard-ccid-tcp-master/
 ./configure
 make
 sudo make install

Compile and install pcsc-tools

  • Open a terminal.
  • Go to the directory where you have uncompressed the pcsc-tools archive.
  • Enter the commands :
 cd ../pcsc-tools-1.4.23/
 make
 sudo make install

Tools are installed into /usr/local/bin directory.

You can use ‘export PKG_CONFIG_PATH=/opt/pcsc/lib/pkgconfig‘ if you wish to use another base directory for CCID driver. It allows you to separate CCID USB, TwinSerie driver from SpringCard TCP driver.

Configuring a NetPCSC reader

Why not plug’n’play?

When you use the standard CCID driver with a plain-old USB-attached reader, there’s nothing to configure: attach the reader to the computer, the kernel looks for a suitable driver, and everything is ok.

But when we come to a network-attached reader, there’s no direct connection between the reader and the computer, so nobody could tell the kernel there’s something to do. More than that, if a computer automatically try to activate a driver for any NetPCSC reader it founds on the network, it means that if there are 2 computers (or more) on the network, they will fight to take control of the reader.

To keep things simple and reliable, the NetPCSC reader is a TCP server, and to be able to use it, the NetPCSC driver must be explicitely configured with the IP address of the reader. Make sure that you don’t configure the same reader on more than one computer.

Setting the reader’s IP address

Today, there’s no Linux-based tool to set the IP address of the E663-based readers. You must use SpringCard NDDU (Network Device Discovery Utility) running on Windows to set the IP address of your reader(s), or to retrive the actual IP address of the readers configured as DHCP client.

Latest version of NDDU is here: http://www.springcard.com/en/download/find/file/sn13210

Modify configuration files

  • Open the file /usr/local/etc/reader.conf.d.
  • You must create one configuration entry per E663 reader.

padding-left: 30px;">Each configuration must have those parameters:

  1. FRIENDLYNAME: a (near)human readable string describing the reader. This is the name that will be returned by SCardListReaders.
  2. DEVICENAME: a colon-separated string containing network informations about your reader (IP:PORT:OPTION BYTE:KEY):
  3. IP : your device IP address.
    • PORT : tcp port used to contact the reader.
    • OPTION BYTE : communication options (device dependant), must be ’00’ for current version of the driver.
    • KEY : depending on OPTION BYTE, must be ‘nokey’ for current version of the driver
  4. LIBPATH : full path to the PCSC over Network Driver library file

 Linux_2

Validation the configuration with PCSC-Lite daemon in debug mode

PCSC-Lite’s pcscd process must be running under an elevated user (root for example).
You can launch pcscd into debug mode to see some error messages : pcscd -fd

sudo /usr/local/sbin/pcscd -fd

Linux_3

Linux_4

Using NetPCSC

Configure PCSC-Lite to start automatically

It is better to have pcscd automatically started when the computer starts. To do so, you must add pcscd in the list of processes started in rc.local or equivalent startup script.
Please see the Ludovic Rousseau blog to see how to set pcscd running at startup.

Run pcsc_scan tests application

This tool is provided with the pcsc-tools package. You can run it like below.

/usr/local/bin/pcsc_scan

Linux_5

Developing with E663-based readers on top of PC/SC

Well, the magic behind PC/SC is that you don’t need to worry whether your reader is a NetPCSC or a more classical USB-attached device, on the developer’s point of view, it’s all the same. If you’re not familiar with PC/SC-development, please visit our page on the subject.