.. 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. 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`` ================================== ============================================================ PIN verification/modification and |PACE| can also be started by the application transmitting (SCardTransmit) specially crafted APDUs. Only the alternative initialization of |PACE| using SCardControl requires patching the driver (available for libccid, see :file:`patches`). The pseudo APDUs with no need for patches are defined as follows (see `BSI TR-03119 1.3`_ p. 33-34): +--------------------------+--------------------------------------------------------------------------------------------+---------------------------------------------+ | | Command APDU | Response APDU | | +----------+----------+----------+----------+------------------------------------------------+--------------------------------+------------+ | | CLA | INS | P1 | P2 | Command Data | Response Data | SW1/SW2 | +==========================+==========+==========+==========+==========+================================================+================================+============+ | GetReaderPACECapabilities| ``0xFF`` | ``0x9A`` | ``0x04`` | ``0x01`` | (No Data) | ``PACECapabilities`` | ``0x9000`` | +--------------------------+----------+----------+----------+----------+------------------------------------------------+--------------------------------+ or other | | EstablishPACEChannel | ``0xFF`` | ``0x9A`` | ``0x04`` | ``0x02`` | ``EstablishPACEChannelInput`` | ``EstablishPACEChannelOutput`` | in case of | +--------------------------+----------+----------+----------+----------+------------------------------------------------+--------------------------------+ an error | | DestroyPACEChannel | ``0xFF`` | ``0x9A`` | ``0x04`` | ``0x03`` | (No Data) | (No Data) | | +--------------------------+----------+----------+----------+----------+------------------------------------------------+--------------------------------+------------+ | Verify/Modify PIN | ``0xFF`` | ``0x9A`` | ``0x04`` | ``0x10`` | Coding as ``abData`` from ``PC_to_RDR_Secure`` | Coding as ``RDR_to_PC_DataBlock`` | +--------------------------+----------+----------+----------+----------+------------------------------------------------+---------------------------------------------+ 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`. Here is how to get a running version of GadgetFS on a Debian system (see also `OpenMoko Wiki`_):: sudo apt-get install linux-source linux-headers-`uname -r` sudo tar xjf /usr/src/linux-source-*.tar.bz2 cd linux-source-*/drivers/usb/gadget # build dummy_hcd and gadgetfs echo "KDIR := /lib/modules/`uname -r`/build" >> Makefile echo "PWD := `pwd`" >> Makefile echo "obj-m := dummy_hcd.o gadgetfs.o" >> Makefile echo "default: " >> Makefile echo -e "\t\$(MAKE) -C \$(KDIR) SUBDIRS=\$(PWD) modules" >> Makefile make # load GadgetFS with its dependencies sudo modprobe udc-core sudo insmod ./dummy_hcd.ko sudo insmod ./gadgetfs.ko default_uid=`id -u` # mount GadgetFS sudo mkdir /dev/gadget sudo mount -t gadgetfs gadgetfs /dev/gadget 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`_. PIN commands are supported if implemented by the driver. .. versionadded:: 0.7 @PACKAGE_NAME@ now supports the boxing commands defined in `BSI TR-03119 1.3`_. .. 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 .. _`BSI TR-03119 1.3`: https://www.bsi.bund.de/DE/Publikationen/TechnischeRichtlinien/tr03119/index_htm.html