.. highlight:: sh .. |vpicc| replace:: :abbr:`vpicc (virtual smart card)` .. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)` .. |BAC| replace:: :abbr:`BAC (Basic Access Control)` .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. |TA| replace:: :abbr:`TA (Terminal Authenticatation)` .. |CA| replace:: :abbr:`CA (Chip Authentication)` .. |EAC| replace:: :abbr:`EAC (Extended Access Control)` .. _vicc: ################################################################################ @PACKAGE_NAME@ ################################################################################ .. sidebar:: Summary @PACKAGE_SUMMARY@ :Authors: - `Frank Morgner `_ - `Dominik Oepen `_ :License: GPL version 3 :Tested Platforms: - Linux (Debian, Ubuntu, OpenMoko) - Windows @PACKAGE_NAME@ emulates a smart card and makes it accessible through PC/SC. Currently the @PACKAGE_NAME@ supports the following types of smart cards: - Generic ISO-7816 smart card including secure messaging - German electronic identity card (nPA) with complete support for |EAC| (|PACE|, |TA|, |CA|) - German electronic passport (ePass) with complete support for |BAC| - Cryptoflex smart card (incomplete) The |vpcd| is a smart card reader driver for PCSC-Lite_ and the windows smart card service. It allows smart card applications to access the |vpicc| through the PC/SC API. By default |vpcd| opens slots for communication with multiple |vpicc|'s on localhost from port 35963 to port 35972. But the |vpicc| does not need to run on the same machine as the |vpcd|, they can connect over the internet for example. Although the @PACKAGE_NAME@ is a software emulator, you can use :ref:`pcsc-relay` to make it accessible to an external contact-less smart card reader. The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_. .. tikz:: @PACKAGE_NAME@ used with PCSC-Lite :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)s/bilder/tikzstyles.tex} \node (pcsclite) [klein, aktivbox, shape=rectangle split, rectangle split parts=3, inner xsep=3em] {PCSC-Lite \nodepart{second} \footnotesize \texttt{libpcsclite} \nodepart{third} \footnotesize \texttt{pcscd} }; \node (pcsc) [box, kleiner, at=(pcsclite.two west)] {PC/SC}; \node (sca) [aktivbox, klein, left=of pcsc, align=center] {Smart Card\\Application}; \node (vpcd) [box, at=(pcsclite.three east)] {\texttt{vpcd}}; \node (vicc) [aktivbox, right=of vpcd] {\texttt{vicc}}; \begin{pgfonlayer}{background} \path[linie] (sca) edge (pcsc) (vpcd) edge (vicc) ; \end{pgfonlayer} .. versionadded:: 0.7 We implemented |vpcd| as user mode device driver for Windows so that |vpicc| can directly be used in Windows' smart card applications that use PC/SC. .. versionadded:: 0.7 The @PACKAGE_NAME@ optionally brings its own standalone implementation of PC/SC. This allows accessing |vpicc| without PCSC-Lite. Our PC/SC implementation acts as replacement for ``libpcsclite`` which can lead to problems when used in parallel with PCSC-Lite. .. tikz:: @PACKAGE_NAME@ used with its own PC/SC implementation :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)s/bilder/tikzstyles.tex} \node (pcsclite) [box, shape=rectangle split, rectangle split parts=2, inner xsep=3em] {@PACKAGE_NAME@ \nodepart{second} \footnotesize \texttt{libpcsclite} with \texttt{vpcd} }; \node (pcsc) [box, kleiner, at=(pcsclite.two west)] {PC/SC}; \node (sca) [aktivbox, klein, left=of pcsc, align=center] {Smart Card\\Application}; \node (vicc) [aktivbox, right=of pcsclite.two east] {\texttt{vicc}}; \begin{pgfonlayer}{background} \path[linie] (sca) edge (pcsc) (pcsclite.two east) edge (vicc) ; \end{pgfonlayer} .. include:: relay-note.txt .. include:: download.txt .. include:: autotools.txt Depending on your usage of the |vpicc| you might or might not need the following: - Python_ - pyscard_ - PyCrypto_ - PBKDF2_ - PIP_ - OpenPACE_ (nPA emulation) ================================================================================ Building and installing |vpcd| on Windows ================================================================================ For the Windows integration we extended `Fabio Ottavi's UMDF Driver for a Virtual Smart Card Reader`_ with a |vpcd| interface. To build the |vpcd| we use `Windows Driver Kit 8.1 and Visual Studio 2013`_: Hint 1: With VS2013 and WDK 8.1 no WinXP driver can be build. To do this for WinXP, an older VS with WDK 7.1.0 is required. Hint 2: That UMDF Driver for a Virtual Smart Card Reader is written as Win 32 bit code. The Win7 source can be compiled as Win7 64 Bit, but C/C++ builder option needs to be changed! For that go to project properties of "BixVReader" (not for "BixVReader-package"), move to C/C++ settings and switch off the option "/WX (Treat Linker Warnings as Errors)". Otherwise some warnings gets escalated to errors and build will fail on 64 bit. Hint 3: In configuration manager ensure, that both projects are set to same platform = x64 or Win32, no mix with the other !!! Any mix will result into device manager error code 31 for that driver and this error code is NOT related to wrong or missing code signing as given standard answer in internet. Hint 4: The Win7 (64 Bit) build does not need to be signed, during installation Windows will prompt a warning, just allow its installation. Since Win8 it is mandatory to sign the code In case WDK test signing should be used, simply use VS build-in Driver Signing settings. Context menu for "BixVReader-package" -> properties -> Driver Signing -> Sign Mode = "Test Sign". Import the WDKTestCert certificate located in file name `BixVReader-package.cer` into your windows keystore (e.g. on local computer) and then install the driver Please read Microsoft "Kernel-Mode Code Signing Walkthrough". It is a very good document for better understanding. 1. In Visual Studio select :menuselection:`File --> Open --> Convert Sources/Dirs...` and choose the vpcd's :file:`sources` either in the :file:`WinXP` or :file:`Win7` folder. 2. If you can successfully :guilabel:`Build the solution`, you can find the install package in :file:`BixVReader-package`. It contains `BixVReader.inf` and the required libraries, especially `BixVReader.dll`. For 32 bit driver the WudfUpdate_01009.dll will be 1795 KB For 64 bit driver the WudfUpdate_01009.dll will be 2102 KB. 3. Copy :file:`win32\\BixVReader\\BixVReader.ini` into the :envvar:`%SystemRoot%` directory. 4. In a console with administrator rights go to :file:`BixVReader-package` and execute:: on 32 bit system with 32 bit driver: "C:\Program Files\Windows Kits\8.1\Tools\x86\devcon.exe" install BixVReader.inf root\BixVirtualReader on 64 bit system with 64 bit driver: "C:\Program Files\Windows Kits\8.1\Tools\x64\devcon.exe" install BixVReader.inf root\BixVirtualReader You can adjust the path to ``devcon.exe`` with your version of the WDK and your target architecture. For debugging |vpcd| and building the driver with an older version of Visual Studio or WDK please see `Fabio Ottavi's UMDF Driver for a Virtual Smart Card Reader`_ for details. ******************************************************************************** Using the @PACKAGE_NAME@ ******************************************************************************** The protocol between |vpcd| and |vpicc| as well as details on extending |vpicc| with a different card emulator are covered in :ref:`virtualsmartcard-api`. Here we will focus on configuring and running the provided modules. ================================================================================ Configuring |vpcd| on Unix ================================================================================ The configuration file from |vpcd| is usually placed into :file:`/etc/reader.conf.d/`. The PC/SC daemon should read it and load the |vpcd| on startup. In debug mode :command:`pcscd -f -d` should say something like "Attempting startup of Virtual PCD". For older versions of PCSC-Lite you need to run :command:`update-reader.conf` to update :command:`pcscd`'s main configuration file. By default, |vpcd| opens a socket for |vpicc| and waits for incoming connections. The port to open should be specified in ``CHANNELID`` and ``DEVICENAME``: .. literalinclude:: vpcd_example.conf :emphasize-lines: 2,4 If the first part of the ``DEVICENAME`` is different from ``/dev/null``, |vpcd| will use this string as a hostname for connecting to a waiting |vpicc|. |vpicc| needs to be started with :option:`--reversed` in this case. ================================================================================ Configuring |vpcd| on Windows ================================================================================ The configuration file `BixVReader.ini` from |vpcd| is usually placed into :file:`C:\\Windows` (:envvar:`%SystemRoot%`). The PC/SC daemon should read it and load the |vpcd| on startup. The Windows Device Manager should list the :guilabel:`Bix Virtual Smart Card Reader`. |vpcd| opens a socket for |vpicc| and waits for incoming connections. The port to open should be specified in ``TCP_PORT``: .. literalinclude:: BixVReader.ini :emphasize-lines: 8 Currently it is not possible to configure the Windows driver to connect to an |vpicc| running with :option:`--reversed`. ================================================================================ Running |vpicc| ================================================================================ The command :command:`vicc --help` gives an overview about the command line options of |vpicc|. .. program-output:: vicc --help On Windows you can start |vpicc| with :command:`python.exe src/vpicc/vicc.in` or :command:`python.exe vicc`. Notice! actually on Windows |vpicc| can not run in mode `-t nPA` due to some missing python binding, refer to |openPACE|. When |vpcd| and |vpicc| are connected you should be able to access the card through the PC/SC API. You can use the :command:`opensc-explorer` or :command:`pcsc_scan` for testing. In @PACKAGE_NAME@'s root directory we also provide scripts for testing with :ref:`libnpa` and PCSC-Lite's smart card reader driver tester. .. include:: questions.txt ******************** Notes and References ******************** .. target-notes:: .. _cyberflex-shell: https://github.com/henryk/cyberflex-shell .. _PCSC-lite: http://pcsclite.alioth.debian.org/ .. _Python: http://www.python.org/ .. _pyscard: http://pyscard.sourceforge.net/ .. _PyCrypto: http://pycrypto.org/ .. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/ .. _PIP: http://www.pythonware.com/products/pil/ .. _OpenPACE: https://github.com/frankmorgner/openpace .. _`Fabio Ottavi's UMDF Driver for a Virtual Smart Card Reader`: http://www.codeproject.com/Articles/134010/An-UMDF-Driver-for-a-Virtual-Smart-Card-Reader .. _`Windows Driver Kit 8.1 and Visual Studio 2013`: http://msdn.microsoft.com/en-us/windows/hardware/hh852365.aspx