.. highlight:: sh .. |libnpa| replace:: :ref:`libnpa` .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. _ccid-emulator: ################################################################################ USB CCID Emulator ################################################################################ :Author: `Frank Morgner `_ :License: GPL version 3 :Tested Platforms: Linux (Debian, Ubuntu, OpenMoko) The USB CCID Emulator forwards a locally present PC/SC smart card reader as a standard USB CCID reader. USB CCID Emulator can be used as trusted intermediary enabling secure PIN entry and PIN modification. In combination with the |libnpa| also |PACE| can be performed by the emulator. If the machine running :command:`ccid-emulator` is in USB device mode, a local reader is forwareded via USB to another machine. If in USB host mode, the USB CCID reader will locally be present. Applications on Windows and Unix-like systems can access the USB CCID Emulator through PC/SC as if it was a real smart card reader. No installation of a smart card driver is required since USB CCID drivers are usually shipped with the modern OS. [#f1]_ Here is a subset of USB CCID commands supported by the USB CCID Emulator with their PC/SC counterpart: ================================== ============================================================ USB CCID PC/SC ================================== ============================================================ ``PC_to_RDR_XfrBlock`` ``SCardTransmit`` ``PC_to_RDR_Secure`` ``FEATURE_VERIFY_PIN_DIRECT``, ``FEATURE_MODIFY_PIN_DIRECT`` ``PC_to_RDR_Secure`` (proprietary) ``FEATURE_EXECUTE_PACE`` ================================== ============================================================ The USB 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. .. include:: download.txt .. include:: autotools.txt Running the USB CCID Emulator has the following dependencies: - Linux Kernel with GadgetFS_ - OpenSC_ - |libnpa| (only if support for |PACE| is enabled) Whereas using the USB CCID Emulator on the host system as smart card reader only needs a usable PC/SC middleware with USB CCID driver. This is the case for most modern Windows and Unix-like systems by default. ================= Hints on GadgetFS ================= To create a 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 in the `OpenMoko Wiki`_. On OpenMoko it is likely that you need to `patch your kernel `_. If you also want to switch multiple times between :program:`gadgetfs` and :program:`g_ether`, `another patch is needed `_. 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 `_. =============== Hints on OpenSC =============== Without the |libnpa| the USB CCID Emulator needs the OpenSC components to be installed (especially :file:`libopensc.so`). Here is an example of how to get the standard installation of OpenSC without |PACE|:: PREFIX=/tmp/install VSMARTCARD=vsmartcard git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard $VSMARTCARD cd $VSMARTCARD/ccid/src/opensc autoreconf --verbose --install ./configure --prefix=$PREFIX make install && cd - Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to configure the USB CCID Emulator to use it:: cd $VSMARTCARD/ccid ./configure --prefix=$PREFIX OPENSC_LIBS="-L$PREFIX/lib -lopensc" make install && cd - If you want |PACE| support for the emulated smart card reader the process is similar. Install |libnpa| and it should be recognized automatically by the :file:`configure` script. ***** Usage ***** The USB CCID Emulator has various command line options to customize the appearance on the USB host. In order to run the USB CCID Emulator GadgetFS must be loaded and mounted. The USB CCID Emulator is compatible with the unix driver libccid_ and the `Windows USB CCID driver`_. To initialize |PACE| using the PC/SC API you need to patch libccid (see :file:`patches`). On Windows, the USB CCID Emulator currently has no support for |PACE|. .. program-output:: ccid-emulator --help .. include:: questions.txt ******************** Notes and References ******************** .. target-notes:: .. _`GadgetFS`: http://www.linux-usb.org/gadget/ .. _`OpenSC`: http://www.opensc-project.org/opensc .. _`libccid`: http://pcsclite.alioth.debian.org/ccid.html .. _`Windows USB CCID driver`: http://msdn.microsoft.com/en-us/windows/hardware/gg487509 .. _`OpenMoko Wiki`: http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_ .. [#f1] Note that the heavily outdated Windows USB CCID driver does not support secure PIN entry or PIN modification. USB CCID Emulator comes with a patch for libccid to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction.