.. highlight:: sh

.. _OpenSC: http://www.opensc-project.org/opensc
.. _GadgetFS: http://www.linux-usb.org/gadget/
.. _libccid: http://pcsclite.alioth.debian.org/ccid.html


*************
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 and on the source code of the OpenSC_ tools.


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

.. include:: autotools.rst

ccid as the following dependencies:

- Linux Kernel with GadgetFS_
- OpenSC_
- :ref:`npa` (only if support for PACE is enabled)


-----------------
Hints on GadgetFS
-----------------

To create an USB Gadget in both USB host and USB client mode, you need to load
the kernel module :program:`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
<http://docs.openmoko.org/trac/ticket/2206>`_. If you also want to switch
multiple times between :program:`gadgetfs` and :program:`g_ether`, `another patch is needed
<http://docs.openmoko.org/trac/ticket/2240)>`_.

If you are using a more recent version of :program:`dummy_hcd` and get an error
loading the module, 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 :file:`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