
                                 Content
                 --------------------------------------------
                 1. Introduction
                 2. Needed Components
                 3. Server Setup
                 4. Starting The Daemon
                 5. Server Environment Variables
                 6. Client Setup
                 7. Using Libchipcard2 in your own Projects
                 8. Remote Drivers
                 9. Using OpenSC with Libchipcard2
                 10. Using Libchipcard2 With MacOS
                 11. Using the OpenSource Generic CCID Driver
                 --------------------------------------------



1. Introduction
===============

This is the server and the client part of Libchipcard2.

Since 2005/01/02 Libchipcard2 contains both the packages chipcard2-server and
chipcard2-client.



2. Needed Components
====================

Libchipcard2 needs the following packages:
- Gwenhywfar http://gwenhywfar.sf.net/          [required]
- LibUSB     http://libusb.sf.net/              [strongly recommended]
- LibSysFS   http://linux-diag.sf.net/          [recommended]
- OpenSC     http://www.opensc.org/             [optional]

If LibUSB is available at compile time it will be used to scan the USB bus
for new devices. Fortunately LibUSB is ported to the major *nix-alike 
systems ;-)
If LibUSB is missing autoconfiguration of USB devices is not possible.

For devices which use a /dev/ttyUSBx device the procfs file 
"/proc/tty/driver/usb-serial" or "/proc/tty/driver/usbserial" is used.
However, revent kernels (2.6.x) only allow root to view these files, so
for these systems LibSysFS (part of sysfsutils) is needed.

If OpenSC is installed then the OpenSC-driver for Libchipcard2 is built and
installed. This driver allows OpenSC to use Libchipcard.


3. Server Setup
===============

The chipcard daemon uses the configuration file 
    $PREFIX/etc/chipcard2-server/chipcardd2.conf

This file contains a description of which drivers to load and a list of
configured readers.

You can copy one of the example files installed to 
"$PREFIX/etc/chipcard2-server/". For USB-only readers the minimal example
can be used. For serial devices the file "chipcardd2.conf.example" can be used
as a starting point.


3.1. Security Mode
------------------

The underlying IPC (interprocess communication) model used allows a variety
of security modes:
 
 a) local
    This mode uses Unix Domain Sockets. These sockets are only available on
    POSIX systems (not on WIN32 platforms), they can only be connected to from
    the very same machine.
    This is the recommended mode for local-only usage.
    
 b) public
    This mode uses simple TCP sockets for IPC. You should not use this mode
    since it does not provide any encryption.
 
 c) private
    This mode uses SSL secured sockets. This is the recommended mode on
    systems where there are no Unix Domain Sockets (i.e. the "local" mode is
    not available).
    
 d) secure
    This mode is the same as "private", but it requires the client to present
    a valid certificate. This certificate is looked up in a directory on the
    server and if not found access will be denied.
    You can use this mode if you want to be very safe. It also allows the
    server to distinguish between multiple users accessing the server, so that
    administration accounts can be realized (which will only allow special
    users to execute administrative commands).

For security modes "private" and "secure" some additional setup is to be done.
You can do most of that additional setup with the following command:

#>chipcardd2 init

This will create all files necessary for "private" or "secure" mode (such as
Diffie-Hellman-parameters, a self-signed certificate etc).

Please refer to the file doc/CERTIFICATES for details.


3.2. Adding Readers
-------------------

#>chipcardd2 addreader --rname ARG --dtype ARG --rtype ARG --rport ARG

Adds a reader to the configuration. Please see "chipcardd2 --help".



4. Starting The Daemon
======================

"chipcardd2 --help" lists all possible command line arguments.

However, in most cases the following does suffice:

#>chipcardd2 --pidfile PIDFILENAME
where PIDFILENAME is the name of the PID file (used to store the process id
of the server which can be used to send signals to it).


For debugging purposes the following is more usefull:

#>chipcardd2 --pidfile PIDFILENAME -f --logtype console --loglevel notice

For "loglevel" you can use "--loglevel info" to increase the verbosity even
more. 
The option "-f" makes the daemon stay in the foreground. In this case you can
stop it using CTRL-C.



5. Server Environment Variables
===============================


LC_DRIVER_LOGLEVEL
------------------
Loglevel to be used for drivers.


LC_SERVICE_LOGLEVEL
------------------
Loglevel to be used for services.


LC_CTAPI_LOGLEVEL
-----------------
Loglevel to be used by the fake CTAPI.


OPENSC_LOGLEVEL
-----------------
Loglevel to be used by the OpenSC reader driver.



6. Client Setup
===============

Clients for libchipcard2 use the configuration file 
    $PREFIX/etc/chipcard2-client/chipcardc2.conf

This file contains a description of the chipcard2 servers to connect to.



7. Using Libchipcard2 in your own Projects
==========================================

Please have a look at the file in tutorials/. They pretty much explain how
Libchipcard2 can be used.



8. Remote Drivers
=================

As of version 1.9.10 Libchipcard2 supports remote drivers. These drivers are
used on thin clients (as requested by GnuMed).

For this to work you need to enable remote drivers in the server configuration
file ($PREFIX/etc/chipcard2-server/chipcardd2.conf).

Also, you will have to add a "server" section in the server configuration file
which is not "local" (because otherwise the remote driver could not connect
to the server).

The next step is to create a configuration file on the thin client which is
used by the remote driver daemon 
     $PREFIX/etc/chipcard2-server/chipcardrd.conf

An example file is provided. The driver sections in such a file are nearly the
same as in the server configuration file.



9. Using OpenSC with Libchipcard2
=================================

You can enable this driver with OpenSC by adding the name "chipcard2" to
the OpenSC configuration file variable "app/reader_drivers".
You will also have to add a driver section to that configuration file below
"app":

  ----------------------------------------
  reader_driver chipcard2 {
    module = /usr/lib/reader-libchipcard2;
  }
  ----------------------------------------
  
Such a section allows OpenSC to dynamically load the driver module.



10. Using Libchipcard2 With MacOS
=================================

The following commands will compile Libchipcard2 on MacOS:

--------------------------------------------------------------------------------------
./configure --prefix=/sw LDFLAGS=-L/sw/lib CFLAGS=-I/sw/include CPPFLAGS=-I/sw/include
make
sudo make install
--------------------------------------------------------------------------------------

The configuration files are then expected in /sw/chipcard2-server.



11. Using the OpenSource Generic CCID Driver
============================================

Libchipcard2 1.9.12beta and later has improved support for this GPL licensed
driver. However, since Libchipcard2 uses this driver directly (i.e. without
using PC/SC) you will have to compile the driver youself.
I suggest using version ccid-0.9.3 or better. To *compile* the driver you need
libpcsclite (but don't install the pcscd if you want to work with 
Libchipcard2). After compiling the driver you can safely uninstall
libpcsclite and still use the driver with libchipcard2.

------------------------------------------------------------- X8
./configure (all in one line)
  --disable-pcsclite 
  --enable-usbdropdir=/usr/lib/chipcard2-server/lowlevel/ifd
  --enable-ccidtwindir=/usr/lib/chipcard2-server/lowlevel/ifd
make
make install
------------------------------------------------------------- X8

This allows parallel installation of the non-PCSC version of the driver and
the PCSC version. Libchipcard2 always searches for the CCID driver in its
own lowlevel/ifd folder.



Martin Preuss, Hamburg/Germany, 2005/03/15



