$Id: README-0.7,v 1.8 2003/04/11 17:05:08 aquamaniac Exp $ LibChipCard 0.7 - Overview ========================== LibChipCard has been totally rewritten to form version 0.7. The major changes are: - the core is now completely written in C (instead of C++), so the size of the library is now a quarter of that of version 0.6.1 (can even be trimmed down to about 700 kB using "strip", this reduces the size of the daemon to less than 150 kB)) - additional C API which is more powerfull than the old C++ API (which is still supported!). This new API allows asynchronous access to the reader. The well known C++ API (CTCard) internally uses the C API. You'll find the C API in "src/libchipcard.h". - introduced a mandatory daemon, which is the only part of libchipcard now to directly communicate with your card readers. That abstracts the client even more from the card readers. Communication is encrypted using RSA and Blowfish. - KCardSetup has been adapted and improved - LibChipCard now uses two configuration files: - "$sysconfdir/chipcardc.conf" for the client - "$sysconfdir/chipcardd.conf" for the daemon (server) where $sysconfdir normally defaults to the "etc" directory within your installation prefix (choosen with "./configure --prefix=XYZ"). Please note that since version 0.7 you need to start the new chipcard daemon (chipcardd) in order to use LibChipCard. Since the daemon uses only non- privileged ports you do not need to be root to do so. The KDE tools are now a separate package. Accessing Card Readers as Non-root ================================== You must make sure that the daily user has read and write access to the appropriate devices in "/dev": - ttyS0 for card readers at port COM1 - ttyS1 for card readers at port COM2 - ttyUSB0, USB1, USB2, USB3 and/or USB4 for USB card readers You can do so by using the following commands (example: ttyS0): chgrp users /dev/ttyS0 (this changes the owner group to "users". This is on most unices the group "normal" users belong to) chmod g+rw /dev/ttyS0 (this gives read and write access to the owner group, so that now the normal user is granted full access to the device) Updating from Previous Versions =============================== Please use the KDE tool "KCardSetup" to create and setup the new configuration files. After that you need to recompile your LibChipCard dependant programs in order to participate in the improvements. After setting up the configuration files you may start the chipcard daemon "chipcardd". Without options it simply reads its configuration file "$sysconfdir/chipcardd.conf" and forks into background. Use the "--help" option for a list of valid options. Please note: - When using the PC/SC daemon (pcscd) from the MUSCLE project you have to start it prior to starting the chipcard daemon chipcardd ! - Since client-server communication is encrypted OpenSSL is now required Porting your Programs to 0.7 ============================ The old C++ API did not change very much. One thing that changed is the constructor of the CTCard (and inheriting) class. Previous versions allowed to provide the so called short name of the card reader to use. This is now obsolete. The current version simply selects the first useable reader. This default behaviour can be changed by using the new method "CTCard::waitForCard". This method allows to select a card reader by - reader type (Towitoko, Kobil, Cyberjack, other), - so called reader flags (these include "hasKeypad", "hasDisplay" and a mask which tells which flags you want the reader to match) - status (such as "isInserted", "isConnected", "isProcessorCard" along with a mask which tells which status you want the reader to match) Another major change is that the class "libChipCard" disappeared. Its functionality is not needed for the current version anymore. Well, version 0.7 internally works asynchronously. To support this feature with the CTCard (C++) API without breaking it I introduced a CALLBACK into CTCard. This callback is called whenever CTCard is waiting for the server's response. This allows updating the GUI of your programs or aborting the current action. Client Server Protocol ====================== All communication between client and server is encrypted, except the first message, which initiates the key transfer. The key exchange protocol looks like this: Client | Server -----------------------------------+---------------------------------------- - connect to the server (TCP) | | - accept the connection, but mark this | connection still logically closed - create a RSA key | - send the public part of the key | to the server (unencrypted) | | - create a Blowfish session key for this | client | - encrypt this key using the public RSA | key provided by the client | - send this encrypted session key | - mark this connection open, so that no | further key exchange is allowed for | this connection - receive the session key and | store it internally for this | session | After that each message will be encrypted using the session key. Each unencrypted message that is received after the completed key exchange will be ignored. Since the session key transferred is encrypted using the clients public RSA key only the client is able to decrypt and use the key. When the key exchange is completed the server will not accept a new key exchange request on this connection. When the connection is lost, the session is closed, thus releasing all ressources used by the client. However, the client automatically (re)connects when needed.