.. highlight:: sh

.. _OpenSC: http://www.opensc-project.org/opensc

*************
ccid-emulator
*************

:Author:
    Frank Morgner <morgner@informatik.hu-berlin.de>
:License:
    GPL version 3
:Tested Platforms:
    Linux (Debian, Ubuntu, OpenMoko)

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 another
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
are based on the GadgetFS example at http://www.linux-usb.org/gadget/ and on the
source code of the OpenSC tools.

=============
Installation
=============

ccid uses the GNU Build System to compile and install. If you are unfamiliar
with it, please have a look at the file ``INSTALL``. If you have a look around
and can not find it, you are probably working bleeding edge in the repository.
Run the following command in the npa direcotry to get the missing standard
auxiliary files::
    
        autoreconf -i

ccid as the following dependencies:

        - OpenSC_
        - libnpa 

------------------
Hints of 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, another patch is needed (see
https://docs.openmoko.org/trac/ticket/2240).

If you are using a more recent version of dummy_hcd, you maybe want to check
out this patch:
http://comments.gmane.org/gmane.linux.usb.general/47440

---------------
Hints on OpenSC
---------------

Without libnpa ccid-emulator links against libopensc, which is discouraged and
hindered since opensc>=0.12. We really need to get rid of this dependency. You
need the opensc components to be installed (especially libopensc.so). Here is
an example of how to get the standard installation of OpenSC_::

    PREFIX=/tmp/install
    OPENSC=opensc
    svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC
    cd $OPENSC
    autoreconf -i
    # adding PKG_CONFIG_PATH here lets OpenSC use OpenSSL with OpenPACE
    ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
    make
    make install

Now ``libopensc.so`` should be located in ``$PREFIX/lib``. Here is how to
configure ccid-emulator to use it::

    ./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc"


=====
Usage
=====

ccid-emulator has various command line options to customize the appearance on
the USB host. In order 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.

=========
Questions
=========

For questions, please use http://sourceforge.net/projects/vsmartcard/support