141 lines
5.3 KiB
Plaintext
141 lines
5.3 KiB
Plaintext
.. highlight:: sh
|
|
|
|
.. |libnpa| replace:: :ref:`libnpa`
|
|
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
|
|
|
|
.. _ccid-emulator:
|
|
|
|
################################################################################
|
|
USB CCID Emulator
|
|
################################################################################
|
|
|
|
:Author:
|
|
`Frank Morgner <morgner@informatik.hu-berlin.de>`_
|
|
: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
|
|
<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 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.
|