/** @mainpage

Welcome to ccid-emulator.  The purpose of ccid-emulator is to forward a PCSC
smartcard reader as a standard USB CCID reader. If the host system is in USB
device mode, ccid-emulator forwards the local reader via USB to an other
device. If in USB host mode, ccid-emulator virtually plugges in a USB CCID
reader to the host system.  ccid-emulator has support for Password
Authenticated Connection Establishment (PACE) using OpenPACE
(http://sourceforge.net/projects/openpace/).

ccid-emulator is implemented using GadgetFS. Some fragments of the source code
is based on the GadgetFS example at http://www.linux-usb.org/gadget/ and on the
source code of the OpenSC tools.


@section i INSTALLATION

See file INSTALL.


@subsection g HINTS ON GADGETFS

To create an USB Gadget in both USB host and USB client mode, you need to load
the kernel module gadgetfs. A guide focused on Debian based systems to run and
compile gadgetfs, you can find here:
http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module

On OpenMoko it is likely, that you need to patch your kernel (see
http://docs.openmoko.org/trac/ticket/2206). If you also want to switch multiple
times between gadgetfs and g_ether an other patch is needed (see
https://docs.openmoko.org/trac/ticket/2240).


@subsection o HINTS ON OPENSC

ccid-emulator links against libopensc, which is discouraged and hindered since
opensc>=0.12. We really need to get rid of this dependency. But so far we
manually build it to have libopensc for linking. The good thing is that you
don't need any opensc components to be installed. The bad thing is, that
ccid-emulator configures and builds opensc on its own. So you might need to
pass some extra configure options to opensc. So if you need to pass options to
opensc, use something like the following command:
./configure \
    OPENSC_CONFIGURE="options"


@subsection l HINTS ON LIBPACE

If you have a local build of libpace and OpenPACE, that you want to link
against use something like the following command:
./configure \
    OPENSSL_CFLAGS="-I/path/to/openssl-1.0.0c_with_openpace-0.4/include" \
    LIBPACE_CFLAGS="-I/path/to/openssl-1.0.0c_with_openpace-0.4/include -I/path/to/libpace-0.1/src" \
    OPENSSL_LIBS="-L/path/to/openssl-1.0.0c_with_openpace-0.4 -lcrypto" \
    LIBPACE_LIBS="-L/path/to/openssl-1.0.0c_with_openpace-0.4 -lcrypto -L/path/to/libpace-0.1/src/.libs -lpace"


@section u USAGE

ccid-emulator has various command line options to customize the appearance on
the USB host. To run ccid-emulator GadgetFS must be loaded and mounted.
ccid-emulator is compatible with the unix driver libccid and the windows smart
card driver. To initialize PACE using the PC/SC API you need to patch libccid
and pcsc-lite (see directory patches).

cats-test can be used to test the PACE capabilities of a smart card reader with
PACE support (such as ccid-emulator or any other "Standardleser" CAT-S or
"Komfortleser" CAT-C) via PC/SC.


@section q QUESTIONS
For questions, please use http://sourceforge.net/projects/vsmartcard/support

@author Frank Morgner <morgner@informatik.hu-berlin.de>
*/