$Id: README,v 1.7 2003/06/23 17:32:41 aquamaniac Exp $ Overview ============ 1. License 2. Quickstart 3. What Is This Library For ? 4. Requirements 5. What Do You Get ? 6. Documentation 1. License ========== Libchipcard is available under the GNU Lesser General Public License version 2.1. Please see file "COPYING" for details. 2. Quickstart ============= This section is for those who don't have the time to read ALL this file ;-) To prepare building of CVS version: @> make -fMakefile.dist This step needs the autotools (automake, autoconf) and libtool installed. To build libchipcard do this: @> ./configure @> make And install it by doing that @> make install The last step requires you to be root. Please note that for compilation under FreeBSD 4.6.2 you'll need the GNU make tool (gmake), the standard BSD "make" won't do it. For WIN32 you'll need the mingw32 environment (http://www.mingw.org). The packages "msys" and "mingw" are required, please see the installation notes on the mingw homepage. 3. What Is This Library For ? ============================== This library is a basic framework for accessing chip cards via chip card readers (terminals). It uses the CTAPI interface which is supported by most card readers (like Towitoko, Kobil), so it should work with many of them. Since version 0.6 libchipcard can also access readers via the PC/SC (MUSCLE) interface. It is completely written in C and C++ so it should compile on a broad range of operating systems. Of course it is limited by the availability of drivers for the chip card terminal on your OS. This library directly supports memory and processor cards and some special cards, like HBCI cards, German "Geldkarten" and German medical cards. A Card File System for I2C memory cards is provided, too. The command line tool "ctfstool" allows manipulation of files on such a card. There are also tools to manipulate data on a HBCI card (hbcicard) and for raw access to memory cards (memcard). Well, the main reason for writing this library is to provide a generic interface to all terminal drivers and PC/SC. While CTAPI is a defacto standard driver API for terminals, each manufacturer has its own details and limitations. And even if they worked all the same way, some cards support only a subset of the ISO standard commands (or parameters). LibChipCard tries to abstract these differences thus providing a quite generic interface to your cards. 4. Requirements ====================== You need: - a chip card reader that is supported by your operating system. Linux drivers for the following readers are tested: - Towitoko ChipDrive Micro - Kobil Kaan - Reiner SCT Cyberjack - Orga HML 5021 - the CTAPI library which is the driver for your card reader. It is often called something like "libctapi.so.xx". Other names are (e.g.): - Towitoko readers: "libtowitoko.so" - Kobil readers - Kaan: "libct_kaan.so" - B1 : "libct_b1.so" Well, the driver is only needed if you really want to access chip cards. If no driver is found at runtime then an error will be reported. This way you can add libchipcard to your projects (like openHBCI does) to only add the ABILITY of accessing cards. - a config file "/etc/chipcardd.conf" which describes what card readers you have and at which interfaces they reside. There is a section in this file that describes the format of that config file. - a config file "/etc/chipcardc.conf" which describes where servers are listening. I recommend using "KCardSetup" to create those files. - optional PC/SC (MUSCLE, http://www.linuxnet.com) - OpenSSL (this is used for encryption of files on a memory card and for encryption of communication between client and server. 5. What Do You Get ? ===================== This package includes some KDE GUI tools: - KCardSetup: Tool to configure the card readers available in your system - KMedicalCard: Tool that shows the content of a German medical card - KPCSCSetup : Allows setting up your PC/SC system - KChipCardControl: Controls a running chipcard daemon And there are some command line tools: - hbcicard: Tool for manipulation of data on a HBCI card (Home Banking Computer Interface) - memcard: Tool to read data from and write data to a memory card - ctfstool: Tool to create and administrate a file system on a memory card. - geldkarte: shows how much money is loaded onto a German "Geldkarte" - cardcommander: allows debugging card classes - readertest: checks for the existence of a given reader - kvkd: A daemon for German medical cards (used by GNUMed) 6. Documentation ================= For a more complete documentation please have a look at the "doc/html" folder. I also provide some manpages: - libchipcard.conf (5) describes the general format of the configuration files - chipcardc.conf (5) describes the client configuration file - chipcardd.conf (5) describes the server configuration file - manpages for all included tools (mosty courtesy of Thomas Viehmann, who is also the maintainer of the Debian packages) Martin Preuss Hamburg, Germany, Apr 10, 2003