279 lines
12 KiB
Plaintext
279 lines
12 KiB
Plaintext
.. 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 <morgner@informatik.hu-berlin.de>`_
|
|
- `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
|
|
: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
|