How to make Smart Cards work with Network Station, OCF and USB.

Author: Ed van den Oever - V2R1 experience with Network Station 2800 and 2200.


Motivation

This document describes my experience with Smart Cards (and USB adapters) used with IBM Network Station.
I helped an Italian BP with their Smart Card project, based on the Java Open Card Framework (OCF 1.1.1).
First we made Smart Cards work on the 2800, as that was the product they were using.
After we solved the USB-Serial adapter problem, we were then able to get Smart Cards working on  the 2200 as well.
Many people have asked how I did it. Here is the full story. It is educational to perform the whole build process.
Alternatively jump to the end, and use the quicksmart.zip file provided, to start testing Smart Cards from any drive (including a CD-ROM)

Limitations

There is no general Smart Card hardware/software solution, as drivers are limited to specific Readers, Cards and USB Adapters.
The table below lists the hardware we have tested.
Also, we only used the Java OCF environment up to this point.
I am not aware of any effort to enable Smart Cards with the PC/SC Windows standard in a multi-user (ICA) environment.
 

Hardware/Drivers Tested

 
Network Station 2800 with 64MB Network Station 2200  with 96MB
USB-to-Serial Adapter model  Belkin  F5U003
Thinkpad 770 with 128MB, with optional
USB-to-Serial Adapter model  Belkin  F5U003
Gemplus Card Reader GCR 410
IBM Multi-Function Card (MFC 4.0)
Gemplus Card Reader GCR 410
IBM Multi-Function Card (MFC 4.0)
Gemplus Card Reader GCR 410
IBM Multi-Function Card (MFC 4.0)
NSM V2R1 PTF-2
OCF 1.1.1
Gemplus OCF-driver (jar)
NSM V2R1 PTF-2
OCF 1.1.1
Gemplus OCF-driver (jar)
libibmcomm.so (updated)
Windows 98
Java JVM 1.1.8
javax.comm 2.0
OCF 1.1.1
Gemplus OCF-driver (jar)
USB drivers for Belkin F5U003

Useful URL's

http://www.opencard.org/misc/OCF-FAQ.shtml     How to use Smart Cards in an open Java environment
http://www.gemplus.com/                                       Major supplier of Smart Card readers
http://SCS.BOEBLINGEN.DE.IBM.COM/          IBM Smart Card center of Competence
 

Acquire the hardware and software

Buy a smart card reader,  Gemplus GCR-410 (41.95 pound + VAT).
Buy the Belkin, model F5U003 USB-to-Serial Adapter (60 pounds +VAT) for Network Station 2200
Download the Java OCF 1.1.1 code from http://www.opencard.org/  , instructions here
Download the Gemplus drivers from http://www.gemplus.com/ , instructions here
That's all.
For testing on Windows 98, you also need to download java from IBM or Sun, and javax.comm software from Sun

How to use the Smart Card Reader

Smart Card Readers can be bought from the Internet or from a local specialist store (Radio Spares UK)
The Gemplus GCR-410 Smart Card Reader is a small (86x85x25 mm) device. (picture here)
(here are the specs) http://www.gemplus.com/products/hardware/gcr410.htm
It comes with a serial cable attached (9-pin connector and a PS/2 piggy-back power connector).
There is no need for an external power brick as the power is derived from the keyboard/mouse PS/2 connector.
In the 2200 case, the mouse plugs into a PS/2 socket of the USB keyboard. You can piggy-back from there.
 

How to use the USB-Serial adapter

The Belkin serial cable can be obtained from a number of Internet suppliers. Search for F5U003.
I bought it from our local PC World outlet. It comes with a Windows 98 driver diskette. NSM drivers are in libibmcomm.so
You plug the USB cable in the spare USB slot next to the keyboard USB slot (the two may be interchanged).
It is powered by the USB port of Network Station 2200.

Software download

The software can be downloaded free, as follows.
Usually, you first have to register your address details. Then you proceed with the download of the selected file.

Open Card software(includes the stockbroker demo)
http://www.opencard.org/download/code/1.1.1/Convenience.class  (1,698,264 bytes)
Note: there is an error on their website. You have to rename Convenience.exe to Convenience.class, then execute java Convenience

Gemplus drivers
http://www.gemplus.com/products/hardware/drivers.htm takes you after logging in to
http://www.gemplus.fr/developers/resources/drivers/index.htm then click on
OCF drivers and click on gemplus-terminals.zip
( http://www.gemplus.fr/developers/passwd_protected/download/drivers/ocf/gemplus-terminals.zip )

To verify Smart Cards on a Windows 98 machine, you also need to download

JDK 1.1.8 from IBM
internal IBM: http://w3.hursley.ibm.com/java/codedemos/quickdl.html
after JIM Registration, will take you to http://xmlhost.hursley.ibm.com/production/JavaPortfolioSystem
and select View Java Portfolio ->JDK for IBM Windows-32 --> 1.1.8 --> JDK InstallShield, downloads the full JDK
ibm-jdk-n118p-win32-x86.exe  (10,907,661 bytes 11/24/99)
external IBM-site
http://www.ibm.com/java/jdk/118/index.html  Click on Register&download, select ibm-jdk-n118p-win32-x86.exe (10,907,661 bytes 11/24/99)
or download from SUN
JDK 1.1.8 from  SUN
http://java.sun.com/products/jdk/1.1/download-jdk-windows.htmljdk1_1_8-win.exe (8,798,933 bytes)
  and
Java Communications API 2.0  from SUN
http://java.sun.com/products/javacomm/  (272,690 bytes)
Select download for Windows platform: javacomm20-win32.zip (272,690 bytes)


Unpack software to default directories

After you have downloaded all this, you can create the contents into the required directories.
NSM V2R1 already has Java 1.1.8 and javax.comm installed. Check these files are there:
\NetworkStationV2\prodbase\X86\usr\local\java\J118\lib\classes.zip
\NetworkStationV2\prodbase\X86\usr\local\java\J118\lib\javaxcomm.zip
\NetworkStationV2\prodbase\X86\usr\local\java\J118\lib\javax.comm.properties
 

For Windows 98/NT, you may already have installed Java 1.1.8 in the default directory \jdk1.1.8 If not, then execute ibm-jdk-n118p-win32-x86.exe
Next, unzip  javacomm20-win32.zip in the default directory  \commapi, also copy the commapi.dll to \jdk1.1.8\bin\commapi.dll

The OpenCard software installs in \Convenience\OCF1.1.1, by executing java Convenience from the directory where you downloaded Convenience.class
OpenCard provides many jar files. Check they are there: \Convenience\OCF1.1.1\lib\*.jar
base-core.jar
base-opt.jar
comm.jar
demo.jar
gemplus-terminals.jar
ibmservices.jar
migterminals.jar
reference-services.jar
reference-terminals-windows.jar
rejar-tool.jar
stockbroker-x.jar
The classpath may become very long,  giving us problems when it exceeds some limit.
There is a rejar-tool.jar file that allows you to combine all the required jar-files into a single OCF.jar, which will not clutter the classpath.
Instructions here.
\jdk1.1.8\bin\java    -classpath .;\jdk1.1.8\lib\classes.zip;\j\rejar-tool.jar com.ibm.tools.rejar.ReJar   \Convenience\OCF1.1.1\lib    c:\OCF.jar
From the rejar-tool menu select the 11 jar files and execute. This builds a all-encompassing OCF.jar file.
Then copy OCF.jar to \NetworkStationV2\prodbase\X86\usr\local\java\J118\lib\OCF.jar
or for testing with Windows 98 copy to \jdk1.1.8ibm\lib\OCF.jar

The Gemplus-drivers gemplus-terminals.zip can be unzipped in a default directory OCF1.1. Then copy just one jar-file gemplus-terminals.jar from the lib directory to \NetworkStationV2\prodbase\X86\usr\local\java\J118\lib\gemplus-terminals.jar
or for testing with Windows 98 unzip to \jdk1.1.8ibm\lib\gemplus-terminals.jar
 

Properties file

The opencard.properties file may look like this:
OpenCard.services = com.ibm.opencard.factory.MFCCardServiceFactory
OpenCard.terminals = com.gemplus.opencard.terminal.GemplusCardTerminalFactory|mygcr|GCR410|COM1
OpenCard.trace = opencard:0 com.ibm:0 com.gemplus.opencard.terminal:0

Once all the software is installed, you need to copy the properties files in place.
\NetworkStationV2\prodbase\X86\usr\local\java\J118\lib\opencard.properties    (copy from above example)
\NetworkStationV2\prodbase\X86\usr\local\java\J118\lib\javax.comm.properties (already done by NSM V2R1)

or in the case of Windows 98/NT:
\jdk1.1.8ibm\lib\opencard.properties    (copy from above example)
\jdk1.1.8ibm\lib\javax.comm.properties (copy from from \commapi\lib)


Testing, testing...

First you invoke the java command from a command line:

Check the version of java:
java -fullversion

Check classpath:
echo $CLASSPATH
echo $JAVAHOME
echo %CLASSPATH% in Windows

Set classpath (all on one line, ignore the continuation (\) character )
export CLASSPATH = .:/usr/local/java/J118/lib/classes.zip:/usr/local/java/J118/lib/javax.comm.zip:/usr/local/java/J118/lib/OCF.jar:/usr/local/java/J118/lib/gemplus-terminals.jar

or in Windows
set CLASSPATH = .;\jdk1.1.8\lib\classes.zip;\jdk1.1.8\lib\comm.jar;\jdk1.1.8\lib\OCF.jar;\jdk1.1.8\lib\gemplus-terminals.jar

With the 2800 you can start testing Smart Card operations immediately.
When you use the 2200 with USB, you need a fix for PTF-2.
either: insert a line ln /dev/utty0 /dev/ucom0 just before the seriald line
or: backup /usr/local/java/J118/lib/libibmcomm.so and replace with the test version of libibmcomm.so,
that I have included in the QUICKSMART.ZIP file at the end of this document.

java demos.samples.StartOpenCard

With a Card inserted you can query its ID with
java demos.samples.GetCardID

and when you have the stockbroker demo installed you invoke it with
cd /stockbroker
java sun.applet.AppletViewer SignatureDemo.html

When everything works from the command line, then you are ready to create a desktop icon.
This is how I configured NSM to create a Stocbroker icon.
I assume you have already done the following:

Now let's configure NSM: You will find debug info in your home directory: 1.txt and 2.txt

As development have not come up with a Smart Card actlogin feature, it is not possible to create a NSM desktop based on the Smart Card ID.
As an alternative to actlogin, the Italian BP starts a Java Smart Card Login application in Kiosk mode (suppressed login).
When the user inserts his Smart Card and confirms the PIN number, the Java application starts an ICA session, based on the Smart Card userid and password, and also starts any other application that is authorized for this user.
When the user extracts the Smart Card, all user sessions get terminated, the ICA session disconnects, and can be reconnected again from any other terminal.
 


Reprint from: http://www.belkin.com/products/product_index/USB/usb_catalog_pages/serial/f5u003.html

Belkin USB Serial Adapter


The Belkin USB Serial Adapter is the ideal way to connect additional serial devices to your PC. Connect fax machines, modems, printers, point-of-sale devices, industrial controls, and other local hardware having RS-232 serial interfaces. The USB Serial Adapter is automatically detected and configured - there's no need to install, shut down or reboot, and you can add or switch serial devices on the fly. When used with ExpressBus® hubs, up to 127 USB Serial Adapters can be used simultaneously, each connecting a serial device. With the Belkin USB Serial Adapter, multiple serial device connections are instant and simple. F5U003
 
 


 
 
Package Includes:
  • Belkin USB Serial Adapter 
  • Software Diskette 
  • Belkin USB Device Cable, A/B, 6 ft., Part # F3U133-06 

  • User Guide 


Reprint from: http://www.gemplus.com/products/hardware/gcr410.htm
GCR410-P
Product Sheet.
 
GCR410-P A Universal Smart Card Reader

A highly accessible, highly convenient solution.

This compact card reader, designed to plug into a PC environment, is the ultimate smart card peripheral for a PC. It is also very simple to use and install. The user needs no technical knowledge. If you need electronic commerce, home banking or e-purse facilities, secure computer access or any of a multitude of other applications, the GCR410-P is the smartest answer. For the first time, a solution is available that offers impressive possibilities at an exceptional price.
 
 

Small is beautiful

At a mere 86 x 85 x 26 mm, the GCR410-P will handle the card interface, while your computer supports and manages the applications. Compatible with all major computers and operating systems, the GCR410-P is powered from your computer’s keyboard port, free of the constraints associated with other power-source options.

It will open up many possibilities, including:

Years of Gemplus technological experience, now available to all

The GCR410-P is based on Gemplus’s GemCore ® hardware and firmware, which means it can handle all types of ISO7816- compatible smart cards without compatibility problems. It is user-friendly, and operating or using it requires no technical expertise. The GCR410-P will happily blend with all main environments (DOS, Windows ®* 3.x, Windows ® 95, Windows ® NT, OS/2 ® , etc.), all types of card, and most makes of computer. It will readily adapt to new smart-card services, as they become available.
 
 

Compatibility with the GCR400

The GCR410-P is compatible with the GCR400 when used with its main power supply block. When the GCR400 is used with a battery, some application software changes may be necessary for compatibility.
 
 

GCR410-P Features and Application Standard
 

Feature
Description
Smart-card interface
  • reads from and writes to all ISO7816-1/2/3/4 memory and microprocessor smart cards (T=0, T=1)
  • supports 3V and 5V cards
Communication
  • programmable from 9,600 baud to 115,200 baud with the smart card
  • up to 38,400 baud for communication with PC
Power consumption
  • average of 20 mA in operational mode
Interface modes
  • Serial communication with the PC through RS232 connection
  • TLP224 and GBP (Gemplus Block Protocol)
Power supply
  • 5V maximum
Electro-magnetic standards
  • Europe: 89/336/CEE guideline
  • USA: FCC part 15
Security levels
  • Europe: EN60950
  • USA: UL1950
  • Canada: CSA950
The cable supplied with the GCR410-P allows the user to connect both the keyboard and the reader to the same port.

And finally

For the lazy Smart Card tester, here is the quicksmart.zip file. Unzip it to any PC hard drive, or even write to a read-only CD-ROM and execute the test.bat files.
QUICKSMART.ZIP is 11MB.
You can build the NSM files from the QUICKSMART directories by copying:
 
/stockbroker/* /NetworkStationV2/prodbase/x86/stockbroker/*
/jdk1.1.8/lib/OCF.jar /NetworkStationV2/prodbase/x86/usr/local/java/J118/lib/OCF.jar
/jdk1.1.8/lib/opencard.properties /NetworkStationV2/prodbase/x86/usr/local/java/J118/lib/opencard.properties
Do not copy javax.comm.properties or classes.zip or comm.jar as they are Windows-specific. NSM has these files already built-in (javaxcomm.zip instead of comm.jar).
The QUICKSMART version of OCF.jar has all the required OCF jar-files + demo/stockbroker jar files + gemplus-terminals.jar.
The html directory contains this file and the associated specsheets for the Gemplus GCR-410 and Belkin USB-Serial F5U003 adapter
+ the test version of libibmcomm.so to fix the USB problem with PTF-2

Good Luck.  Ed.
14 December 1999
Ed van den Oever/UK/IBM@IBMGB