bc8b237c5a
There is no longer an external (or stable) interface for libopensc. Linking this program with an existing version of libopensc that is pre-installed in the system library paths is not practical. However, a specific snapshot of the OpenSC source code is embedded here as a Git submodule (and included in the source distributions). Build libopensc from this and statically link it into this program. (Options such as '--enable-openpace' that are passed to ./configure will be forwarded to control the build configuration of libopensc.) Remove code that existed for compatibility when dynamically linking with older versions of libopensc.
341 lines
15 KiB
Plaintext
341 lines
15 KiB
Plaintext
.. highlight:: sh
|
|
|
|
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
|
|
|
|
.. _ccid-emulator:
|
|
|
|
################################################################################
|
|
USB CCID Emulator
|
|
################################################################################
|
|
|
|
.. sidebar:: Emulate a USB CCID compliant smart card reader
|
|
|
|
: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 OpenSC_
|
|
also |PACE| can be performed by the emulator.
|
|
|
|
.. tikz:: Portable smart card reader with trusted user interface
|
|
:stringsubst:
|
|
:libs: arrows, calc, fit, patterns, plotmarks, shapes.geometric, shapes.misc, shapes.symbols, shapes.arrows, shapes.callouts, shapes.multipart, shapes.gates.logic.US, shapes.gates.logic.IEC, er, automata, backgrounds, chains, topaths, trees, petri, mindmap, matrix, calendar, folding, fadings, through, positioning, scopes, decorations.fractals, decorations.shapes, decorations.text, decorations.pathmorphing, decorations.pathreplacing, decorations.footprints, decorations.markings, shadows
|
|
|
|
\input{$wd/bilder/tikzstyles.tex}
|
|
\tikzstyle{bla}=[kleiner, text width=.45\textwidth]
|
|
|
|
\node (reader)
|
|
{\includegraphics[width=1cm]{$wd/bilder/my_cardreader.pdf}};
|
|
\node (readertext) [right=0of reader, bla]
|
|
{Smartphone provides smart card reader via USB};
|
|
\node (display) [below=0of reader]
|
|
{\includegraphics[width=1cm]{$wd/bilder/display.pdf}};
|
|
\node (displaytext) [right=0of display, bla]
|
|
{Secure display of service provider and purpose of transaction};
|
|
\node (keyboard) [below=0of display]
|
|
{\includegraphics[width=1cm]{$wd/bilder/keyboard.pdf}};
|
|
\node (keyboardtext) [right=0of keyboard, bla]
|
|
{Secure PIN Entry};
|
|
\node (firewall) [below=0of keyboard]
|
|
{\includegraphics[width=1cm]{$wd/bilder/Firewall.pdf}};
|
|
\node (firewalltext) [right=0of firewall, bla]
|
|
{Verification of terminal authentication and sanitiy checks};
|
|
|
|
\node (features) [fit=(display) (keyboard) (reader) (firewall)] {};
|
|
|
|
\node (moko) [left=0of features.west] {\includegraphics[height=4cm]{$wd/bilder/phone-fic-neo-freerunner.pdf}};
|
|
|
|
\node (epa) [left=1.5of moko, yshift=-2cm]
|
|
{\includegraphics[width=3cm]{$wd/bilder/nPA_VS.png}};
|
|
\node (pc) [left=1.5of moko, yshift=1.5cm]
|
|
{\includegraphics[width=3cm]{$wd/bilder/computer-tango.pdf}};
|
|
|
|
\begin{pgfonlayer}{background}
|
|
|
|
\node (mokobox)
|
|
[box,
|
|
fit=(moko) (readertext) (displaytext) (keyboardtext) (firewalltext)
|
|
(features)] {};
|
|
|
|
\draw [usb]
|
|
(moko) -- (pc.center) ;
|
|
\draw [decorate, decoration={expanding waves, angle=20, segment length=6}, nichtrundelinie]
|
|
(moko) -- (epa) ;
|
|
|
|
\end{pgfonlayer}
|
|
|
|
|
|
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.
|
|
|
|
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``
|
|
================================== ============================================================
|
|
|
|
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`` |
|
|
| EstablishPACEChannel | ``0xFF`` | ``0x9A`` | ``0x04`` | ``0x02`` | ``EstablishPACEChannelInput`` | ``EstablishPACEChannelOutput`` | or other |
|
|
+--------------------------+----------+----------+----------+----------+--------------------------------+-----------------------------------+ in case of |
|
|
| DestroyPACEChannel | ``0xFF`` | ``0x9A`` | ``0x04`` | ``0x03`` | (No Data) | (No Data) | an error |
|
|
+--------------------------+----------+----------+----------+----------+--------------------------------+-----------------------------------+ |
|
|
| Verify/Modify PIN | ``0xFF`` | ``0x9A`` | ``0x04`` | ``0x10`` | Coding as ``PC_to_RDR_Secure`` | Coding as ``RDR_to_PC_DataBlock`` | |
|
|
+--------------------------+----------+----------+----------+----------+--------------------------------+-----------------------------------+------------+
|
|
|
|
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.
|
|
|
|
.. tikz:: Software stack of the USB CCID Emulator running on the OpenMoko Neo FreeRunner
|
|
:stringsubst:
|
|
:libs: arrows, calc, fit, patterns, plotmarks, shapes.geometric, shapes.misc, shapes.symbols, shapes.arrows, shapes.callouts, shapes.multipart, shapes.gates.logic.US, shapes.gates.logic.IEC, er, automata, backgrounds, chains, topaths, trees, petri, mindmap, matrix, calendar, folding, fadings, through, positioning, scopes, decorations.fractals, decorations.shapes, decorations.text, decorations.pathmorphing, decorations.pathreplacing, decorations.footprints, decorations.markings, shadows
|
|
|
|
\input{$wd/bilder/tikzstyles.tex}
|
|
\tikzstyle{schicht}=[text width=5cm, align=right]
|
|
\tikzstyle{fade down}=[path fading=south, color=huslateblue]
|
|
|
|
\node (kernel)
|
|
[box, shape=rectangle split, rectangle split parts=3, kleiner]
|
|
{Linux Kernel
|
|
\nodepart{second}
|
|
\footnotesize S3C24xx Controller Driver
|
|
\nodepart{third}
|
|
\footnotesize GadgetFS
|
|
};
|
|
|
|
\node (ccid)
|
|
[aktivbox, shape=rectangle split, rectangle split parts=2, below=of kernel]
|
|
{CCID Emulator
|
|
\nodepart{second}
|
|
\texttt{usb}\qquad\texttt{ccid}
|
|
};
|
|
\draw [box] ($(ccid.text split)-(.05cm,0)$) -- ($(ccid.south)-(.05cm,0)$);
|
|
|
|
\node (opensc) [box, below=of ccid, kleiner] {OpenSC};
|
|
|
|
\node (controller) [klein, right=0of kernel.two east, schicht]
|
|
{Driver for USB Controller};
|
|
\node (gadget) [klein, right=0of kernel.three east, schicht]
|
|
{Gadget Driver};
|
|
\node (upper) [klein, right=0of kernel.three east, schicht, yshift=-1.75cm]
|
|
{Upper Layers};
|
|
|
|
\tikzstyle{rechts}=[to path={-- ++(1,0) |- (\tikztotarget)}]
|
|
\tikzstyle{links}=[to path={-- ++(-1,0) |- (\tikztotarget)}]
|
|
\begin{pgfonlayer}{background}
|
|
\path
|
|
(ccid.two west) edge [links, linie] (kernel.three west)
|
|
(ccid.two east) edge [rechts, linie] (opensc.east)
|
|
;
|
|
|
|
\path [color=black!30]
|
|
(controller.north east) edge +(-9,0)
|
|
(gadget.north east) edge +(-9,0)
|
|
(upper.north east) edge +(-9,0)
|
|
;
|
|
\end{pgfonlayer}
|
|
|
|
\node [kleiner, anchor=east, text width=3cm]
|
|
at ($($(ccid.two west)+(-3,0)$)!.5!(kernel.three west)$)
|
|
{\color{hublue}
|
|
\texttt{/dev/gadget/ep1-bulk}\\
|
|
\texttt{/dev/gadget/ep2-bulk}\\
|
|
\texttt{/dev/gadget/ep3-bulk}\\};
|
|
|
|
|
|
Running the USB CCID Emulator has the following dependencies:
|
|
|
|
- Linux Kernel with GadgetFS_
|
|
- OpenSC_
|
|
|
|
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.
|
|
|
|
.. tikz:: Implementation of a mobile smart card reader for the German ID card
|
|
:stringsubst:
|
|
:libs: arrows, calc, fit, patterns, plotmarks, shapes.geometric, shapes.misc, shapes.symbols, shapes.arrows, shapes.callouts, shapes.multipart, shapes.gates.logic.US, shapes.gates.logic.IEC, er, automata, backgrounds, chains, topaths, trees, petri, mindmap, matrix, calendar, folding, fadings, through, positioning, scopes, decorations.fractals, decorations.shapes, decorations.text, decorations.pathmorphing, decorations.pathreplacing, decorations.footprints, decorations.markings, shadows
|
|
|
|
\input{$wd/bilder/tikzstyles.tex}
|
|
\tikzstyle{keks}=[to path={-- ++(.1,0) |- (\tikztotarget)}]
|
|
|
|
\tikzstyle{bla}=[shape=rectangle split, rectangle split parts=2,
|
|
every text node part/.style={align=center, klein}, text width=7cm,
|
|
every second node part/.style={kleiner}, inner sep=0pt]
|
|
|
|
\node (ccid-emulator)
|
|
{\texttt{ccid-emulator}};
|
|
|
|
\node (basis) [below=3of ccid-emulator]
|
|
{\includegraphics[keepaspectratio, height=2cm,
|
|
width=2cm]{$wd/bilder/moko/basisleser_plain_klein.png}};
|
|
\node (basisbeschreibung) [below=0cm of basis, kleiner, text width=2cm]
|
|
{Reiner SCT RFID basis};
|
|
|
|
\node (npa) [left=1.5of basis]
|
|
{\includegraphics[keepaspectratio, height=3cm,
|
|
width=3cm]{$wd/bilder/nPA_VS.png}};
|
|
\node (npabeschreibung) [below=0cm of npa, kleiner]
|
|
{German identity card};
|
|
|
|
\node (funktionenchat) [right=.6cm of ccid-emulator.east, anchor=text west, bla]
|
|
{
|
|
PACE
|
|
\nodepart{second}
|
|
\begin{itemize}
|
|
|
|
\item Display CHAT
|
|
\begin{itemize}
|
|
\item Display context (eID/eSign)
|
|
\item Display requested permissions
|
|
\end{itemize}
|
|
|
|
\item Display certificate description
|
|
\begin{itemize}
|
|
\item Identification of service provider
|
|
\item Display purpose of transaction
|
|
\end{itemize}
|
|
|
|
\item Secure PIN entry
|
|
\end{itemize}
|
|
};
|
|
\node (funktionenpace) [below=.5 of funktionenchat, bla]
|
|
{
|
|
Terminal Authentication
|
|
\nodepart{second}
|
|
\begin{itemize}
|
|
\item Verify authenticy of terminal
|
|
\item Check freshness of cv certificate
|
|
\end{itemize}
|
|
};
|
|
|
|
\begin{pgfonlayer}{background}
|
|
\node (box) [fit=(ccid-emulator) (basis) (basisbeschreibung)
|
|
(funktionenchat) (funktionenpace), box, inner sep=.5cm] {};
|
|
\node (boxbild) at (box.north west)
|
|
{\includegraphics[keepaspectratio, height=1.5cm,
|
|
width=1.5cm]{$wd/bilder/moko/moko_reader.png}};
|
|
\node [right=0cm of boxbild.east, yshift=.3cm]
|
|
{Openmoko Neo FreeRunner};
|
|
\end{pgfonlayer}
|
|
|
|
\node (a) [above=1of npa]
|
|
{\includegraphics[keepaspectratio, height=3cm,
|
|
width=3cm]{$wd/bilder/computer-tango.pdf}};
|
|
|
|
|
|
\begin{pgfonlayer}{background}
|
|
\path
|
|
(ccid-emulator) edge [doppelpfeil] (basis)
|
|
(basis) edge [rfid] (npa)
|
|
(a.center) edge [usb] (ccid-emulator)
|
|
(ccid-emulator.east) edge [pfeil, keks] (funktionenchat.text west)
|
|
(ccid-emulator.east) edge [pfeil, keks] (funktionenpace.text west);
|
|
\end{pgfonlayer}
|
|
|
|
|
|
.. include:: download.txt
|
|
|
|
|
|
.. include:: autotools.txt
|
|
|
|
The USB CCID Emulator depends on :program:`libopensc`, which is automatically
|
|
built from a snapshot of the OpenSC source code and then statically linked.
|
|
|
|
|
|
=================
|
|
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
|
|
<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>`_.
|
|
|
|
|
|
*****
|
|
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`_. PIN commands are supported if implemented
|
|
by the driver.
|
|
|
|
.. versionadded:: 0.7
|
|
USB CCID Emulator 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`: https://github.com/frankmorgner/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
|