Smartcards: Installing OpenCard on Linux systems, using IBM JDK

Davor Ocelic, docelic@spinlocksolutions.com
SPINLOCK - Advanced Unix-based networks for commercial and education sectors.

Jun 28, 2005.

Obtaining files

Java and Java Communications API

Obtain Java Development Kit (JDK).
IBM Java also offers Java Communications API for download, which is needed by OpenCard.

Following the link above, log in (using your existing or new account) and proceed to IBM SDK download.
You need to download:

IBMJava2-SDK-142.tgz
IBMJava2-JAVACOMM-142.tgz

The IBM Java SDK package also contains the runtime environment, so you do not need the JRE (the Java Runtime Environment) - you need JRE instead of SDK on systems where you will only want to deploy (and not develop) your applications.

OpenCard

Visit opencard.org (their downloads section), then download OCF 1.2 All-in-One package, which is an installable class file (installOCF).

The OpenCard went completely inactive somewhere in 2001, do not use it for new developments.

PC/SC

PC/SC is a "driver" for your smart card reader (terminal). Install PC/SC from your Linux distribution.

OpenCard Framework -> PC/SC Shim (OCFPCSC)

You need the "shim" (layer) which allows OCF to utilize the PC/SC Lite drivers. You can download it from the MUSCLE project, on their middleware download page. Direct download link is http://linuxnet.com/middleware/files/OCFPCSC1-0.0.1.tar.gz.

Installing files

Java and Java Communications API

Since the paths are predefined in the SDK package, you need to create the /opt/ directory on your system and unpack the Java package to it:

mkdir /opt
cd /opt
tar zxf /path/to/IBMJava2-SDK-142.tgz
tar zxf /path/to/IBMJava2-JAVACOMM-142.tgz

Then you need to add Java bin directory to your PATH. This can be done system- or user-wide. System-wide approach:

echo 'export PATH=$PATH:/opt/IBMJava2-142/bin:/opt/IBMJava2-142/jre/bin' >> /etc/profile

To apply changes, either completely log out and log back in, or do . /etc/profile in the current shell to update PATH.

To test the installation, do:

java -version

The Communications API is used for opening parallel and/or serial ports. Since we will only use serial ports (USB smart card readers will also appear as serial), the Comm API notes mention that you need to give proper permission to users on /dev/ttyS* devices. On Debian, you need to add user to the 'dialout' group; on Ubuntu, this is already done; on generic setups, either manually prepare permissions or, for no fuss and quick setup, choose variant #3 from the below list:

Debian# adduser USERNAME dialout
Ubuntu# (nothing)
Generic-linux# chmod 666 /dev/ttyS{1,2,3,4}

Regardless of the above device permissions, you need to slightly adjust the javax.comm.properties file, if you use the USB smart card reader. You need to open /opt/IBMJava2-142/jre/lib/javax.comm.properties and uncomment the last line that says:

/dev/ttyUSB=PORT_SERIAL

OpenCard

Make the root user source /etc/profile (directly, by running . /etc/profile) - to get Java in PATH - then execute java installOCF.

For the installation path, pick /opt/OpenCard/.
The installation procedure asks to build the basic opencard.properties file. Towitoko ChipDrive Micro (USB) smartcard readers (terminals) should use "PC/SC Card Terminal interface" from the menu.
The location of the opencard.properties file should be left in JAVA_HOME/jre/lib/, which is already the default.

At this point, you are presented with a picture of OpenCard consortium members, and the installation begins.
In the end, you are asked to view the README file, which isn't there, but supposedly the procedure is done.

Now you need to create symbolic links to OpenCard *.jar files from the Java space:

cd /opt/IBMJava2-142/jre/lib/ext
for p in `find /opt/OpenCard -name '*.jar'`; do ln -s $p; done

To catch the problem before it happens, execute export | grep -E 'LANG|LC' and see if any of the (one or two) variables shown contains "UTF-8". If it does, simply redefine it, omitting .UTF-8:

$ export | grep -E 'LANG|LC'
declare -x LANG="en_US.UTF-8"
declare -x LANGUAGE="en_HR:en"

$ export LANG=en_US

(UTF-8 setting is re-initialized each time you open a terminal, so make sure you modify appropriate system config files for a permanent solution - /etc/profile for example).

PC/SC

This is where you need to get your smart card terminal running. If it is an USB device, you will need USB host support, usb->serial, and a specific driver. In case of Towitoko chipdrive micro on USB, the kernel modules to load are usbserial and pl2303. When you connect the reader, device /dev/ttyUSB0 will be created.

On Debian GNU, pc/sc-related packages are called libpcsclite1, libusb-0.1-4, pcscd, libccid and libtowitoko2.
When you install all of this, ending with libtowitoko2, the smart card reader (terminal) should light its LED (if it has one) when any smart card is inserted.

(USB card terminals do not require manual setup; for serial devices /etc/reader.conf needs to be adjusted).

You also need to install libpcsc-perl and libpcsc-tools for some very great additional tools.

OpenCard Framework -> PC/SC Shim (OCFPCSC)

You need to extract the mentioned tarball, and run make. Before that, you will need to modify the Makefile appropriately (adjust file paths). You can download our modified and compiled OCFPCSC1 package, that both has a Makefile that matches our setup, and has libOCFPCSC1.so library built. In any case, it is strongly advise that you take at least the Makefile from our package and work from there on - it contains small but crucial fixes.

Ideally, you would see if the Makefile suits you, and rebuild the library yourself (by doing make clean all). However, if you have trouble doing so, you can just type make install and have my precompiled version (if it matches your system - Linux x86, gcc 3).

Testing the installation

To see if pcscd is working, inserting and removing card from the chip card reader should turn-on/turn-off the LED on the reader (if any).

Run pcsc_scan, it should detect the terminal, notice card insertions/removals, and print card identification information.

Run java demos.samples.GetCardID, and when you insert the smart card, you should see a CardID displayed through the use of OpenCard Framework!

(If you run the command and get a message about __gxx_personality_v0 being undefined, then you need to replace linker 'ld' in the OCFPCSC Makefile with 'g++' - which would have been done for you if you picked my Makefile as the base).

Enhancing the installation

findOCP tool

findOCP is an useful tool that would be nice to install - it prints the locations where opencard.properties files are looked for. If java demos.tools.findOCP doesn't work, then save the following content as findOCP.java:

import java.io.File;
import java.util.Properties;

public class findOCP {
    public static void main(String[] argv) {
        final String sep = File.separator;
        Properties props = System.getProperties();
        String JavaHome  = props.getProperty("java.home");
        String UserHome  = props.getProperty("user.home");
        String UserDir   = props.getProperty("user.dir");
        System.out.println("Looking for OpenCard Properties file in:\n\t" 
                           + JavaHome + sep + "lib" + sep 
                           + "opencard.properties\n\t"
                           + UserHome + sep + ".opencard.properties\n\t"
                           + UserDir  + sep + "opencard.properties\n\t"
                           + UserDir  + sep + ".opencard.properties\n");
 }
}

Compile and install:

javac findOCP.java
jar cvf findOCP.jar findOCP.class
cp -i findOCP.jar /opt/IBMJava2-142/java/jre/lib/ext

To run, then just run java findOCP.

That's it.

SPINLOCK - Advanced Unix-based networks for commercial and education sectors.