updated documentation
This commit is contained in:
Frank Morgner
@@ -134,9 +134,7 @@ submodules::
|
||||
|
||||
git clone https://github.com/frankmorgner/vsmartcard.git
|
||||
cd vsmartcard
|
||||
# fetch the applets that are in the submodules
|
||||
git submodule init
|
||||
git submodule update
|
||||
git submodule update --init --recursive
|
||||
|
||||
We use `Android Studio`_ to build and deploy the application. Use
|
||||
:menuselection:`File --> Open` to select :file:`vsmartcard/ACardEmulator`.
|
||||
|
||||
@@ -168,12 +168,6 @@ tools.
|
||||
\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.
|
||||
@@ -266,7 +260,12 @@ modern Windows and Unix-like systems by default.
|
||||
.. 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.
|
||||
built from a snapshot of the OpenSC_ source code and then statically linked.
|
||||
|
||||
Running the USB CCID Emulator has the following dependencies:
|
||||
|
||||
- Linux Kernel with GadgetFS_
|
||||
- OpenSSL_ 1.0.0 or later
|
||||
|
||||
|
||||
=================
|
||||
@@ -334,6 +333,7 @@ Notes and References
|
||||
|
||||
.. _`GadgetFS`: http://www.linux-usb.org/gadget/
|
||||
.. _`OpenSC`: https://github.com/frankmorgner/OpenSC
|
||||
.. _`OpenSSL`: https://www.openssl.org
|
||||
.. _`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
|
||||
|
||||
@@ -61,17 +61,17 @@ have a look at these programming guides and try yourself:
|
||||
|
||||
virtualsmartcard/api
|
||||
|
||||
.. image:: https://img.shields.io/travis/frankmorgner/vsmartcard/master.svg?label=Travis%20CI%20build
|
||||
:target: https://travis-ci.org/frankmorgner/vsmartcard
|
||||
:alt: Travis CI Build Status Image
|
||||
.. image:: https://img.shields.io/github/actions/workflow/status/frankmorgner/vsmartcard/ci.yml?branch=master&label=Ubuntu%2FmacOS&logo=github
|
||||
:target: https://github.com/frankmorgner/vsmartcard/actions/workflows/ci.yml?branch=master
|
||||
:alt: GitHub CI status
|
||||
|
||||
.. image:: https://img.shields.io/appveyor/ci/frankmorgner/vsmartcard/master.svg?label=AppVeyor%20build
|
||||
:target: https://ci.appveyor.com/project/frankmorgner/vsmartcard
|
||||
:alt: AppVeyor CI Build Status Image
|
||||
:alt: AppVeyor CI status
|
||||
|
||||
.. image:: https://img.shields.io/coverity/scan/3987.svg?label=Coverity%20scan
|
||||
:target: https://scan.coverity.com/projects/3987
|
||||
:alt: Coverity Scan Status
|
||||
:alt: Coverity Scan status
|
||||
|
||||
|
||||
Download
|
||||
|
||||
@@ -16,7 +16,7 @@ PC/SC Relay
|
||||
|
||||
Welcome to PC/SC Relay. The purpose of PC/SC Relay is to relay a smart
|
||||
card using an contact-less interface. Currently the following contact-less
|
||||
emulators are supported:
|
||||
**emulators** are supported:
|
||||
|
||||
- `Hardware supported by libnfc`_
|
||||
- OpenPICC_
|
||||
@@ -24,7 +24,7 @@ emulators are supported:
|
||||
|
||||
Command APDUs are received with the contact-less interface and relayed. The
|
||||
Response APDUs are then sent back via RFID. The contact-less data will be
|
||||
relayed to one of the following:
|
||||
relayed to one of the following **connectors**:
|
||||
|
||||
- to a *real* smart card inserted into one of the systems' smart card readers.
|
||||
The smart card reader must be accessible with PC/SC. The smart card may be
|
||||
@@ -33,6 +33,32 @@ relayed to one of the following:
|
||||
smart card's native interface is used and (despite its name) PC/SC Relay
|
||||
does not need to access PC/SC in this case.
|
||||
|
||||
..
|
||||
http://www.plantuml.com/plantuml/txt/SoWkIImgAStDuNBDBSr9BCalKj2rKr0gI2vErYrApKciL5AmKd3EpyrDp4jHS0nm2UL2bWEg1KhcvQKc0pLoGLcOHc3eWTjbfH2KMboGdrUS2Z7S8JKl1UWO0000
|
||||
|
||||
@startuml
|
||||
skinparam responseMessageBelowArrow true
|
||||
Emulator -> "pcsc-relay" : Command APDU
|
||||
"pcsc-relay" -> Connector
|
||||
Connector -> "pcsc-relay"
|
||||
"pcsc-relay" -> Emulator : Response APDU
|
||||
@enduml
|
||||
|
||||
::
|
||||
|
||||
┌────────┐ ┌──────────┐ ┌─────────┐
|
||||
│Emulator│ │pcsc-relay│ │Connector│
|
||||
└───┬────┘ └────┬─────┘ └────┬────┘
|
||||
│ Command APDU │ │
|
||||
│ ───────────────────> │
|
||||
│ │ ───────────────────>│
|
||||
│ │ <───────────────────│
|
||||
│ Response APDU │ │
|
||||
│ <─────────────────── │
|
||||
┌───┴────┐ ┌────┴─────┐ ┌────┴────┐
|
||||
│Emulator│ │pcsc-relay│ │Connector│
|
||||
└────────┘ └──────────┘ └─────────┘
|
||||
|
||||
.. tikz:: Debug, Analyze and Emulate with PC/SC Relay
|
||||
: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
|
||||
|
||||
@@ -103,7 +103,7 @@ Depending on your usage of the |vpicc| you may need to install the following:
|
||||
|
||||
- Python_
|
||||
- pyscard_ (relaying a local smart card with `--type=relay`)
|
||||
- PyCryptodome_, PBKDF2_, PIL_, readline_ or PyReadline_ (emulation of electronic
|
||||
- PyCryptodome, PBKDF2_, PIL_, readline_ or PyReadline_ (emulation of electronic
|
||||
passport with `--type=ePass`)
|
||||
- OpenPACE_ (emulation of German identity card with `--type=nPA`)
|
||||
- libqrencode_ (to print a QR code on the command line for `vpcd-config`; an
|
||||
@@ -145,11 +145,15 @@ Building and installing |vpcd| on Windows
|
||||
PC/SC.
|
||||
|
||||
For the Windows integration we extended `Fabio Ottavi's UMDF Driver for a
|
||||
Virtual Smart Card Reader`_ with a |vpcd| interface. To build |vpcd| for
|
||||
Windows we use `Windows Driver Kit 10 and Visual Studio 2015`_. The vpcd
|
||||
installer requires the `WiX Toolset 3.10`_. If you choose
|
||||
Virtual Smart Card Reader`_ with a |vpcd| interface. If you choose
|
||||
to download the `Windows binaries`_, you may directly jump to step 4.
|
||||
|
||||
In the CI environment, we're building |vpcd| for Windows with Visual Studio
|
||||
Community 2019 with SDK/WDK for Windows 11. (The WDK version needs to match
|
||||
at least your targeted version of Windows, see this `guide for installing VS
|
||||
with WDK`_) The vpcd installer additionally
|
||||
requires the `WiX Toolset 3.10`_ to be installed.
|
||||
|
||||
1. Clone the git repository and make sure it is initialized with all
|
||||
submodules::
|
||||
|
||||
@@ -166,10 +170,21 @@ to download the `Windows binaries`_, you may directly jump to step 4.
|
||||
the installer (:file:`BixVReaderInstaller.msi`) in
|
||||
:file:`virtualsmartcard\\win32\\BixVReaderInstaller\\bin\\*Release`
|
||||
|
||||
4. To install |vpcd|, double click :file:`BixVReaderInstaller.msi`. Since we
|
||||
are currently not signing the Installer, this will yield a warning about an
|
||||
unverified driver software publisher on Windows 8 and later. Click
|
||||
:guilabel:`Install this driver software anyway`.
|
||||
4. To import the installer's test signing certificate, double click
|
||||
:file:`BixVReader.cer` and add it to the *Trusted Root Certification
|
||||
Authority* and the *Trusted Publishers* at the *Local Computer" (not the
|
||||
*Current User*).
|
||||
|
||||
On the commandline, you could do this :ref:`as follows<Using CertMgr to
|
||||
Install Test Certificates on a Test Computer>`::
|
||||
|
||||
CertMgr.exe /add BixVReader.cer /s /r localMachine root /all
|
||||
CertMgr.exe /add BixVReader.cer /s /r localMachine trustedpublisher
|
||||
|
||||
Feel free to remove the certificate from the certificate stores once the
|
||||
device is installed.
|
||||
|
||||
5. To install |vpcd|, double click :file:`BixVReaderInstaller.msi`.
|
||||
|
||||
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
|
||||
@@ -300,6 +315,38 @@ through the PC/SC API. You can use the :command:`opensc-explorer` or
|
||||
provide scripts for testing with npa-tool_ and PCSC-Lite's smart card
|
||||
reader driver tester.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
Testing |vpicc| -t ePass
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
A simple tool to test |BAC| is available for Python 2.7. On Ubuntu, its
|
||||
requiremets are installed as follows::
|
||||
|
||||
sudo apt-get install python2.7-dev
|
||||
curl https://bootstrap.pypa.io/pip/2.7/get-pip.py -o get-pip.py
|
||||
python2.7 get-pip.py
|
||||
python2.7 -m pip install pycryptodomex pyscard
|
||||
python2.7 readpass.py --no-gui
|
||||
git clone https://github.com/henryk/cyberflex-shell
|
||||
cd cyberflex-shell
|
||||
|
||||
Now we can create and run a small script::
|
||||
|
||||
echo "select_application a0000002471001" > script.txt
|
||||
echo "perform_bac L898902C<3UTO6908061F9406236ZE184226B<<<<<14" >> script.txt
|
||||
python2.7 cyberflex-shell.py script.txt
|
||||
|
||||
The tool will wait for a (virtual) smart card to appear. Start |vpicc| and make
|
||||
sure to configure it with the correct MRZ, i.e.
|
||||
``P<UTOERIKSSON<<ANNA<MARIX<<<<<<<<<<<<<<<<<<<L898902C<3UTO6908061F9406236ZE184226B<<<<<14``
|
||||
in this case::
|
||||
|
||||
vicc -t ePass
|
||||
|
||||
Once the card is connected, ``cyberflex-shell`` will quickly perform |BAC| and
|
||||
exit. Running the tool without arguments allows entering in interactive mode
|
||||
to run additional tests.
|
||||
|
||||
|
||||
.. include:: questions.txt
|
||||
|
||||
@@ -322,7 +369,8 @@ Notes and References
|
||||
.. _OpenPACE: https://github.com/frankmorgner/openpace
|
||||
.. _libqrencode: https://fukuchi.org/works/qrencode/
|
||||
.. _`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 10 and Visual Studio 2015`: https://msdn.microsoft.com/en-us/library/windows/hardware/ff557573
|
||||
.. _`guide for installing VS with WDK`: https://learn.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk
|
||||
.. _`WiX Toolset 3.10`: https://wixtoolset.org/releases/v3.10/stable
|
||||
.. _`Windows binaries`: https://github.com/frankmorgner/vsmartcard/releases/download/virtualsmartcard-0.7/virtualsmartcard-0.7_win32.zip
|
||||
.. _`Windows binaries`: https://github.com/frankmorgner/vsmartcard/releases/tag/virtualsmartcard-0.8
|
||||
.. _npa-tool: https://github.com/frankmorgner/OpenSC
|
||||
.. _`Using CertMgr to Install Test Certificates on a Test Computer`: https://docs.microsoft.com/en-us/windows-hardware/drivers/install/using-certmgr-to-install-test-certificates-on-a-test-computer
|
||||
|
||||
@@ -1,10 +0,0 @@
|
||||
HandlerTest Module
|
||||
==================
|
||||
|
||||
.. inheritance-diagram:: virtualsmartcard.cards.HandlerTest
|
||||
.. automodule:: virtualsmartcard.cards.HandlerTest
|
||||
:members:
|
||||
:undoc-members:
|
||||
:inherited-members:
|
||||
:show-inheritance:
|
||||
:private-members:
|
||||
@@ -1,10 +0,0 @@
|
||||
Relay Module
|
||||
============
|
||||
|
||||
.. inheritance-diagram:: virtualsmartcard.cards.Relay
|
||||
.. automodule:: virtualsmartcard.cards.Relay
|
||||
:members:
|
||||
:undoc-members:
|
||||
:inherited-members:
|
||||
:show-inheritance:
|
||||
:private-members:
|
||||
@@ -1,10 +0,0 @@
|
||||
RelayMiddleman Module
|
||||
=====================
|
||||
|
||||
.. inheritance-diagram:: virtualsmartcard.cards.RelayMiddleman
|
||||
.. automodule:: virtualsmartcard.cards.RelayMiddleman
|
||||
:members:
|
||||
:undoc-members:
|
||||
:inherited-members:
|
||||
:show-inheritance:
|
||||
:private-members:
|
||||
@@ -1,10 +0,0 @@
|
||||
CardGenerator_test Module
|
||||
=========================
|
||||
|
||||
.. inheritance-diagram:: virtualsmartcard.tests.CardGenerator_test
|
||||
.. automodule:: virtualsmartcard.tests.CardGenerator_test
|
||||
:members:
|
||||
:undoc-members:
|
||||
:inherited-members:
|
||||
:show-inheritance:
|
||||
:private-members:
|
||||
@@ -1,10 +0,0 @@
|
||||
CryptoUtils_test Module
|
||||
=======================
|
||||
|
||||
.. inheritance-diagram:: virtualsmartcard.tests.CryptoUtils_test
|
||||
.. automodule:: virtualsmartcard.tests.CryptoUtils_test
|
||||
:members:
|
||||
:undoc-members:
|
||||
:inherited-members:
|
||||
:show-inheritance:
|
||||
:private-members:
|
||||
@@ -1,10 +0,0 @@
|
||||
SmartcardSAM_test Module
|
||||
========================
|
||||
|
||||
.. inheritance-diagram:: virtualsmartcard.tests.SmartcardSAM_test
|
||||
.. automodule:: virtualsmartcard.tests.SmartcardSAM_test
|
||||
:members:
|
||||
:undoc-members:
|
||||
:inherited-members:
|
||||
:show-inheritance:
|
||||
:private-members:
|
||||
@@ -1,10 +0,0 @@
|
||||
tests Package
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
|
||||
virtualsmartcard.tests.CardGenerator_test
|
||||
virtualsmartcard.tests.CryptoUtils_test
|
||||
virtualsmartcard.tests.SmartcardSAM_test
|
||||
virtualsmartcard.tests.utils_test
|
||||
|
||||
@@ -1,10 +0,0 @@
|
||||
utils_test Module
|
||||
=================
|
||||
|
||||
.. inheritance-diagram:: virtualsmartcard.tests.utils_test
|
||||
.. automodule:: virtualsmartcard.tests.utils_test
|
||||
:members:
|
||||
:undoc-members:
|
||||
:inherited-members:
|
||||
:show-inheritance:
|
||||
:private-members:
|
||||
Reference in New Issue
Block a user