VivoKey/vsmartcard
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

less clutter in documentation

Browse Source 
- distribute HTML documentation in master branch
- use MD files in project directories for GitHub
- removed some unused autotools files
This commit is contained in:
Frank Morgner
2016-10-08 01:12:09 +02:00
parent 1a86f1ebe0
commit d1cd0ea379
46 changed files with 108 additions and 18021 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
ACardEmulator/README
View File

@@ -1 +0,0 @@
doc/README.txt

26
ACardEmulator/README.md Normal file
View File

@@ -0,0 +1,26 @@
#Android Smart Card Emulator
The Android Smart Card Emulator allows the emulation of a contact-less smart card.
The emulator uses Android's HCE to fetch APDUs from a contact-less reader.
The app allows to process the Command APDUs either by delegating them to a
remote virtual smart card or by a built-in Java Card simulator. The response
APDUs are then returned to the smart card reader.
With the built-in Java Card runtime of [jCardSim](http://www.jcardsim.org/) the
app includes the following Applets:
- [Hello World Applet](https://github.com/licel/jcardsim/blob/master/src/main/java/com/licel/jcardsim/samples/HelloWorldApplet.java) (application identifier ``F000000001``)
- [OpenPGP Applet](https://developers.yubico.com/ykneo-openpgp/) (application identifier ``D2760001240102000000000000010000``)
- [OATH Applet](https://developers.yubico.com/ykneo-oath/) (application identifier ``A000000527210101``)
- [ISO Applet](http://www.pwendland.net/IsoApplet/) (application identifier ``F276A288BCFBA69D34F31001``)
- [GIDS Applet](https://github.com/vletoux/GidsApplet) (application identifier ``A000000397425446590201``)
The remote interface can be used together with the [Virtual Smart
Card](http://frankmorgner.github.io/vsmartcard/virtualsmartcard/README.html),
which allows emulating the following cards:
- Generic ISO-7816 smart card
- German electronic identity card (nPA)
- Electronic passport
Please refer to [our project's website](http://frankmorgner.github.io/vsmartcard/ACardEmulator/README.html) for more information.

2
ACardEmulator/doc/README.txt
View File

@@ -25,7 +25,7 @@ The app allows to process the Command APDUs either by delegating them to a
remote virtual smart card or by a built-in Java Card simulator. The response
APDUs are then returned to the smart card reader.
With the built-in Java Card runtime of jCardSim_ the app includes the follwoing
With the built-in Java Card runtime of jCardSim_ the app includes the following
Applets:
- `Hello World Applet`_ (application identifier ``F000000001``)

1
ccid/AUTHORS
View File

@@ -1 +0,0 @@
Frank Morgner <frankmorgner@gmail.com>

6844
ccid/ChangeLog
View File

File diff suppressed because it is too large Load Diff

10
ccid/Makefile.am
View File

@@ -1,12 +1,4 @@
DISTCHECK_CONFIGURE_FLAGS = --enable-pace
ACLOCAL_AMFLAGS = -I m4
SUBDIRS = src m4 patches doc
distcheck-hook:
test -d .svn && \
svn2cl --group-by-day --reparagraph --separate-daylogs --include-actions --include-rev \
|| true
test -d ../.git && \
git log --pretty --numstat --summary . | git2cl > ChangeLog \
|| true
EXTRA_DIST = docs

0
ccid/NEWS
View File

1
ccid/README
View File

@@ -1 +0,0 @@
doc/README.txt

9
ccid/README.md Normal file
View File

@@ -0,0 +1,9 @@
#USB CCID Emulator
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](https://github.com/frankmorgner/OpenSC) also PACE can be performed by
the emulator.
Please refer to [our project's website](http://frankmorgner.github.io/vsmartcard/ccid/README.html) for more information.

3
ccid/configure.ac
View File

@@ -6,7 +6,7 @@ AC_INIT([USB CCID Emulator], [0.8], [https://github.com/frankmorgner/vsmartcard/
AC_CONFIG_SRCDIR([src/ccid.c])
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_MACRO_DIR([m4])
AM_INIT_AUTOMAKE
AM_INIT_AUTOMAKE(foreign)
AC_USE_SYSTEM_EXTENSIONS
LT_INIT
@@ -74,7 +74,6 @@ AC_TRY_LINK_FUNC(EVP_read_pw_string_min, [ AC_MSG_RESULT([yes]) ], [ AC_MSG_ERRO
CPPFLAGS="$saved_CPPFLAGS"
LIBS="$saved_LIBS"
# --enable-pace
saved_CPPFLAGS="$CPPFLAGS"
saved_LIBS="$LIBS"
PKG_CHECK_EXISTS([libopensc],

2
ccid/doc/Makefile.am
View File

@@ -17,7 +17,7 @@ do_subst = $(SED) \
-e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \
-e 's,[@]top_srcdir[@],$(top_srcdir),g'
EXTRA_DIST = README.txt.in README.txt autotools.txt autotools.txt.in questions.txt questions.txt.in download.txt.in download.txt
EXTRA_DIST = README.txt.in autotools.txt.in questions.txt.in download.txt.in
doc: *.in
$(do_subst) < autotools.txt.in > autotools.txt

374
ccid/doc/README.txt
View File

@@ -1,374 +0,0 @@
.. highlight:: sh
.. |libnpa| replace:: :ref:`libnpa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. _ccid-emulator:
################################################################################
USB CCID Emulator
################################################################################
.. sidebar:: Summary
Emulate a USB CCID compliant smart card reader
:Author:
`Frank Morgner <frankmorgner@gmail.com>`_
: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 the |libnpa|
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)s/bilder/tikzstyles.tex}
\tikzstyle{bla}=[kleiner, text width=.45\textwidth]
\node (reader)
{\includegraphics[width=1cm]{%(wd)s/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)s/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)s/bilder/keyboard.pdf}};
\node (keyboardtext) [right=0of keyboard, bla]
{Secure PIN Entry};
\node (firewall) [below=0of keyboard]
{\includegraphics[width=1cm]{%(wd)s/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)s/bilder/phone-fic-neo-freerunner.pdf}};
\node (epa) [left=1.5of moko, yshift=-2cm]
{\includegraphics[width=3cm]{%(wd)s/bilder/nPA_VS.png}};
\node (pc) [left=1.5of moko, yshift=1.5cm]
{\includegraphics[width=3cm]{%(wd)s/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)s/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] {\texttt{libnpa} or 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_
- |libnpa| (only if support for |PACE| is enabled)
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)s/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)s/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)s/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)s/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)s/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
=================
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>`_.
===============
Hints on OpenSC
===============
Without the |libnpa| the USB CCID Emulator needs the OpenSC components to be
installed (especially :file:`libopensc.so`). Here is an example of how to get
the standard installation of OpenSC without |PACE|::
PREFIX=/tmp/install
VSMARTCARD=$PWD/vsmartcard
git clone https://github.com/frankmorgner/vsmartcard.git $VSMARTCARD
cd $VSMARTCARD
git submodule init
git submodule update
cd $VSMARTCARD/ccid/src/opensc
autoreconf --verbose --install
./configure --prefix=$PREFIX
make install && cd -
Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to
configure the USB CCID Emulator to use it::
cd $VSMARTCARD/ccid
./configure --prefix=$PREFIX OPENSC_LIBS="-L$PREFIX/lib -lopensc"
make install && cd -
If you want |PACE| support for the emulated smart card reader the process is
similar. Install |libnpa| and it should be recognized automatically by the
:file:`configure` script.
*****
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`: http://www.opensc-project.org/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

14
ccid/doc/README.txt.in
View File

@@ -1,6 +1,5 @@
.. highlight:: sh
.. |libnpa| replace:: :ref:`libnpa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. _ccid-emulator:
@@ -22,7 +21,7 @@
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 the |libnpa|
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
@@ -142,7 +141,7 @@ tools.
};
\draw [box] ($(ccid.text split)-(.05cm,0)$) -- ($(ccid.south)-(.05cm,0)$);
\node (opensc) [box, below=of ccid, kleiner] {\texttt{libnpa} or OpenSC};
\node (opensc) [box, below=of ccid, kleiner] {OpenSC};
\node (controller) [klein, right=0of kernel.two east, schicht]
{Driver for USB Controller};
@@ -178,7 +177,6 @@ Running the @PACKAGE_NAME@ has the following dependencies:
- Linux Kernel with GadgetFS_
- OpenSC_
- |libnpa| (only if support for |PACE| is enabled)
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
@@ -312,7 +310,7 @@ loading the module, you maybe want to check out `this patch
Hints on OpenSC
===============
Without the |libnpa| the @PACKAGE_NAME@ needs the OpenSC components to be
@PACKAGE_NAME@ needs the OpenSC components to be
installed (especially :file:`libopensc.so`). Here is an example of how to get
the standard installation of OpenSC without |PACE|::
@@ -334,10 +332,6 @@ configure the @PACKAGE_NAME@ to use it::
./configure --prefix=$PREFIX OPENSC_LIBS="-L$PREFIX/lib -lopensc"
make install && cd -
If you want |PACE| support for the emulated smart card reader the process is
similar. Install |libnpa| and it should be recognized automatically by the
:file:`configure` script.
*****
Usage
@@ -367,7 +361,7 @@ Notes and References
.. target-notes::
.. _`GadgetFS`: http://www.linux-usb.org/gadget/
.. _`OpenSC`: http://www.opensc-project.org/opensc
.. _`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

25
ccid/doc/autotools.txt
View File

@@ -1,25 +0,0 @@
.. highlight:: sh
************
Installation
************
=======================================
Installation on Linux, Unix and similar
=======================================
The USB CCID Emulator uses the GNU Build System to compile and install. If you are
unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
it, you are probably working bleeding edge in the repository. Run the
following command in :file:`ccid-emulator` to get the missing standard
auxiliary files::
autoreconf --verbose --install
To configure (:command:`configure --help` lists possible options), build and
install the USB CCID Emulator now do the following::
./configure
make
make install

14
ccid/doc/download.txt
View File

@@ -1,14 +0,0 @@
.. highlight:: sh
********
Download
********
You can find the latest release of USB CCID Emulator on `Github
<https://github.com/frankmorgner/vsmartcard/releases>`_. Older releases are
still available on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository::
git clone https://github.com/frankmorgner/vsmartcard.git

6
ccid/doc/questions.txt
View File

@@ -1,6 +0,0 @@
********
Question
********
Do you have questions, suggestions or contributions? Feedback of any kind is
more than welcome! Please use our `project trackers <https://github.com/frankmorgner/vsmartcard/issues>`_.

1
ccid/docs Symbolic link
View File

@@ -0,0 +1 @@
../docs/

0
npa/README → npa/README.md
View File

2
pcsc-relay/AUTHORS
View File

@@ -1,2 +0,0 @@
Dominik Oepen <oepen@informatik.hu-berlin.de>

6858
pcsc-relay/ChangeLog
View File

File diff suppressed because it is too large Load Diff

10
pcsc-relay/Makefile.am
View File

@@ -1,12 +1,6 @@
SUBDIRS=src doc win32
EXTRA_DIST = docs
win:
make -C win32 $@
distcheck-hook:
test -d .svn && \
svn2cl --group-by-day --reparagraph --separate-daylogs --include-actions --include-rev \
|| true
test -d ../.git && \
git log --pretty --numstat --summary . | git2cl > ChangeLog \
|| true

0
pcsc-relay/NEWS
View File

1
pcsc-relay/README
View File

@@ -1 +0,0 @@
doc/README.txt

23
pcsc-relay/README.md Normal file
View File

@@ -0,0 +1,23 @@
#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:
- Hardware supported by [libnfc](http://www.libnfc.org/)
- OpenPICC
- [Android Smart Card
Emulator](http://frankmorgner.github.io/vsmartcard/ACardEmulator/README.html)
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:
- 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
contact-based *or* contact-less.
- to a [virtual smart
card](http://frankmorgner.github.io/vsmartcard/ccid/README.html) that
directly connects to `pcsc-relay`. The virtual smart card's native interface
is used and (despite its name) PC/SC Relay does not need to access PC/SC in
this case.

2
pcsc-relay/configure.ac
View File

@@ -6,7 +6,7 @@ AC_INIT([PC/SC Relay], [0.5], [https://github.com/frankmorgner/vsmartcard/issues
AC_CONFIG_SRCDIR([src/pcsc-relay.c])
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_MACRO_DIR([m4])
AM_INIT_AUTOMAKE
AM_INIT_AUTOMAKE(foreign)
dnl Check for windows build
case "${host}" in

2
pcsc-relay/doc/Makefile.am
View File

@@ -17,7 +17,7 @@ do_subst = $(SED) \
-e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \
-e 's,[@]top_srcdir[@],$(top_srcdir),g'
EXTRA_DIST = README.txt.in README.txt autotools.txt.in questions.txt.in autotools.txt questions.txt download.txt.in download.txt relay-note.txt
EXTRA_DIST = README.txt.in autotools.txt.in questions.txt.in download.txt.in relay-note.txt
doc: *.in
$(do_subst) < autotools.txt.in > autotools.txt

301
pcsc-relay/doc/README.txt
View File

@@ -1,301 +0,0 @@
.. highlight:: sh
.. _pcsc-relay:
################################################################################
PC/SC Relay
################################################################################
.. sidebar:: Summary
Relay a smart card to a contactless interface
:Authors:
- `Frank Morgner <frankmorgner@gmail.com>`_
- `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
:License:
GPL version 3
:Tested Platforms:
- Windows
- Linux (Debian, Ubuntu, OpenMoko)
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:
- `Hardware supported by libnfc`_
- OpenPICC_
- :ref:`acardemulator`
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:
- 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
contact-based *or* contact-less.
- to a :ref:`vicc` that directly connects to :command:`pcsc-relay`. The virtual
smart card's native interface is used and (despite its name) PC/SC Relay
does not need to access PC/SC in this case.
.. 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
\input{%(wd)s/bilder/tikzstyles.tex}
\node (pcsc-relay) {\texttt{pcsc-relay}};
\node [kleiner, right=2cm of pcsc-relay, yshift=.9cm]
(libnfc) {Libnfc Devices};
\node [kleiner, right=2cm of pcsc-relay, yshift=.3cm]
(openpicc) {OpenPICC};
\node [kleiner, right=2cm of pcsc-relay, yshift=-.3cm]
(vpcd) {Virtual Smart Card Reader};
\node [kleiner, right=2cm of pcsc-relay, yshift=-.9cm]
(acardemulator) {Android Smart Card Emulator};
\node [kleiner, left=2cm of pcsc-relay, yshift=.9cm]
(contactbased) {Contact-based Smart Card};
\node [kleiner, left=2cm of pcsc-relay, yshift=.3cm]
(contactless) {Contact-less Smart Card};
\node [kleiner, left=2cm of pcsc-relay, yshift=-.9cm]
(remotereader) {Remote Smart Card Reader};
\node [kleiner, left=2cm of pcsc-relay, yshift=-.3cm]
(virtual) {Virtual Smart Card};
\node [above=.3cm of pcsc-relay, kleiner, xshift=1.2cm]
(capdu) {Command APDU};
\node [below=.3cm of pcsc-relay, kleiner, xshift=-1.2cm]
(rapdu) {Response APDU};
\draw (rapdu.east) edge [pfeil] +(1,0);
\draw (capdu.west) edge [pfeil] +(-1,0);
\begin{pgfonlayer}{background}
\path[line width=.5cm,color=hublue!20]
(pcsc-relay.mid) edge [out=180, in=0] (contactbased.east)
edge [out=180, in=0] (contactless.east)
edge [out=180, in=0] (virtual.east)
edge [out=180, in=0] (remotereader.east)
edge [out=0, in=180] (libnfc.west)
edge [out=0, in=180] (openpicc.west)
edge [out=0, in=180] (vpcd.west)
edge [out=0, in=180] (acardemulator.west)
;
\end{pgfonlayer}
With PC/SC Relay you can relay a contact-less or contact based smart card
over a long distance. Also you can use it in combination with the :ref:`vicc`
to completely emulate an ISO/IEC 14443 smart card.
.. tikz:: Emulate a contact-less German ID card to perform sanity checks
: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}
\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]
\tikzstyle{keks}=[to path={-- ++(.1,0) |- (\tikztotarget)}]
\node (touchatag)
{\includegraphics[keepaspectratio, height=2cm,
width=2cm]{%(wd)s/bilder/touchatag.png}};
\node (touchatagbeschreibung) [below=0cm of touchatag, kleiner]
{touchatag};
\node (pcsc-relay) [right=of touchatag]
{\texttt{pcsc-relay}};
\node (pcsc-relaybeschreibung) [below=0cm of pcsc-relay, kleiner]
{NFC emulator
};
\node (vicc) [right=of pcsc-relay]
{\texttt{vicc -t nPA}};
\node (viccbeschreibung) [below=0cm of vicc, kleiner]
{nPA emulator};
\node (group) [fit=(touchatag) (pcsc-relay) (vicc) (touchatagbeschreibung)
(pcsc-relaybeschreibung) (viccbeschreibung)] {};
\node (funktionenchat) [below=0cm of group, bla]
{
PACE
\nodepart{second}
\begin{itemize}
\item Display context (eID/eSign)
\item Display requested permissions
\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
\item With certificate database
\begin{itemize}
\item Identification of service provider
\item Display purpose of transaction
\end{itemize}
\end{itemize}
};
\begin{pgfonlayer}{background}
\node (box) [fit=(touchatag) (pcsc-relay) (vicc) (touchatagbeschreibung)
(pcsc-relaybeschreibung) (viccbeschreibung) (funktionenchat)
(funktionenpace), box, inner sep=.5cm] {};
\node (boxbild) at (box.north west)
{\includegraphics[keepaspectratio, height=1.5cm,
width=1.5cm]{%(wd)s/bilder/moko/moko_reader.png}};
\node [right=0cm of boxbild.east, yshift=.3cm]
{Openmoko Neo FreeRunner};
\end{pgfonlayer}
\node (a) [left=1.5of box]
{\includegraphics[keepaspectratio, height=4cm,
width=4cm]{%(wd)s/bilder/ivak_kiosk-terminal.pdf}};
\node (e) [below=0cm of a, text width=2.5cm, align=center]
{(Public) Terminal};
\begin{pgfonlayer}{background}
\path
(touchatag) edge [doppelpfeil] (pcsc-relay)
(pcsc-relay) edge [doppelpfeil] (vicc)
(vicc.east) edge [keks, pfeil] (funktionenchat.text east)
(vicc.east) edge [keks, pfeil] (funktionenpace.text east)
(a) edge [decorate, decoration={expanding waves, angle=20, segment
length=6}, nichtrundelinie] (touchatag.south west);
\end{pgfonlayer}
PC/SC Relay has the following dependencies:
- PC/SC middleware
- libnfc_
.. include:: relay-note.txt
.. include:: download.txt
.. include:: autotools.txt
===============
Hints on libnfc
===============
Here is an example of how to get the standard
installation of libnfc::
PREFIX=/tmp/install
LIBNFC=libnfc
git clone https://code.google.com/p/libnfc $LIBNFC
cd $LIBNFC
autoreconf -i
# See `./configure --help` for enabling support of additional hardware
./configure --prefix=$PREFIX
make
make install
Building PC/SC Relay with libnfc is done best using :command:`pkg-config`. The file
:file:`libnfc.pc` should be located in ``$INSTALL/lib/pkgconfig``. Here is how to
configure PC/SC Relay to use it::
./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
====================================
Hints on Android Smart Card Emulator
====================================
The Android Smart Card Emulator is build around the host card emulation mode of
Android 4.4 and later. This mode activates the app if the terminal issues a
SELECT command with one of the app's application identifiers. The app registers
for the following AIDs (:file:`ACardEmulator/app/src/main/res/xml/aid_list.xml`):
.. literalinclude:: ../../ACardEmulator/app/src/main/res/xml/aid_list.xml
:language: xml
:emphasize-lines: 8,12,16,20
If used together with PC/SC Relay you need to change these application
identifiers to match the emulated card. Otherwise the app will not be activated
when it should relay command APDUs to PC/SC Relay.
And while you are already modifying the Android Smart Card Emulator you may also
want to activate `useVPCD` and change `hostname` and `port` to configure the
connection to PC/SC Relay
(:file:`ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java`):
.. literalinclude:: ../../ACardEmulator/app/src/main/java/com/vsmartcard/acardemulator/SimulatorService.java
:language: java
:lines: 47-52
:emphasize-lines: 3,5-6
Compiling and installing Android Smart Card Emulator is covered in its :ref:`acardemulator_install` section.
=========================
Hints on PC/SC middleware
=========================
A PC/SC middleware is included by default in most modern operating systems. On
Unix-like systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To
compile PC/SC Relay you will need to install the PCSC-Lite headers from
your distribution.
Windows also ships with a PC/SC middleware in form of the Winscard module.
PC/SC Relay can be (cross) compiled with MinGW-w64. Also, Microsoft's
developement environment Visual Studio includes all necessary data for building
PC/SC Relay.
*****
Usage
*****
.. program-output:: pcsc-relay --help
Below we explain what option to choose for the emulator which receives a
command APDU and transmits a response APDU back to the terminal:
=================================================== ==============
Option ``--emulator``
=================================================== ==============
Emulation hardware supported via libnfc ``libnfc``
Emulation with OpenPICC ``openpicc``
Android Smart Card Emulator ``vpcd``
Virtual Smart Card ``vpcd``
=================================================== ==============
Below we explain what option to choose for the connector which calculates
a response APDU from a given command APDU:
=================================================== ===============
Option ``--connector``
=================================================== ===============
Contact-based Smart Card in PC/SC Reader ``pcsc``
Contact-less Smart Card in PC/SC Reader ``pcsc``
Contact-less Smart Card in Remote Smart Card Reader ``vicc``
Virtual Smart Card ``vicc``
=================================================== ===============
.. include:: questions.txt
********************
Notes and References
********************
.. target-notes::
.. _`Hardware supported by libnfc`: http://nfc-tools.org/index.php?title=Devices_compatibility_matrix
.. _libnfc: http://www.libnfc.org/
.. _OpenPICC: http://www.openpcd.org/OpenPICC
.. _PCSC-lite: http://pcsclite.alioth.debian.org/

25
pcsc-relay/doc/autotools.txt
View File

@@ -1,25 +0,0 @@
.. highlight:: sh
************
Installation
************
=======================================
Installation on Linux, Unix and similar
=======================================
The PC/SC Relay uses the GNU Build System to compile and install. If you are
unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
it, you are probably working bleeding edge in the repository. Run the
following command in :file:`pcsc-relay` to get the missing standard
auxiliary files::
autoreconf --verbose --install
To configure (:command:`configure --help` lists possible options), build and
install the PC/SC Relay now do the following::
./configure
make
make install

14
pcsc-relay/doc/download.txt
View File

@@ -1,14 +0,0 @@
.. highlight:: sh
********
Download
********
You can find the latest release of PC/SC Relay on `Github
<https://github.com/frankmorgner/vsmartcard/releases>`_. Older releases are
still available on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository::
git clone https://github.com/frankmorgner/vsmartcard.git

6
pcsc-relay/doc/questions.txt
View File

@@ -1,6 +0,0 @@
********
Question
********
Do you have questions, suggestions or contributions? Feedback of any kind is
more than welcome! Please use our `project trackers <https://github.com/frankmorgner/vsmartcard/issues>`_.

1
pcsc-relay/docs Symbolic link
View File

@@ -0,0 +1 @@
../docs/

1
remote-reader/README
View File

@@ -1 +0,0 @@
doc/README.txt

9
remote-reader/README.md Normal file
View File

@@ -0,0 +1,9 @@
#Remote Smart Card Reader
Allow a host computer to use the smartphone's NFC hardware as contact-less
smartcard reader. On the host computer a special smart card driver,
[vpcd](http://frankmorgner.github.io/vsmartcard/virtualsmartcard/README.html),
must be installed. The app establishes a connection to vpcd over the network
when a contact-less card is detected.
Please refer to [our project's website](http://frankmorgner.github.io/vsmartcard/remote-reader/README.html) for more information.

2
virtualsmartcard/AUTHORS
View File

@@ -1,2 +0,0 @@
Frank Morgner <frankmorgner@gmail.com>
Dominik Oepen <oepen@informatik.hu-berlin.de>

3115
virtualsmartcard/ChangeLog
View File

File diff suppressed because it is too large Load Diff

10
virtualsmartcard/Makefile.am
View File

@@ -1,15 +1,7 @@
ACLOCAL_AMFLAGS = -I m4
SUBDIRS = src doc npa-example-data MacOSX
EXTRA_DIST = test_vicc_with_npa-tool.sh test_vicc_with_handler_test.sh
distcheck-hook:
test -d .svn && \
svn2cl --group-by-day --reparagraph --separate-daylogs --include-actions --include-rev \
|| true
test -d ../.git && \
git log --pretty --numstat --summary . | git2cl > ChangeLog \
|| true
EXTRA_DIST = test_vicc_with_npa-tool.sh test_vicc_with_handler_test.sh docs
osx:
$(MAKE) -C MacOSX $@

0
virtualsmartcard/NEWS
View File

1
virtualsmartcard/README
View File

@@ -1 +0,0 @@
doc/README.txt

23
virtualsmartcard/README.md Normal file
View File

@@ -0,0 +1,23 @@
#Virtual Smart Card
Virtual Smart Card emulates a smart card and makes it accessible through PC/SC.
Currently the Virtual Smart Card 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)
- Electronic passport (ePass/MRTD) with support for BAC
- Cryptoflex smart card (incomplete)
The vpcd is a smart card reader driver for [PCSC-Lite](http://pcsclite.alioth.debian.org/) 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 on port 35963 and port 35964. 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 Virtual Smart Card is a software emulator, you can use
[pcsc-relay](http://frankmorgner.github.io/vsmartcard/pcsc-relay/README.html)
to make it accessible to an external contact-less smart card reader.
Please refer to [our project's website](http://frankmorgner.github.io/vsmartcard/virtualsmartcard/README.html) for more information.

2
virtualsmartcard/configure.ac
View File

@@ -6,7 +6,7 @@ AC_INIT([Virtual Smart Card], [0.8], [https://github.com/frankmorgner/vsmartcard
AC_CONFIG_SRCDIR([src/vpcd/vpcd.c])
AC_CONFIG_HEADERS([config.h])
AC_CONFIG_MACRO_DIR([m4])
AM_INIT_AUTOMAKE
AM_INIT_AUTOMAKE(foreign)
dnl Add libtool support.
ifdef(

2
virtualsmartcard/doc/Makefile.am
View File

@@ -18,7 +18,7 @@ do_subst = $(SED) \
-e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \
-e 's,[@]top_srcdir[@],$(top_srcdir),g'
EXTRA_DIST = README.txt.in README.txt autotools.txt.in questions.txt.in autotools.txt questions.txt download.txt.in download.txt vpcd_example.conf
EXTRA_DIST = README.txt.in autotools.txt.in questions.txt.in download.txt.in vpcd_example.conf
dist_noinst_SCRIPTS = generate_modules.py

340
virtualsmartcard/doc/README.txt
View File

@@ -1,340 +0,0 @@
.. 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:
################################################################################
Virtual Smart Card
################################################################################
.. sidebar:: Summary
Smart card emulator written in Python
:Authors:
- `Frank Morgner <frankmorgner@gmail.com>`_
- `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
:License:
GPL version 3
:Tested Platforms:
- Windows
- Mac OS X
- Linux (Debian, Ubuntu, OpenMoko)
Virtual Smart Card emulates a smart card and makes it accessible through PC/SC.
Currently the Virtual Smart Card 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|)
- Electronic passport (ePass/MRTD) with 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 on port 35963 and port 35964. 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 Virtual Smart Card 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:: Virtual Smart Card used with PCSC-Lite or WinSCard
: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, inner xsep=.7cm, text width=3cm]
{PC/SC Framework\\\
(\texttt{pcscd} or \texttt{SCardSvr})
};
\node (sca) [aktivbox, klein, left=of pcsclite] {Smart Card\\Application};
\node (vpcd) [box, at=(pcsclite.east), xshift=-.3cm] {\texttt{vpcd}};
\node (vicc) [aktivbox, right=2cm of pcsclite] {\texttt{vicc}};
\begin{pgfonlayer}{background}
\path[linie]
(sca) edge (pcsclite)
(vpcd) edge node {\includegraphics[width=1.2cm]{%(wd)s/bilder/simplecloud.pdf}} (vicc)
;
\end{pgfonlayer}
.. versionadded:: 0.7
The Virtual Smart Card 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:: Virtual Smart Card 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)
[klein, box, text width=4cm]
{Virtual Smart Card's\\
PC/SC Framework
};
\node (sca) [aktivbox, klein, left=of pcsclite] {Smart Card\\Application};
\node (vicc) [aktivbox, right=2cm of pcsclite] {\texttt{vicc}};
\begin{pgfonlayer}{background}
\path[linie]
(sca) edge (pcsclite)
(pcsclite) edge node {\includegraphics[width=1.5cm]{%(wd)s/bilder/simplecloud.pdf}} (vicc)
;
\end{pgfonlayer}
On Android, where a traditional PC/SC framework is not available, you can use
our framework to make your real contact-less smart accessible through PKCS#11.
For example, an email signing application can use the PKCS#11 interface of
OpenSC, which is linked against our PC/SC implementation. Then an Android App
(e.g. :ref:`remote-reader`) can connect as |vpicc| delegating all requests and
responses via NFC to a contact-less smart card that signs the mail.
Depending on your usage of the |vpicc| you may need to install the following:
- Python_
- pyscard_ (relaying a local smart card with :option:`--type=relay`)
- PyCrypto_, PBKDF2_, PIL_, readline_ or PyReadline_ (emulation of electronic
passport with :option:`--type=ePass`)
- OpenPACE_ (emulation of German identity card with :option:`--type=nPA`)
- libqrencode_ (to print a QR code on the command line for `vpcd-config`; an
URL will be printed if libqrencode is not available)
.. include:: download.txt
.. _vicc_install:
.. include:: autotools.txt
================================================================================
Building and installing |vpcd| on Mac OS X
================================================================================
Mac OS X 10.9 and earlier is using PCSC-Lite as smart card service which allows
using the standard routine for :ref:`installation on Unix<vicc_install>`.
Mac OS X 10.10 (and later) ships with a proprietary implementation of the PC/SC
layer instead of with PCSC-Lite. As far as we know, this means that smart card
readers must be USB devices instead of directly allowing a more generic type of
reader. To make |vpcd| work we simply configure it to pretend being a USB smart
card reader with an :file:`Ìnfo.plist`::
./configure --prefix=/ --enable-infoplist
make
make install
================================================================================
Building and installing |vpcd| on Windows
================================================================================
.. 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.
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 8.1 and Visual Studio 2013`_. If you choose
to download the `Windows binaries`_, you may directly jump to step 3.
1. In Visual Studio select :menuselection:`File --> Open --> Convert
Sources/Dirs...` and choose the vpcd's :file:`sources` either in the
:file:`WinXP` [#footnote1]_ or :file:`Win7` folder.
When successfully imported, ensure with the configuration manager, that both
of the created projects are built for the same platform (x64 or Win32).
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` and
`WudfUpdate_01009.dll` [#footnote2]_.
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
install the driver::
"C:\Program Files\Windows Kits\8.1\Tools\x86\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 (e.g., use ``...\x64\devcon.exe`` for a 64 bit
driver). You can also download `DevCon's source code`_ and compile it
yourself.
For Win7 and older, code signing is optional and will yield a warning during
installation when missing. Simply click continue to install the driver anyway.
To activate the WDK test signing, use VS build-in Driver Signing settings.
Right click :guilabel:`BixVReader-package` :menuselection:`Properties -->
Driver Signing --> Sign Mode --> Test Sign`. Import the WDKTestCert
certificate :file:`BixVReader-package.cer` into your windows keystore (e.g.
on local computer) and then install the driver. See
`Microsoft's Kernel-Mode Code Signing Walkthrough`_ for
details.
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. All of Fabio's card connectors (pipe reader/TCP/IP
reader) are still active by default.
********************************************************************************
Using the Virtual Smart Card
********************************************************************************
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.
.. _vicc_config:
================================================================================
Configuring |vpcd| on Unix
================================================================================
The configuration file of |vpcd| is usually placed into
:file:`/etc/reader.conf.d/`. For older versions of PCSC-Lite you
need to run :command:`update-reader.conf` to update :command:`pcscd`'s main
configuration file. 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" when loading |vpcd|.
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 Mac OS X
================================================================================
Mac OS X 10.9 and earlier is using PCSC-Lite as smart card service which allows
using the standard routine for :ref:`configuration on Unix<vicc_config>`.
On Mac OS X 10.10 you should have configured the generation of
:file:`Info.plist` at compile time. Now do the following for registering |vpcd|
as USB device:
1. Choose an USB device (e.g. mass storage, phone, mouse, ...), which will be
used to start |vpcd|. Plug it into the computer.
2. Run the following command to get the device's product and vendor ID::
system_profiler SPUSBDataType
3. Change :file:`/usr/libexec/SmartCardServices/drivers/ifd-vpcd.bundle/Info.plist`
to match your product and vendor ID:
.. literalinclude:: Info.plist
:emphasize-lines: 34,39
Note that ``ifdFriendlyName`` can be used in the same way as ``DEVICENAME``
:ref:`described above<vicc_config>`.
4. Restart the PC/SC service::
sudo killall -SIGKILL -m .*com.apple.ifdreader
Now, every time you plug in your USB device |vpcd| will be started. It will be
stopped when you unplug the device.
================================================================================
Configuring |vpcd| on Windows
================================================================================
The configuration file `BixVReader.ini` of |vpcd| is usually placed into
:file:`C:\\Windows` (:envvar:`SystemRoot`). The user mode device driver
framework (:command:`WUDFHost.exe`) should read it automatically and load the
|vpcd| on startup. The Windows Device Manager :command:`mmc devmgmt.msc` 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:: ../../virtualsmartcard/win32/BixVReader/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 compiled `Windows binaries`_ of |vpicc| include OpenPACE. The other
dependencies listed above need to be installed seperately. You can start the
|vpicc| via :command:`python.exe vicc.py`. On all other systems an executable
script :command:`vicc` is installed using the autotools.
The |vpicc| option :option:`--help` gives an overview about the command line
switches:
.. program-output:: vicc --help
.. versionadded:: 0.7
We implemented :command:`vpcd-config` which tries to guess the local IP
address and outputs |vpcd|'s configuration. |vpicc|'s options should be
chosen accordingly (:option:`--hostname` and :option:`--port`)
:command:`vpcd-config` also prints a QR code for configuration of the
:ref:`remote-reader`.
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 Virtual Smart Card'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::
.. [#footnote1] With VS 2013 and WDK 8.1 no Windows XP driver can be build. You need to use an older version of VS with WDK 7.1.0.
.. [#footnote2] Note that WudfUpdate_01009.dll for 32 bit will be around 1795 KB and for 64 bit around 2102 KB big.
.. _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/
.. _readline: https://docs.python.org/3.3/library/readline.html
.. _PyReadline: https://pypi.python.org/pypi/pyreadline
.. _PIL: http://www.pythonware.com/products/pil/
.. _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 8.1 and Visual Studio 2013`: http://msdn.microsoft.com/en-us/windows/hardware/hh852365.aspx
.. _`DevCon's source code`: https://github.com/Microsoft/Windows-driver-samples/tree/master/setup/devcon
.. _`Microsoft's Kernel-Mode Code Signing Walkthrough`: http://msdn.microsoft.com/en-us/library/windows/hardware/dn653569%28v=vs.85%29.aspx
.. _`Windows binaries`: https://github.com/frankmorgner/vsmartcard/releases/download/virtualsmartcard-0.7/virtualsmartcard-0.7_win32.zip

25
virtualsmartcard/doc/autotools.txt
View File

@@ -1,25 +0,0 @@
.. highlight:: sh
************
Installation
************
=======================================
Installation on Linux, Unix and similar
=======================================
The Virtual Smart Card uses the GNU Build System to compile and install. If you are
unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
it, you are probably working bleeding edge in the repository. Run the
following command in :file:`virtualsmartcard` to get the missing standard
auxiliary files::
autoreconf --verbose --install
To configure (:command:`configure --help` lists possible options), build and
install the Virtual Smart Card now do the following::
./configure --sysconfdir=/etc
make
make install

14
virtualsmartcard/doc/download.txt
View File

@@ -1,14 +0,0 @@
.. highlight:: sh
********
Download
********
You can find the latest release of Virtual Smart Card on `Github
<https://github.com/frankmorgner/vsmartcard/releases>`_. Older releases are
still available on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository::
git clone https://github.com/frankmorgner/vsmartcard.git

6
virtualsmartcard/doc/questions.txt
View File

@@ -1,6 +0,0 @@
********
Question
********
Do you have questions, suggestions or contributions? Feedback of any kind is
more than welcome! Please use our `project trackers <https://github.com/frankmorgner/vsmartcard/issues>`_.

1
virtualsmartcard/docs Symbolic link
View File

@@ -0,0 +1 @@
../docs/