.. highlight:: sh .. |libnpa| replace:: :ref:`libnpa` .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. _ccid-emulator: ################################################################################ @PACKAGE_NAME@ ################################################################################ :Author: `Frank Morgner `_ :License: GPL version 3 :Tested Platforms: Linux (Debian, Ubuntu, OpenMoko) The @PACKAGE_NAME@ forwards a locally present PC/SC smart card reader as a standard USB CCID reader. @PACKAGE_NAME@ 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 @PACKAGE_NAME@ 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 @PACKAGE_NAME@ 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 @PACKAGE_NAME@ 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 @PACKAGE_NAME@ has the following dependencies: - Linux Kernel with GadgetFS_ - OpenSC_ - |libnpa| (only if support for |PACE| is enabled) Whereas using the @PACKAGE_NAME@ 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 @PACKAGE_NAME@ 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 @PACKAGE_NAME@ 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 @PACKAGE_NAME@ has various command line options to customize the appearance on the USB host. In order to run the @PACKAGE_NAME@ GadgetFS must be loaded and mounted. The @PACKAGE_NAME@ 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 @PACKAGE_NAME@ 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. @PACKAGE_NAME@ 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.