
Treiber fr REINER SCT cyberJack pinpad/e-com USB Kartenleser

Martin Preuss

   Copyright  2006 REINER SCT GmbH

   $Date$

   Dies ist das Handbuch zum Linux-Treiber fr die Reiner SCT
   cyberJack Kartenleser.
     _________________________________________________________

   Table of Contents
   1. bersicht
   2. Von diesem Treiber untersttzte Gerte
   3. Distributions-spezifische Hinweise

        3.1. RPM-basiert

              3.1.1. Einrichtung unter SuSE Linux

        3.2. DEB-basiert
        3.3. Alle anderen Distributionen

   4. Support
   5. Troubleshooting

        5.1. Herausfinden der Kernelversion
        5.2. Groe Anzahl von Lesern
        5.3. Hotplugging
        5.4. Logging

   6. Bekannte Probleme
   7. Anwendungen

        7.1. Moneyplex

   8. Zustzliche Information

        8.1. CT-API
        8.2. PC/SC

              8.2.1. Installation

        8.3. Multithreading
        8.4. Kommandolange
        8.5. Tastendruck Callback
        8.6. Informationen zur Treiberversion
        8.7. Zusaetzliche CT_init Ersatz-Funktion
        8.8. Pin-Ueberpruefung mit der PC/SC Funktion
                SCardControl

1. bersicht

   Dieser Treiber fr die Cyberjack Pinpad/ecom-Familie von USB
   Kartenlesegerten implementiert den CTAPI Standard in der
   Version 1.1 sowie das PC/SC-Interface von pcsc-lite.

   Er ist vollstndig im Userspace implementiert. Dadurch
   entfallen Schwierigkeiten mit unterschiedlichen
   Kernel-Versionen, dem Kompilieren und Patchen von Kerneln etc.

   Smtliche Zugriffe werden ber das usb devfs in /proc/bus/usb
   (oder /dev/bus/usb fr udev-basierte systeme) abgewickelt.

   Behandlung von Dateirechten geschieht ausschlielich ber
   udev. Das Skript cyberjack.rules - falls es nach
   /etc/udev/rules.d installiert wurde - wird automatisch von
   udev aufgerufen, sobald der Leser angeschlossen wird. Es setzt
   die Dateirechte fr das entsprechende Gert, so da
   anschliessend die Benutzer der Gruppe cyberjack darauf
   zugreifen knnen.

   Fr mehr Informationen ber den Kartenleser selbst besuchen
   Sie bitte http://www.reiner-sct.com/. Dort finden Sie auch
   einen Onlineshop, in dem Sie diesen Leser bestellen knnen.
     _________________________________________________________

2. Von diesem Treiber untersttzte Gerte

   Die folgenden Reiner-SCT Kartenleser werden untersttzt:

                Product              ProductID
   REINER SCT cyberJack pinpad USB   0x100
   REINER SCT cyberJack e-com USB    0x100
   REINER SCT cyberJack pinpad_a USB 0x300

   Mit dem Kommando lsusb knnen Sie sich alle USB-Gerte
   anzeigen lassen. Es zeigt die Hersteller- und Gertekennung
   aller angeschlossenen Gerte an, beispielsweise:

   Bus Nr Device Nr VeID:PrID Bus 002 Device 002: ID 0451:1446
   Texas Instruments, Inc. TUSB2040/2070 Hub Bus 002 Device 006:
   ID 0c4b:0300

   Die REINER SCT Herstellerkennung ist 0c4b. Die
   Produktkennungen finden Sie in der vorigen Tabelle.
     _________________________________________________________

3. Distributions-spezifische Hinweise

   Sie finden alle Pakete unter
   http://www.reiner-sct.com/content/view/32/43/#linux.

   Die meisten Pakete erzeugen eine Gruppe cyberjack. Dieser
   Gruppe mssen alle Benutzer zugeordnet werden, die Zugriff auf
   das Gert haben sollen. Das erreichen Sie am einfachsten ber
   das KDE-Programm kuser oder das Administrations-Programm Ihres
   Systems (bei SuSE z.B. yast). Eine Ausnahme stellt hier SuSE
   10.1 dar, hier mssen Sie keine Benutzer- Zuordnung vornehmen
   (ab SuSE 10.2 hingegen schon).

   Nach der Installation des Paketes und der Benutzerzuordnung
   sollten Sie Ihren Rechner neu starten, damit die nderungen
   gltig werden.
     _________________________________________________________

3.1. RPM-basiert

   Reiner-SCT bietet RPM-Pakete fr die folgenden Distributionen
   an:

     * SuSE 10.2
     * SuSE 10.1
     * SuSE 10.0
     * SuSE 9.3
     * Fedora Core 5
     * Fedora Core 4

   Installieren Sie das entsprechende Paket einfach durch das
   folgende Kommando: rpm -i <Paketdatei>

   Sollten Sie bereits ein lteres Treiberpaket installiert
   haben, verwenden Sie stattdessen das folgende Kommando: rpm -U
   <Paketdatei>

   Es gibt allerdings eine Besonderheit bei Verwendung von
   SuSE10.0 auf einem 64-Bit-System mit der Anwendung
   "Moneyplex": Da diese Anwendung leider eine 32-Bit-Anwendung
   ist, kann sie nur mit der 32-Bit-Version unseres Treibers
   arbeiten. Leider war der Kernel von SuSE10.0 noch nicht in der
   Lage, alle 32-Bit-Aufrufe des Treibers nach 64-Bit
   umzuwandeln. Hier muss daher eine Aenderung an der Datei
   /etc/cyberjack.conf vorgenommen werden. Fuegen Sie bitte die
   folgende Zeile ein: "flags=0x20000".
     _________________________________________________________

3.1.1. Einrichtung unter SuSE Linux

   Nach der Installation des Treibers muessen Sie die Benutzer,
   die auf den Leser zugreifen koennen sollen, in die Gruppe
   "cyberjack" einfuegen.

   Am einfachsten geschieht dies mit Yast: Starten Sie Yast,
   rufen Sie das Menu "Sicherheit und Benutzer" auf und dort
   "Gruppen bearbeiten und anlegen".

   Es erscheint ein Fenster, das standardmaessig die
   Systemgruppen nicht anzeigt, daher muessen Sie den Filter
   aendern. Klicken Sie dazu unten rechts auf "Filter festlegen"
   und waehlen Sie dort "Systemgruppen". Daraufhin sollten Sie in
   der Liste auch die Gruppe "cyberjack" finden, die Sie dann
   markieren muessen. Anschliessend klicken Sie unten auf
   "Bearbeiten".

   In dem Fenster, welches dann erscheint, setzen Sie bei den
   aufgefuehrten Benutzern, die auf den Leser zugreifen koennen
   sollen, die Markierung.

   Klicken Sie nun auf "Uebernehmen" und starten Sie das System
   neu, Der Leser sollte nun fuer die markierten Benutzer
   verwendbar sein.
     _________________________________________________________

3.2. DEB-basiert

   Reiner-SCT bietet DEB-Pakete fr die folgenden Distributionen:

     * Debian unstable
     * Ubuntu 6.06
     * Ubuntu 6.10

   Installieren Sie das entsprechende Paket mit: dpkg -i
   <Paketdatei>
     _________________________________________________________

3.3. Alle anderen Distributionen

   Es gibt momentan wenig Erfahrungen mit anderen
   Linux-Distributionen. Haben Sie ein RPM-basiertes System, so
   knnen Sie probieren eigene RPM-Paket zu erstellen: rpm
   --rebuild <Quellpaketdatei> oder rpmbuild --rebuild
   <Quellpaketdatei>

   Falls Sie den Treiber selber kompilieren wollen, wechseln Sie
   in das Hauptverzeichnis des entpackten Treiber-Paketes und
   geben Sie die folgenden Befehle ein: ./configure make

   Anschlieend knnen Sie den Treiber auf Ihr System
   installieren. Dazu bentigen Sie sehr wahrscheinlich
   Administrator-Rechte. make install
     _________________________________________________________

4. Support

   Support fr diesen Treiber bietet REINER SCT. E-mail:
   support@reiner-sct.com Postadresse: Schwabacher Str. 34, 90762
   Frth, Deutschland

   Bitte fgen Sie ihrer Problembeschreibung die folgenden
   Informationen bei:

     * Name und Version des verwendeten Programmes, mit dem der
       Fehler auftrat
     * die vollstndige Fehlermeldung
     * den Namen und die Version der von Ihnen verwendeten
       Linux-Distribution (z.B. SuSE 10.1, Debian 3.0r1 testing)
     * CPU-Typ (z.B. der Inhalt der Datei /proc/cpuinfo)
     * Kernelversion (z.B. die Ausgabe des Befehls uname -r)
     * Liste der angeschlossenen USB-Gerte (z.B. die Ausgabe des
       Befehls lsusb)
     _________________________________________________________

5. Troubleshooting

5.1. Herausfinden der Kernelversion

   Sie finden die Version des derzeit laufenden Kernels mit dem
   Befehl uname -r heraus.

   Die Version der Kernel-Quellen ersehen Sie aus dem
   Verzeichnisnamen (normalerweise unterhalb des Verzeichnisses
   /usr/src). Auerdem ist die Version in der Datei Makefile im
   Linux-Quellverzeichnis (meistens /usr/src/linux) in den ersten
   3 Zeilen verzeichnet.
     _________________________________________________________

5.2. Groe Anzahl von Lesern

   Der cyberJack wurde mit bis zu 52 gleichzeitig angeschlossenen
   Gerten (ber 7-Port Hubs) getestet. Dabei gibt es allerdings
   etwas zu beachten:

     * Linux bis Version 2.4.19 hngt sich vollstndig auf, wenn
       zu viele Gerte angeschlossen sind. Versionen ab 2.4.20
       weisen dieses Problem nicht mehr auf.
     * Es treten manchmal timeout-Fehler auf. Das Problem scheint
       hier im Linux-Kernel selbst zu liegen (usb-uhci). Mit
       schnelleren Rechnern tritt dieses Problem nicht mehr auf
       (ab 2GHz).
     * Sollte es immer noch nicht wie gewnscht funktionieren,
       sollten Sie die beteiligten USB-Controller-Karten und/oder
       Hubs austauschen. Es gibt hier offensichtlich eine
       besonders groe Streubreite in der Qualitt dieser Gerte.

   Der Daten-Durchsatz nimmt nicht ab, wenn Sie statt einem 50
   Kartenleser anschlieen und konstant auslesen (getestet mit
   den Kommandos SELECT und READ_BINARY).
     _________________________________________________________

5.3. Hotplugging

   Linux untersttzt hotplugging (das Einstecken und Entfernen
   von USB-Gerten bei laufendem Betrieb). Dies wird durch das
   udev-System implementiert.

   Sie finden udev-Skriptdateien fr die REINER SCT Kartenleser
   im Verzeichnis etc/udev des Quellpaketes.

   Da udev-Skripte Distributions-spezifisch sind (nicht alle
   verwenden udev, und SuSE verwendet ausserdem resmgr, zudem
   sind auch die Namen der Skripte nicht einheitlich), knnen wir
   nicht fr alle am Markt existierenden Distributionen die
   passenden Skripte bereitstellen. Die von uns gelieferten RPM-
   und DEB-Pakete installieren die fr das jeweilige System
   passenden Dateien an die vorgesehene Stelle, so da mit diesen
   Paketen hotplugging problemlos mglich ist.
     _________________________________________________________

5.4. Logging

   Dieser Treiber erlaubt die Aufzeichnung der Kommunitkation mit
   dem Kartenleser. Sie schalten es ein, indem Sie die
   Umgebungsvariable CJDEBUG anlegen. Wenn diese existiert,
   schreibt der Treiber die gesendeten und empfangenen T1-Daten
   nach /tmp/cj.log.
     _________________________________________________________

6. Bekannte Probleme

   Leider enthalten alle Kernel bi einschliesslich Version
   2.6.12-rc5 einen schweren Fehler in der Behandlung von
   asynchronen URB's (USB Request Block) im Userspace. Dieser
   Fehler hat absolut nichts mit dem Reiner SCT Treiber zu tun,
   dennoch betrifft er auch unseren Treiber fr PC/SC. Der Fehler
   tritt auf, wenn der PC/SC Dienst beendet wird und kann im
   schlimmsten Fall zum vollstndigen Absturz des Kernels fhren.

   Es wurde eine Lsung erarbeitet, die aber bisher nicht
   offizieller Bestandteil des Linux-Kernels ist. Wir bieten
   unsere Lsung aber als patch an (in Form der Datei
   patches/usb-async_urb-devio-oops-fix.patch).

   Falls Sie PC/SC in Verbindung mit einem betroffenen Kernel
   verwenden wollen, raten wir daher dringend dazu den
   mitgelieferten Patch anzuwenden.
     _________________________________________________________

7. Anwendungen

7.1. Moneyplex

   Moneyplex bringt seine eigenen Treiber fuer die bekanntesten
   Geraete mit. Leider sind die Treiber fuer den Cyberjack, die
   sich auf der Moneyplex-CD befinden, meist veraltet und
   funktionieren auf aktuellen Systemen nicht.

   Sie sollten daher unbedingt den jeweils aktuellsten Treiber
   von unserer Homepage herunterladen und installieren.

   Anschliessend muessen Sie dann im entsprechenden
   Konfigurationsmenue von Moneyplex direkt unseren Treiber
   angeben (je nach System entweder in /usr/lib oder in
   /usr/lib/readers, Dateiname ist "libctapi-cyberjack.so".

   Damit sollte Moneyplex auch mit dem Cyberjack zusammenarbeiten
   koennen.
     _________________________________________________________

8. Zustzliche Information

8.1. CT-API

   Die CT-API Spezifikation erhalten Sie auf der Seite
   http://www.darmstadt.gmd.de/~eckstein/CT/mkt.html

   Bitte beachten Sie, da die Port-Nummern bei 1 beginnen (wie
   in den Spezifikationen vorgesehen).
     _________________________________________________________

8.2. PC/SC

   Dieser Treiber bietet inzwischen auch einen PC/SC-Treiber fr
   pcsc-lite an. Er wurde mit pcsc-lite-1.2.0 getestet.
     _________________________________________________________

8.2.1. Installation

   Fr RPM-basierte Systeme ist der sogenannte IFD-Treiber im
   Paket ctapi-cyberjack-ifd enthalten.

   Falls Sie den Treiber aus dem Quellpaket selber kompilieren,
   wird durch make install der IFD-Treiber an die passende Stelle
   in Ihrem System (normalerweise /usr/lib/pcsc/drivers/)
   installiert.
     _________________________________________________________

8.3. Multithreading

   Dieser Treiber ist nicht thread-safe, d.h. es knnen nicht
   mehrere Threads des gleichen Programmes auf den gleichen Leser
   zugreifen (dies wrde aber ohnehin meist zu Problemen auf der
   Karte fhren).

   Allerdings knnen unterschiedliche Threads des gleichen
   Programmes auf unterschiedliche Gerte zugreifen. So knnen
   also beispielsweise 3 Threads gleichzeitig auf 3 Karten in 3
   unterschiedlichen Gerten zugreifen.
     _________________________________________________________

8.4. Kommandolange

   Die Kommandolnge ist derzeit auf ISO7816 short commands
   reduziert. Dies bedeutet allerdings im normalen Betrieb keine
   Einschrnkung.
     _________________________________________________________

8.5. Tastendruck Callback

   IS8 rsct_setkeycb(IU16ctn, void (*cb) (void *user_data));

   Die Funktion rsct_setkeycb wurde hinzugefgt, um laufenden
   Programmen eine Rckmeldung ber gedrckte Tasten des Lesers
   zu geben. Die Funktion, die als 2. Argument dieses Aufrufes
   geliefert wird, wird jeweils aufgerufen, wenn ein C4- oder F4
   S-Block vom Leser empfangen wurde. Die Anwendung kann dann
   beispielsweise einen Piepton erzeugen, oder die Anzahl der
   gedrckten Tasten anzeigen.
     _________________________________________________________

8.6. Informationen zur Treiberversion

   void rsct_version(IU8*vmajor, IU8*vminor, IU8*vpatchlevel,
   IU16*vbuild);

   Die Funktion rsct_version gibt die vollstaendige Version des
   Treibers in den uebergebenen Variablen zurueck.
     _________________________________________________________

8.7. Zusaetzliche CT_init Ersatz-Funktion

   IS8 rsct_init_name(IU16ctn, const char*device_name);

   Die Funktion rsct_init_name erlaubt die direkte Angabe des
   Geraetes wie bei PC/SC. Damit kann eindeutig festgelegt
   werden, welches Geraet verwendet werden soll. Der Geraetename
   ist wie folgt aufgebaut:
   "usb:VENDOR_ID/PRODUCT_ID:libusb:BUS_ID:DEVICE_ID". Fuer einen
   neuen Cyberjack an /proc/bus/usb/003/002 lautet der Name
   demnach: "usb:0c4b/0300:libusb:003:002".
     _________________________________________________________

8.8. Pin-Ueberpruefung mit der PC/SC Funktion SCardControl

   Die folgende Tabelle zeigt Werte fuer die einzelnden Felder
   der Struktur PSCS_VERIFY_STRUCTURE die mit ASCII und
   FPIN2-kodierten Pins getestet wurden.

             Feld            ASCII FPIN2
   bTimerOut                 00    00
   bTimerOut2                00    00
   bmFormatString            82    81
   bmPINBlockString          04    48
   bmPINLengthFormat         00    04
   wPINMaxExtraDigit         0408  0408
   bEntryValidationCondition 02    02
   bNumberMessage            01    01
   wLangId                   0904  0904
   bMsgIndex                 00    00
   bTeoPrologue 0-2          00    00
