REINER SCT cyberJack pinpad/e-com USB chipcard reader driver
============================================================


Table of Contents
=================

1  Overview
2  Kernel part
2.1  Howto check the kernel version
2.2  LINUX Kernel version 2.4.6 and up
2.3  LINUX Kernel 2.4.0 to 2.4.5
2.4  LINUX Kernel up to 2.3.
2.5  OHCI host controllers
2.6  Hotplugging
3  User space part
3.1  Distribution RedHat 7.0-7.2
3.2  Distribution SuSE 7.3
3.3  Distribution SuSE 8.0
3.4  Distribution SuSE 8.1
3.5  All other Distributions
4  Additional Information
4.1  Mandatory locking
4.2  Permissions
4.3  CT-API
4.4  Large number of readers
4.5  Multithreading
4.6  Command size
4.7  Testing
4.7.1 cjgeldkarte
4.7.2 ctsh
5  Support


1) Overview
===========

This driver for the REINER SCT cyberJack pinpad/e-com USB chipcard
reader implements the CT-API interface. It consists of a kernel part and
an userspace part. The kernel part is a module handling the USB data
exchange with the reader. The userpace part is a library implementing
the CT-API interface and handling the higher level of the protocol used
to communicate with the reader. To use the cyberJack both parts must
be installed.

For more information about the smart card reader itself please visit
www.reiner-sct.com. There is also a shop where the the readers can be
ordered online.


2) Kernel part
==============

2.1) Howto check the kernel version
-----------------------------------

You can determine the version of the currently running kernel by executing

   uname -r

The version of the installed kernel sources, which lie normally in
/usr/src, can be determined by looking at the source directory name or
by looking into the main Makefile, where it is in the first three lines.

The kernel part is included in the official linux kernels starting with
version 2.4.6. Operating systems, which come with these kernels are e.g.:

- Caldera OpenLinux Maintenance Release 3.1.1 (Workstation/Server)
- RedHat 7.0 with Updates, 7.1 with Updates, 7.2, 7.3, 8.0
- SuSE LINUX 7.3, 8.0, 8.1
- Debian 3.0


2.2) LINUX Kernel version 2.4.6 and up
--------------------------------------

If you have a distribution, which comes with a running 2.4.6 or above
kernel, you probably don't have to mess with the kernel. The correct
drivers should be loaded upon insertion of the reader. 

There exist two different USB host controllers on the PC:

- UHCI
- OHCI

The first is the more common. Details about this is written in the next
few paragraphs. The second is less common and has not been tested by
REINER SCT, but has been reported to work. If you have an OHCI host
controller you can ignore what is written her about the UHCI drivers. 

The Linux kernel comes with two different drivers for the UHCI USB host
controller. You have to make sure, that you use not the uhci driver, but
the usb-uhci driver has been loaded. If the driver is loaded as a module,
you can check the driver type by starting the programm "lsmod". It prints
something like:

Module                  Size  Used by
ppp_async               6348   1 (autoclean)
ppp_generic            13084   3 (autoclean) [ppp_async]
usb-uhci               21800   0 (unused)
wvlan_cs               24816   1
8139too                11820   1 (autoclean)
de4x5                  42960   1 (autoclean)

You can see there the usb-uhci module loaded, which is correct. If
there is no usb-uhci or uhci, it is either no USB support loaded - try
inserting a USB device - or USB is statically linked to the kernel. You
have to watch here for USB related output at boot time or shortly after
a boot by typing "dmesg" at the shell prompt.

usb-uhci was the first driver for an UHCI USB host controller in Linux,
but is not well structured. uhci is a totally rewritten driver, but has
unfortunatelly still problems with the usb-serial line of drivers and
therefor the cyberJack will not with with it. How to select the correct
driver depends on the Linux distribution.  (See e.g. the section about
SuSE 7.3.)

If you have to compile and install a kernel for yourself, please look into
the manual of your Linux distribution, how this is done properly. E.g. in
SuSE Linux 7.2 it is described in the reference manual (Die Referenz) in
chapter 9.  The config options relevant for the cyberJack installation
are in "USB support". First make sure, that you use "UHCI (Intel PIIX4,
VIA, ...) support" and NOT "UHCI Alternate Driver (JE) support". The
last one is the uhci driver and will not work, as has been described in
the previous paragraph.

For activating the cyberJack driver, you need to enable "Prompt
for development and/or incomplete code/drivers" in "Code maturity
level options".  After this, you can go to "USB support" -> "USB
Serial Converter support" and active "USB Serial Converter support".
The cyberJack driver is then near the bottom.

Overview of the options:

Code maturity level options
  -> Prompt for development and/or incomplete code/drivers
    -> Set to 'y'.
USB support
  -> Support for USB
    -> Set to 'y' or 'm'
USB support
  -> UHCI (Intel PIIX4, VIA, ...) support
    -> Set to 'y' or 'm'
  OR
  -> OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support
    -> Set to 'y' or 'm'
USB support
  -> USB Serial Converter support
    -> USB Serial Converter support
      -> Set to 'y' or 'm'
USB support
  -> USB Serial Converter support
    -> USB REINER SCT cyberJack pinpad/e-com USB chipcard reader
      -> Set to 'y' or 'm'

If your installation includes 'hotplug', all which is then neccessary
for loading the module is to plug in the reader. When 'hotplug' is not
installed, you can add the lines:

alias char-major-188 usbserial
above usbserial cyberjack

to the file /etc/modules.conf. This should then install the usbserial
module and the cyberjack module when accessing the reader the first
time. (Remember, that a driver for your USB controller must be installed,
but not the 'uhci.o' driver.)



2.3) LINUX Kernel 2.4.0 to 2.4.5
--------------------------------

For some earlier kernels (2.4.0-2.4.5), there are patches
in the kernel directory. Apply these with the program 'patch' by going
to the kernel source directory and starting patch with

% cd /usr/src
% patch -p0 <.../cyberjack-2.4.x.patch

or

% cd /usr/src/linux-2.4...
% patch -p1 <.../cyberjack-2.4.x.patch

For configuration options see the above section about the kernels
with version 2.4.6 and up.

(There is also the 'kernel' directory in the cyberjack driver
distribution, which tries to detect the kernel version (2.4.0-2.4.5)
and to compile a module for it, but this is mostly untested.)

Anyway, I suggest to use a kernel with version 2.4.6 or above.


2.4) LINUX Kernel up to 2.3.
----------------------------

Are not supportet by REINER SCT. Please upgrade the kernel or try yourself
the backports.

2.5) OHCI host controllers
--------------------------

Currently there are problems with OHCI host controllers and the cyberJack
under Linux. It seems to be a problem of the ohci driver. The symptoms
are, that a CT_init fails after the reader has been accessed a few times.
2.4.20 did work with a OHCI PCI card (OPTi 82C861). So please try to
upgrade at least to 2.4.20 if you have any problems with an OHCI controller.
Newer 2.5 kernels could work, too. At least 2.5.32 is known to work, but
it is not suggested to install a 2.5-kernel unless you know what you do.

2.6) Hotplugging
----------------

Linux supports hotplugging with USB devices. This is implemented by
calling /sbin/hotplug from the kernel. Because this is not part of the
cyberJack driver and every distribution manufacturer does develop here
its own scripts, REINER SCT can't provide here support. If problems
arise in this area, please contact your distribution manufacturer.


3) User space part
==================

The user space part of the cyberJack support is included in this
cyberJack driver package. It is in the 'ctapi' directory and implements
the CT-API defined for the German health insurance cards and is used
by most German banking applications.


3.1) Distribution RedHat 7.0-7.2
--------------------------------

There is a RPM package available, which can be installed by running e.g.

   rpm -i <package file>


3.2) Distribution SuSE 7.3
--------------------------

The version of the cyberJack driver, which comes with SuSE 7.3 has a few
problems. These are fixed in the new RPM packages for this system.
You can install this RPM by running e.g.

   rpm -i <package file>

or update it by running e.g.

   rpm -Fvh <package file>

Additional you need to edit "/etc/rc.config.d/hotplug.rc.config".
Here the variable "HOTPLUG_USB_HOSTCONTROLLER_LIST" must be set from
"uhci usb-uhci usb-ohci ehci-hcd" to "usb-uhci uhci usb-ohci ehci-hcd"
Without this change, the uhci host controller driver is loaded instead
of the usb-uhci driver. For a description of this issue, see the section
about kernels 2.4.6 and up.


3.3) Distribution SuSE 8.0
--------------------------

This distribution does load the correct UHCI driver. So if your hardware
has a USB UHCI host controller, you needn't make any changes.

You can install this RPM by running e.g.

   rpm -i <package file>

or update it by running e.g.

   rpm -Fvh <package file>


3.4) Distribution SuSE 8.1
--------------------------

It seems to work here out of the box. You can update the driver there
if you need the new features present in the new drivers.


3.5) All other Distributions
---------------------------- 

There is currently no experiance with other Linux distributions. It
should work in most cases as described above. If you get any problems
with the RPM package, you can try to rebuild it on your system with

   rpm --rebuild <source package file>

or

   rpm -ta <tar.gz file>

If you want to compile the source yourself just go into the main
directory of the extracted archive and type

   make

The include file 'ctapi.h' and the resulting libraries
'libctapi-cyberjack.a' and 'libctapi-cyberjack.so' from the directory
'ctapi' can then be copied to convenient places. For 'ctapi.h' this
would normally be '/usr/include' and for the libraries '/usr/lib'.

The name scheme 'libctapi-cyberjack.*' has been choosen to make it
possible to install more than one CT-API library on your system. If
this is the only CT-API library installed, you should rename it to
'libctapi.so', because probably most applications look by default for
this file name.

There is also a driver for MUSCLE available, but this is not
much tested.  You can then copy the file 'libcyberjack_ifd.so' from
'pcsc' to the default MUSCLE library directory '/usr/local/pcsc/lib'
or any other suitable directory.  You can then add following entry to
'/etc/reader.conf':

# REINER SCT cyberJack pinpad/e-com USB (/dev/ttyUSB0)
FRIENDLYNAME    "REINER SCT cyberJack pinpad/e-com USB"
DEVICENAME      REINERSCT_CYBERJACK_USB
LIBPATH         /usr/local/pcsc/lib/libcyberjack_ifd.so
CHANNELID       0

The LIBPATH contains the whole path to the cyberJack MUSCLE interface
library. CHANNELID contains the number appended to '/dev/ttyUSB'.
So CHANNELID 0 opens '/dev/ttyUSB0' to talk to the reader. This is used
like 'pn' in the CT_init function of the CT-API library.

If you want to install all this via an RPM, you can use the SPEC file
in the directory 'rpm' and adapt it to your needs.


4) Additional Information
=========================

4.1) Mandatory locking
----------------------

Normal locking is only advisory, i.e. the programs must be cooperative
to do the locking properly. A non-cooperative program can ignore
a lock and access the reader. Mandatory locking, which stops
even a malicious program from access the reader when it is locked,
requires setting special permissions of the device node.

>From linux/Documentation/mandatory.txt:

A file is marked as a candidate for mandatory locking by setting the group-id
bit in its file mode but removing the group-execute bit. This is an otherwise
meaningless combination, and was chosen by the System V implementors so as not
to break existing user programs.

4.2) Permissions
----------------

If a normal user should be able to access and use the cyberJack chipcard
reader, the permissions should be '2666'. The '2' enables the mandatory
locking described in the section before. The '666' enables read/write
for all users.

4.3) CT-API
------------

The CT-API specification can be downloaded at

    http://www.darmstadt.gmd.de/~eckstein/CT/mkt.html

Please note, that the port numbers start with one, i.e. pn=1 -> /dev/ttyUSB0.
This behaviour is specified in the CT-API documentation.

4.4) Large number of readers
----------------------------

Your distribution has probably only a few ttyUSB<n> nodes in /dev.
If you want to use more readers than this you have to create the
needed nodes yourself. You can use for this the script 'MAKEUSBDEV'.
This creates 64 nodes (/dev/ttyUSB0 - /dev/ttyUSB63). You can change the
number by editing the script. This sets also the correct permission for
mandatory locking. (See above.)

The cyberJack has been tested with up to 52 devices attached simultaneously
to a single PC via 7-port hubs. Some notes regarding this configuration:

- Linux at least up to 2.4.19 does result in a kernel panic, when to many
  devices are attached. Known to work is 2.4.20.

- There occure sometimes timeouts resulting in a shift of the T=1 blocks
  resulting in bad performance and sooner or later a failure of
  communcation. The problem seems to lie somewhere in the usb-uhci part
  and vanishes with a faster PC. (Try >2GHz)

- If there are still some problems try other hubs and other USB host
  controller cards. There seems to be a gread difference in quality
  in these parts.

The performance does not degrade, when going from 1 up to 50 readers,
even when doing constant I/O with cards. (Select and Read Binary)

4.5) Multithreading
-------------------

The library is NOT save against multiple threads accessing at the same
time the same reader. This gives you also most probably problems with
your card anyway.

The library is save against multiple threads accessing multiple
readers. So you could start 3 threads, each accessing their own card in
their own reader.

4.6) Command size
-----------------

The command size is currently limited to ISO7816 short commands.

4.7) Testing
------------

4.7.1) cjgeldkarte

For testing of the successful operation of your reader, you can use
'cjgeldkarte'. It supports following arguments:

-l library   - This can be used to specify, which CT-API library to load.
               'library' can be only the file name, which is then searched
               in the LD_LIBRARY_PATH, or it can be the full path to a
               CT-API library. Default value is 'libctapi.so'.
-p port      - This is the port number of the reader. It is the number
               behind '/dev/ttyUSB' incremented by one. Default value is 1.

'cjgeldkarte' prints on success the balance on the inserted GeldKarte.
So it really does something useful even after your reader is working.
If an error occures, it prints out some information and even tries to
give you some possible reasons for this error.

4.7.2) ctsh

There has also been added 'ctsh'. This is a CT-API shell, which means,
you can send CT-API commands in a shell-like environment. Start it with
the CT-API library name as the first and the port number as the second
parameter. You get on the prompt the help with 'he':

ej - eject card
co cmd[:xxxx...] - send command from script (xx: hex data appended to command)
se d:xxxxxxxx... - send APDU (d: dad, xx: data as hex, spaces are ignored)
qu - quit
he - help

'ej' is a shortcut for Eject ICC.

'co' send the command shortcut 'cmd', which is searched for in
$HOME/.ctshrc.  .ctshrc contains one command shortcut per line. It begins
with the shortcut name following the destination address and command
data. An example .ctshrc is provided. Additional data can be appended
to the shortcut name on the shell prompt after a colon.

'se' is used to send a command to the reader or card. The destination
address is specified before the colon, the data bytes in hexagesimal
notation after the colon.

'qu' terminates the program.

Depending on your configration ctsh has a build in command history.


5) Support
==========

Support of this driver is done by REINER SCT.

E-mail: linux-usb@sii.li
Postal address: Schwabacherstr. 34, 90762 Fuerth


