.. highlight:: sh .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. _ccid-emulator: ################################################################################ @PACKAGE_NAME@ ################################################################################ .. sidebar:: @PACKAGE_SUMMARY@ :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 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 @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`` | | 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 @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. .. tikz:: Software stack of the @PACKAGE_NAME@ 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 @PACKAGE_NAME@ has the following dependencies: - Linux Kernel with GadgetFS_ - OpenSC_ 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. .. 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 @PACKAGE_NAME@ 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 `_. 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 `_. ***** 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`: https://github.com/frankmorgner/OpenSC .. _`libccid`: https://ccid.apdu.fr/ .. _`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