Installation of Smart Card Software

Damien Sauveron

Associate Professor
University of Limoges

123 avenue Albert Thomas 87060 LIMOGES Cedex FRANCE

<damien.sauveron@unilim.fr>

http://damien.sauveron.fr/

Revision History
Revision 1.203/12/2011DS
Change affiliation.
Revision 1.104/01/2004DS
Improve the presentation of the document.
Revision 1.003/10/2003DS
First version.

Abstract

The installation and the usage of some Smart Card software is a complex job. This document could help you to set up an environment in order to take a good way for the Smart Card's world.

Table of Contents

Introduction
Greetings
PC/SC Lite and drivers
Install of PC/SC Lite
Install of SERIAL readers
Gemplus GCR410
SmartMouse SM1 RS232
TOWITOKO CHIPDRIVE extern 320
Install of USB readers
Generic CCID readers
SCM Microsystems SCR 331
TOWITOKO CHIPDRIVE extern 330
OMNIKEY CardMan 2020
Install of PCMCIA readers
Gemplus GPR400
SCM SCR241
Install of libusb
Installation of the JDKs
SUN JDK 1.2.2
SUN JDK 1.3.1
IBM JDK 1.3.1
Installation of fonts
Installation of the communication APIs
Installation of the Java Card Development Kits
JCDK 2.1.1
JCDK 2.1.2
JCDK 2.2
Installation of the GemXpresso RAD III kit
Installation of the OpenCard Framework
Installation of the OCF to PC/SC bridge
Installation of JPCSC 0.7.2
Installation of the JCOP 2.1 kit
Installation of the OpenSC
Installation of the Muscle Framework
Muscle Applications
muscleTools
XCardII
Muscle Plugins
MCardPlugin
FAQ
References

Introduction

I have written this document in order to share my experience on usage of Smart Card on a Linux environment (Slackware 8.1™). I hope this will help you to cope with the installation and using problems. This document describes the installation of:

  • PC/SC Lite and some drivers;

  • many Java Development Kits and Java Card Development Kits;

  • OpenCard Framework (OCF), OCF to PC/SC bridge, GemXpresso RAD3;

  • JPCSC library and JCOP Tools.

Note

For many operations you must have the root privileges on the host.

Greetings

Thanks for all the volunteers who work on the development of PC/SC Lite, free drivers, Muscle, etc. I don't forget all the people who answer on Muscle and other mailing list, newgroups, etc.

PC/SC Lite and drivers

Install of PC/SC Lite

Download the last version of PC/SC Lite [PCSCLite]. 

user% tar xvzf pcsc-lite-x.y.z.tar.gz
user% cd pcsc-lite-x.y.z

If you want use USB readers you must use the --enable_libusb. Libusb is a portable API available on many OS for usage of USB. If libusb is not installed on your system, install it. 

user% ./configure --enable-libusb=/usr/local --enable-daemon --enable-debug --enable-threadsafe --prefix=/usr/local/pcsc --sysconfdir=/etc --enable-runpid=/var/run/pcscd.pid

Note

/usr/local is my path for my libusb install.

Note

The --enable_threadsafe implies to compile the clients of the PC/SC middleware with -lpthread for using the pthread library.

Compile PC/SC Lite. 

user% make

Get the root privileges and install it. 

root% make install
root% echo "/usr/local/pcsc/lib" >> /etc/ld.so.conf
root% ldconfig
root% mkdir /dev/pcsc
root% mkdir /usr/local/pcsc/drivers
root% echo "/usr/local/pcsc/sbin/pcscd" >> /etc/rc.d/rc.local

Note

For security reasons we should create a special account with the good privileges to start the daemon.

You can test:

  • PC/SC Lite installation and the SCard API with the tool testpcsc in src/

  • MuscleCard Framework API with the tool muscletest in src/

Install of SERIAL readers

Your kernel or one of its module must manage the serial port.

Get the root privileges. 

root% cd /dev/pcsc
root% ln -s ../ttyS0 1 (if you connect the reader on the COM1)
root% cd /usr/local/pcsc/drivers

Gemplus GCR410

Download the last version of ifd-gempc-x.y.z.tar.gz [RousseauWeb]. 

root% tar xvzf ifd-gempc-x.y.z.tar.gz
root% cd /usr/local/pcsc/drivers/ifd-gempc-x.y.z/GemPC410
Modify the INCS in Makefile with the path where you have installed the PC/SC Lite include files: 
INCS = -I/usr/local/pcsc/include
				
root% make
Add in /etc/reader.conf the following entry: 
FRIENDLYNAME "Gemplus GemPC410 Reader"
DEVICENAME GEMCORE
LIBPATH /usr/local/pcsc/drivers/ifd-gempc-x.y.z/GemPC410/libGemPC410.so
CHANNELID 1

SmartMouse SM1 RS232

Download ifd-sm-x.y.z.tar.gz [SauveronWeb] 

root% tar xvzf ifd-sm-x.y.z.tar.gz
root% cd ifd-sm-x.y.z
root% make
Add in /etc/reader.conf the following entry: 
FRIENDLYNAME "SM1 Reader"
DEVICENAME SM1
LIBPATH /usr/local/pcsc/drivers/ifd-sm-x.y.z/libsm_ifd.so
CHANNELID 1

TOWITOKO CHIPDRIVE extern 320

Download towitoko-x.y.z.tar.gz 

user% tar xzvf towitokox.y.z.tar.gz
user% cd towitokox.y.z
user% ./configure --prefix=/usr/local/pcsc/drivers/towitoko --enable-usb-bundle --with-pcsc-lite-dir=/usr/local/pcsc
user% make
user% make check
Get the root privileges. 
root% make install
Add in /etc/reader.conf the following entry: 
FRIENDLYNAME "TOWITOKO CHIPDRIVE extern 320"
DEVICENAME CHIPDRIVE320
LIBPATH /usr/local/pcsc/drivers/towitoko/lib/libtowitoko.so
CHANNELID 1

Install of USB readers

Your kernel or one of its module must handle the USB. For me: 

root% modprobe usbcore
root% modprobe usb-uhci irq 11
root% mount -t usbdevfs none /proc/bus/usb

Generic CCID readers

Download ccid-x.y.z.tar.gz [PCSCLite]. This driver needs libusb (cf. the libusb section). 

user% tar xvzf ccid-x.y.z.tar.gz
user% cd ccid-x.y.z
user% ./configure --enable-libusb=/usr/local/
user% make
Get the root privileges. 
root% make install

SCM Microsystems SCR 331

Plug your reader and get the informations with lsusb -v or cat /proc/bus/usb/devices If you obtain for the SCR331 an idProduct's value equal to 0xe000, you must upgrade the firmware explained in the following procedure. Else if you obtain 0xe001 you must choose to use the generic CCID driver (cf. section Generic CCID readers) or install the SCM driver as described at the end of this section.

Procedure 1. Upgrade the firmware

The firmware in the USB reader can be updated to the latest version, which should work with the GNU/Linux driver on SCM's web site:

  1. Find a windows machine (an unfortunate necessity)

  2. Download and install the SCRx31_USB_1.40_signed.zip windows driver from http://www.scmmicro.com/security/secureCard-downloads.html (Click on the SCR331 PCSC link.) Personally I use SCR331 Installer V2.05.zip.

  3. Download the USB-FWUpdate.zip program.

  4. Download the new firmware (SCRx31_Firmware_4.13.zip).

  5. Run the USB-FWUpdate program and select the .bin file from the firmware package.

  6. Now the USB reader should be upgraded to the CCID version.

  7. Throw your windows system away and plug the reader into your GNU/Linux box. Now lsusb -v or cat /proc/bus/usb/devices shall give an idProduct set up at 0xe001.

Install the GNU/Linux driver from ftp://ftp.scmmicro.com/security/drivers/scr331ccidDriver-0.9.0-1.i386.rpm On my Slackware, I converted the rpm to a tgz file using rpm2tgz 

tar xvzf scr331ccidDriver-0.9.0-1.i386.tgz
Get the root privileges and move the driver to /usr/local/pcsc/drivers/

TOWITOKO CHIPDRIVE extern 330

Download towitoko-x.y.z.tar.gz 

user% tar xzvf towitokox.y.z.tar.gz
user% cd towitokox.y.z
user% ./configure --prefix=/usr/local/pcsc/drivers/towitoko --enable-usb-bundle --with-pcsc-lite-dir=/usr/local/pcsc
user% make
user% make check
Get the root privileges. 
root% make install

OMNIKEY CardMan 2020

user% tar xzvf cm2020_installer_vX_Y_Z_src.tar.gz
user% cd cm2020_installer_vX_Y_Z_src
Get the root privileges. 
root% sh install

Install of PCMCIA readers

Gemplus GPR400

1) Installation of the module for the pcmcia card GRP400: This is necessary to handle the PCMCIA. Download the sources of the pcmcia-cs [PCMCIA-CS] 

user% tar xvzf pcmcia-cs-3.1.34.tar.gz
Download the module for the GPR400 [????] Following the README of gpr400_cs-0.9.6.tar.gz i.e: 
user% cd pcmcia-cs-3.1.34
user% tar xvzf gpr400_cs-0.9.6.tar.gz
Change the value of #define PCMCIA_DEBUG from 1 to 0 in the gpr400_cs.c 
user% make config
user% make all
Get the root privileges. 
root% make install
root% mknod /dev/gpr400 c 123 0
root% chmod 0666 /dev/gpr400
2) Installation of the GPR400 PC/SC driver: Download the source ifd-gpr400-0.3.tar.gz [????] Get the root privileges. 
root% cd /dev/pcsc
root% ln -s ../gpr400 5
root% cd /usr/local/pcsc/drivers
root% tar xvzf ifd-gpr400-0.3.tar.gz
root% cd ifd-gpr400-0.3
Add at the beginning of the CFLAGS -I/usr/local/pcsc/include in the Makefile Comment in the pcscdefines.h file the following lines: 
/*
	typedef unsigned long      DWORD;
	typedef unsigned long*     PDWORD;
	typedef unsigned char      UCHAR;
	typedef unsigned char*     PUCHAR;
	typedef char*              LPSTR;
	typedef long               RESPONSECODE;
*/
Copy ifdhandler.h from ifd-devkit-1.0.0.tar.gz or from an old version of pcsc-lite (for instance 1.0.1) in the directory. make Add in /etc/reader.conf the following entry: 
FRIENDLYNAME      "Gemplus GPR400 Reader"
DEVICENAME        GPR400
LIBPATH           /usr/local/pcsc/drivers/ifd-gpr400-0.3/libgpr400_ifd.so
CHANNELID         5

Note

I have submitted a modified version of this driver to Joe Phillips.

SCM SCR241

TO DO!

Install of libusb

Download libusb-0.1.7.tar.gz [LibUSB]. 

user% tar xvzf libusb-0.1.7.tar.gz
user% cd libusb-0.1.7
user% ./configure
user% make
Get the root privileges. 
root% make install

Installation of the JDKs

Download the JDKs.

Note

Do some scripts to set up the environment.

SUN JDK 1.2.2

Get the root privileges. 

root% cd /usr/local
root% tar xvzf jdk-1_2_2_011-linux-i386.tar.gz

SUN JDK 1.3.1

Get the root privileges. 

root% cd /usr/local
root% tar xvzf j2sdk-1_3_1_04-linux-i586.bin

IBM JDK 1.3.1

Get the root privileges. 

root% cd /usr/local
root% tar xvzf IBMJava2-SDK-131-linux.tgz

Installation of fonts

For the SUN JDK 1.2.2 and the SUN JDK 1.3.1 Download symbol.ttf Get the root privileges. 

root% cp symbol.ttf $JAVA_HOME/jre/lib/fonts/
Add to the file $JAVA_HOME/jre/lib/fonts/fonts.dir the following line symbol.ttf -urw-symbol-medium-r-normal--0-0-0-0-p-0-adobe-fontspecific and modify the number of fonts at the beginning of the file (adding 1).

Installation of the communication APIs

Get on the Gemplus CD of GemXPresso RADIII the linux_commapi_conf.tar 

user% tar xvf linux_commapi_conf.tar
Get the root privileges. 
root% cp comm.jar $JAVA_HOME/jre/lib/ext/
root% cp javax.comm.properties $JAVA_HOME/jre/lib/
root% cp jcl.jar $JAVA_HOME/jre/lib/ext/
* For the SUN JDK 
root% cp libSerial.so $JAVA_HOME/jre/lib/i386/
root% cp libParallel.so $JAVA_HOME/jre/lib/i386/
* For the IBM JDK 
root% cp libSerial.so $JAVA_HOME/jre/lib/ext/
root% cp libParallel.so $JAVA_HOME/jre/lib/ext/

Note

For using the serial port the user must have the rights rw on it. As root do root% chmod 666 /dev/ttyS?

Installation of the Java Card Development Kits

Download the JCDKs. Get the root privileges. 

root% cd /usr/local
root% mkdir javacard
root% cd javacard

Note

Do some scripts to set up the environment.

JCDK 2.1.1

root% tar xvzf java_card_kit-2_1_1-unix[1].tar.Z
root% mv jc211 java_card_kit-2_1_1

JCDK 2.1.2

root% unzip java_card_kit-2_1_2-solsparc.zip

JCDK 2.2

root% unzip java_card_kit-2_2-solsparc-gl.zip

Installation of the GemXpresso RAD III kit

The install does not work with the JDK 1.2.2 Get the root privileges mount the 'cdrom' with the GemXPresso RAD III CD. cd 'cdrom'/Unix I have chosen to install the different components in /opt/gemxpresso.rad3/ To install the RAD III: 

root% ./RAD3_INS.bin
To install the card profiles: 
root% ./CP_V1.bin
root% ./CP_V2.bin
root% ./CP_PK.bin
To install the crypto: 
root% ./FPK_SP.bin
To install the OpenCard Framework: 
root% ./OCF_INS.bin
If needed modify the JAVA_HOME in /opt/gemxpresso.rad3/bin/GxpRADInit.sh. For using the GemXpresso RAD III with bash:

  • if you wish using the communication APIs installed by yourself do 

    user% export RAD_HOME=/opt/gemxpresso.rad3

  • if you choose to use the APIs installed by the kit do 

    user% source /etc/gxp_rad_profile

Do some scripts to set up the environment. Put the rights rw on the device's filename of the OCF reader.

Note

For using PC/SC with the OCF to PCSC bridge, it is not necessary to have the rights on the device because the pcscd daemon runs with the rights allowing the access.

I have chosen to use my readers on PC/SC and an OCF to PC/SC brigde because most of my readers work with PC/SC and only one with OCF (the GCR410).

Installation of the OpenCard Framework

The installOCF.class provided by [OCF] does not work on my Linux. Get the root privileges. 

root% /usr/local/
root% ln -s /opt/gemxpresso.rad3/Ocf1.2/ ocf
Create a file opencard.properties in the directory $JAVA_HOME/jre/lib/ Do some scripts to set up the environment (put the .jar in the CLASSPATH)

Installation of the OCF to PC/SC bridge

Download OCFPCSC1-0.0.1.tar.gz [MUSCLE]. Contrary to this is written in the documentation it is possible to have more than one reader in the /etc/readers.conf 

user% tar xvzf OCFPCSC1-0.0.1.tar.gz
user% cd OCFPCSC1-0.0.1
Modify the Makefile 
JDK_HOME = /usr/local/jdk1.2.2
PCSC_HDRS = -I/usr/local/pcsc/include
PCSC_LIBS = -L/usr/local/pcsc/lib -lpcsclite -lpthread
INCLUDE = -I$(JDK_HOME)/include -I$(JDK_HOME)/include/linux $(PCSC_HDRS)

user% make
Get the root privileges. 
root% make install
For using the bridge, put libOCFPCSC1.so in your LD_LIBRARY_PATH Modify the opencard.properties files involved with the line: 
OpenCard.terminals = com.ibm.opencard.terminal.pcsc10.Pcsc10CardTerminalFactory
In order to using the readers with the GemXpresso RAD III and the OCF to PC/SC brigde put in the file opencard.properties in the directory /opt/gemxpresso.rad3/conf: 
OpenCard.terminals = com.ibm.opencard.terminal.pcsc10.Pcsc10CardTerminalFactory
Modify the CLASSPATH in the file /opt/gemxpresso.rad3/bin/GxpRADInit.sh in the way that follows: 
# I set OCF_LIB
OCF_LIB=$RAD_HOME/Ocf1.2/lib

# ======================== OCF =============================
	CLASSPATH=\$CLASSPATH\
:$RAD_LIB/base-core.jar\
:$RAD_LIB/base-opt.jar\
:$RAD_LIB/pcsc_wrapper.jar\
:$OCF_LIB/reference-terminals-windows.jar\
	export CLASSPATH

Installation of JPCSC 0.7.2

user% unzip jpcsc-72.zip
user% cd jpcsc
user% make
Get the root privileges. 
root% make install
If the line "/usr/local/pcsc/lib" doesn't exist in /etc/ld.so.conf add it. 
root% echo "/usr/local/pcsc/lib" >> /etc/ld.so.conf
root% ldconfig
For using it, put jpcsc.jar in CLASSPATH et libjpcsc.so in the LD_LIBRARY_PATH

Installation of the JCOP 2.1 kit

Get the root privileges. 

root% cd /opt tar xvzf jctools-2.1-linux.tgz
root% cd /opt/jctools-2.1-linux/etc/ide
root% chmod 666 classtemplate.txt
root% chmod 666 classheader.txt
root% chmod 666 scriptheader.txt
root% chmod 666 methodheader.txt
root% chmod 666 fieldheader.txt
Do some scripts to set up the environment. For using the examples the user must copy them in an own directory.

Installation of the OpenSC

Download opensc-x.y.z.tar.gz [OpenSC]. 

user% tar xvzf opensc-x.y.z.tar.gz
user% ./configure --prefix=/usr/local/opensc --with-pcsclite=/usr/local/pcsc
user% make

Installation of the Muscle Framework

TO DO!

Muscle Applications

TO DO!

muscleTools

Download the last version of muscleTools. 

user% tar xvzf muscleTools-x.y.z.tar.gz
user% cd muscleTools-x.y.z
Modify the Makefile with the good paths for the library and the include files related to musclecard. For me as: 
	CFLAGS = -g -Wall -I/usr/local/pcsc/include
	LIBS = -L/usr/local/pcsc/lib -lmusclecard -lpthread
	
user% make
Get the root privileges. 
root% make install

XCardII

Download the last version of XCardII. 

user% tar xvzf XCardII-x.y.z.tar.gz
user% cd XCardII-x.y.z
user% cd src
Modify the Makefile with the good paths for the library and the include files related to qt, musclecard and pthread. 
user% make
Get the root privileges. 
root% make install

Muscle Plugins

The plugin are used by the muscle framework to manage the different cards. For example the MCardPlugin is used to handle a Java Card using the MCardApplet and the CFlexPlugin is used for the Cryptoflex card.

MCardPlugin

Download the last version of MCardPlugin. 

user% export CPPFLAGS=-I/usr/local/pcsc/include
user% export LDFLAGS=-I/usr/local/pcsc/include
user% ./configure
user% make
Get the root privileges. 
root% ./installBundle

Note

root% make install is useless.

FAQ

1. What are the informations needed to obtain a quick and efficient response for a post on the mailing list?
2. Why does pcsc-lite fail to communicate with the serial port?
1.

What are the informations needed to obtain a quick and efficient response for a post on the mailing list?

Join the informations about your hardware and software system:

  • OS: uname -a

  • version of PC/SC Lite

  • readers used

  • version of the drivers used

  • cards used

  • softwares used

Join also the logs obtained with: pcscd --apdu --foreground

2.

Why does pcsc-lite fail to communicate with the serial port?

Be sure that /dev/pcsc/1 is a link to /dev/ttyS0 and not to /dev/ttys0.

References

[PCSCLite] PC/SC Lite. http://alioth.debian.org/projects/pcsclite/.

[MUSCLE] MUSCLE. http://www.linuxnet.com/.

[SauveronWeb] Driver for SM1. http://damien.sauveron.free.fr/.

[RousseauWeb] GemCore based PC/SC reader drivers. http://ludovic.rousseau.free.fr/softwares/ifd-GemPC/.

[JPC/SC] The JPC/SC specifications and driver. http://www.linuxnet.com/middleware/.

[OCF] OpenCard Framework. http://www.opencard.org/.

[PCSCSpec] PC/SC Specifications. http://www.pcscworkgroup.com/.

[CCIDSpec] Chip/Smart Card Interface Devices (CCID). http://www.usb.org/developers/.

[LibUSB] The libusb project home. http://libusb.sourceforge.net/.

[PCMCIA-CS] Linux PCMCIA Information Page. http://pcmcia-cs.sourceforge.net/.

[JavaCardSpec] Java Card™ 2.2 Specifications. Sun microsystems. http://java.sun.com/products/javacard/.

[OpenSC] OpenSC. http://www.opensc.org/.

[OpenCT] OpenCT. http://www.opensc.org/.