1 2 Content 3 ------------------------------------------------------- 4 1. Introduction 5 2. Needed Components 6 3. Server Setup 7 3.1. Security Mode 8 3.2. Adding Readers 9 3.3. File Permissions 10 4. Starting The Daemon 11 4.1. Disabling Poll Mode 12 5. Server Environment Variables 13 6. Client Setup 14 7. Using Libchipcard in your own Projects 15 8. Using Libchipcard With MacOS 16 9. Special Drivers and Readers 17 9.1. Generic CCID Driver 18 9.2. Reiner SCT Cyberjack 19 9.3. Omnikey CardMan 4000 20 9.4. SCM SPR 532 21 10. Distribution Specific Notes 22 11. Updating from Versions before 3.9.1 23 12. Projects Using Libchipcard 24 ------------------------------------------------------- 25 26 27 281. Introduction 29=============== 30 31Libchipcard is a library for generic access to chipcard readers. It contains 32a complete ressource manager and uses the hardware drivers provided by 33manufacturers of card readers. The number of readers to be used in parallel 34is unbound. 35 36Libchipcard has some advantages over existing card reader ressource managers: 37 - autodetection of readers at multiple buses 38 - readers are only allocated upon request by a client (while no client needs 39 access to a given reader this reader is not accessed by Libchipcard) 40 - it provides a fake CTAPI which can be used by any CTAPI-aware program 41 to use Libchipcard via CTAPI 42 43Libchipcard autodetects and automatically configures readers at the following 44buses: 45 - raw USB 46 - USB serial 47 - PCI 48 - PCMCIA 49 50Libchipcard has been tested by myself with the following readers: 51- Kobil Kaan Advanced USB (works) 52- Towitoko Chipdrive Micro (serial, works) 53- old Reiner SCT Cyberjack (0x100, works) 54- new Reiner SCT Cyberjack (0x300, works) 55- old Reiner SCT Cyberjack ECom (works) 56- new Reiner SCT Cyberjack ECom (works) 57- Omnikey CardMan 3621 (USB, works) 58- Omnikey CardMan 4000 (PCMCIA, works) 59- Cherry G80-1501 (mode 2, works) 60- Cherry G80-1502 (mode 2, works) 61- SCM SCR 3310 (works) 62- SCM SCR 3311 (works) 63- SCM SPR 532 (works with original driver, see 9.4) 64 65 66 672. Needed Components 68==================== 69 70Libchipcard needs the following packages: 71- Gwenhywfar http://gwenhywfar.sf.net/ [required] 72- LibSysFS http://linux-diag.sf.net/ [strongly recommended] 73 74If LibSysFS is available then the PCMCIA scanner code is built. This allows to 75detect PCMCIA-based card readers. This library is also needed to scan for 76USB devices. 77If LibSysFS is missing autoconfiguration of USB devices is not possible. 78 79 80 813. Server Setup 82=============== 83 84The chipcard daemon uses the configuration file 85 $PREFIX/etc/chipcard/server/chipcardd.conf 86 87This file contains a description of which drivers to load and a list of 88configured readers. 89 90You can copy one of the example files installed to 91"$PREFIX/etc/chipcard/server/". For USB-only readers the minimal example 92can be used. For serial devices the file "chipcardd3.conf.example" can be used 93as a starting point. 94 95 963.1. Security Mode 97------------------ 98 99The underlying IPC (interprocess communication) model used allows a variety 100of security modes: 101 102 a) local 103 This mode uses Unix Domain Sockets. These sockets are only available on 104 POSIX systems (not on WIN32 platforms), they can only be connected to from 105 the very same machine. 106 This is the recommended mode for local-only usage. 107 108 b) public 109 This mode uses simple TCP sockets for IPC. You should not use this mode 110 since it does not provide any encryption. 111 112 c) private 113 This mode uses SSL secured sockets. This is the recommended mode on 114 systems where there are no Unix Domain Sockets (i.e. the "local" mode is 115 not available). 116 117 d) secure 118 This mode is the same as "private", but it requires the client to present 119 a valid certificate. This certificate is looked up in a directory on the 120 server and if not found access will be denied. 121 You can use this mode if you want to be very safe. It also allows the 122 server to distinguish between multiple users accessing the server, so that 123 administration accounts can be realized (which will only allow special 124 users to execute administrative commands). 125 126For security modes "private" and "secure" some additional setup is to be done. 127You can do most of that additional setup with the following command: 128 129#>chipcardd init 130 131This will create all files necessary for "private" or "secure" mode (such as 132Diffie-Hellman-parameters, a self-signed certificate etc). 133 134You have to create the server configuration file first (e.g. by just copying 135one of the example files provided by this package). 136 137Please refer to the file doc/CERTIFICATES for details. 138 139 1403.2. Adding Readers 141------------------- 142 143#>chipcardd3 addreader --rname ARG --dtype ARG --rtype ARG --rport ARG 144 145Adds a reader to the configuration. Please see "chipcardd3 --help". 146 147 1483.3. File Permissions 149--------------------- 150 151Some systems (namely Debian) provide packages which start the chipcard daemon 152as a special user ("chipcard") instead of root. 153However, you have to make sure that this special user is able to access the 154card reader (normally he isn't). 155 156 157 1584. Starting The Daemon 159====================== 160 161"chipcardd4 --help" lists all possible command line arguments. 162 163However, in most cases the following does suffice: 164 165#>chipcardd4 --pidfile PIDFILENAME 166where PIDFILENAME is the name of the PID file (used to store the process id 167of the server which can be used to send signals to it). 168 169 170For debugging purposes the following is more usefull: 171 172#>chipcardd4 --pidfile PIDFILENAME -f --logtype console --loglevel notice 173 174For "loglevel" you can use "--loglevel info" to increase the verbosity even 175more. 176The option "-f" makes the daemon stay in the foreground. In this case you can 177stop it using CTRL-C. 178 179 180Please note that the server doesn't start if there is no line in the 181configuration file saying "enabled=1". 182 183 1844.1. Disabling Poll Mode 185------------------------ 186 187The default setting of Libchipcard is to scan every 1-2 seconds for new 188hardware. However, on modern udev-based systems this polling can be avoided 189by setting "hardwareScanInterval" in the section "DeviceManager" of the server 190configuration file "chipcardd.conf" to "0". 191The daemon will then only initially scan for connected hardware. It can be 192notified about hardware changes via signals (SIGUSR2). Upon receiption of this 193signal the daemon immediately scans for new hardware 194(e.g. "killall -SIGUSR2 chipcardd" will trigger a hardware scan). 195 196 197 1985. Server Environment Variables 199=============================== 200 201 202LCDM_DRIVER_LOGLEVEL 203-------------------- 204Loglevel to be used for drivers. 205Version before 1.9.16alpha used LC_DRIVER_LOGLEVEL" instead. 206 207 208LCSV_SERVICE_LOGLEVEL 209--------------------- 210Loglevel to be used for services. 211Version before 1.9.16alpha used "LC_SERVICE_LOGLEVEL" instead. 212 213 214LC_CTAPI_LOGLEVEL 215----------------- 216Loglevel to be used by the fake CTAPI. 217 218 219 220 2216. Client Setup 222=============== 223 224Clients for libchipcard use the configuration file 225 $PREFIX/etc/chipcard/client/chipcardc.conf 226 227This file contains a description of the chipcard servers to connect to. 228 229 230 2317. Using Libchipcard in your own Projects 232========================================== 233 234Please have a look at the file in tutorials/. They pretty much explain how 235Libchipcard can be used. 236 237 238 2398. Using Libchipcard With MacOS 240================================ 241 242The following commands will compile Libchipcard on MacOS: 243 244-------------------------------------------------------------------------------------- 245./configure --prefix=/sw LDFLAGS=-L/sw/lib CFLAGS=-I/sw/include CPPFLAGS=-I/sw/include 246make 247sudo make install 248-------------------------------------------------------------------------------------- 249 250The configuration files are then expected in /sw/chipcard/server. 251 252 253 2549. Special Drivers and Readers 255=============================== 256 257Most USB readers (like Cherry ST-1044u) might need you to add the following 258udev rule to your system (e.g. by creating a file with the following lines 259in /etc/udev/rules.d) when using Debian (or Ubuntu): 260 261-------------------------------------------------------------------X8 262SYSFS{idVendor}=="046a", SYSFS{idProduct}=="002d", GROUP="chipcard" 263-------------------------------------------------------------------X8 264 265This example is for the Cherry reader, for your reader you will have to use 266the correct values for "idVendor" and "idProduct". 267 268 2699.1. Generic CCID Driver 270------------------------- 271 272Libchipcard has improved support for this GPL licensed driver. It can use 273this driver as installed by your distribution (tested with Debian's binary 274packages). 275 276However, if you need to compile the driver yourself some precautions have to 277be taken: 278Recent versions of this driver need libpcsclite installed at build-time, 279but not at runtime. So please do this: 280- install libcpsclite (and devel-packages, if any) 281- compile the driver 282- deinstall libpcsclite (because it might want to start the PC/SC daemon which 283 unfortunately tries to completely take over control over all card readers it 284 can lay its hands on) 285 286It is safe to leave the package libpcsclite on Debian installed, but the 287package containing the PC/SC daemon (pcscd) MUST NOT be installed, because 288that daemon grabs all readers it can find so other daemons (like the quite 289cooperative daemon of Libchipcard) are unable to use them. 290 291 2929.2. Reiner SCT Cyberjack 293-------------------------- 294 295If you are using a Reiner SCT Cyberjack card reader on Debian then you should 296issue the following command to grant libchipcard access to the reader: 297 "gpasswd -a chipcard cyberjack". 298This adds the user "chipcard" (under which the chipcard daemon runs on Debian) 299to the group "cyberjack" thus allowing libchipcard to access this driver. 300 301 3029.3. Omnikey CardMan 4000 303-------------------------- 304 305Current kernels (2.6.17 as of this writing) already include the module needed 306to access the reader at kernel level (module "cm4000_cs"). 307However, you will need the CardMan driver package from Omnikey which contains 308the library "libcm4000.so". 309 310Please download that package from http://www.omnikey.com/. The package 311contains a script called "install". 312 313DO NOT USE THAT! 314 315Just copy the included file "libcm4000.so" to /usr/lib/. That's all. 316 317If your system starts the chipcard server as a user other than root (e.g. 318Debian does this) you should add the following udev rule (e.g. write the 319following line into a file and place it under "/etc/udev/rules.d"): 320 321--------------------------------------------X8 322SUBSYSTEM="cardman_4000", GROUP="chipcard" 323--------------------------------------------X8 324 325This grants Libchipcard access to the cardman as soon as the reader is 326plugged-in. 327 328 3299.4. SCM SPR 532 330---------------- 331 332Libchipcard no longer uses the generic CCID driver for this reader because 333with that driver it is impossible to perform secure verification or 334modification. Therefore we fallback to the driver of the manufacturer. 335However, this needs the reader to have the old firmware 4.15 installed, newer 336versions do not work. 337You can get the driver and firmware from http://www.libchipcard.de/. 338 339 340 34110. Distribution Specific Notes 342=============================== 343 344 34510.1. Debian 346------------ 347 348Debian packages use a special user which runs the chipcard server: "chipcard". 349This user must have the permissions to access the device files needed by the 350different drivers. 351 352 353 35411. Updating from Versions before 3.9.1 355======================================= 356 357Starting with Libchipcard 3.9.1beta all references to the major version have 358been removed. This means that the server configuration is no longer searched 359for in $PREFIX/etc/chipcard3/server but in $PREFIX/etc/chipcard/server 360instead. Also the name of the file has been changed from chipcardd3.conf to 361chipcardd.conf. 362 363This is also true for client configuration files. 364 365 366 36712. Projects Using Libchipcard 368=============================== 369 370The following is a list of projects which use Libchipcard. This list 371is rather incomplete, please contact the author if you want your project 372listed here as well. 373 374 - AqBanking 375 - QBankManager (via AqBanking) 376 - Gnucash (via AqBanking) 377 - KMyMoney (via AqBanking) 378 - Grisbi (via AqBanking) 379 - Gnumed 380 381 382Martin Preuss, Hamburg/Germany, 2007/10/27 383 384 385 386