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

updated documentation

Browse Source 
git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@743 96b47cad-a561-4643-ad3b-153ac7d7599c
This commit is contained in:
frankmorgner
2012-04-11 03:44:48 +00:00
parent 3ce000b846
commit 93c1a69d7f
11 changed files with 285 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
ccid/doc/Makefile.am
View File

@@ -1,4 +1,5 @@
do_subst = sed \
-e 's,[@]PACKAGE[@],$(PACKAGE),g' \
-e 's,[@]PACKAGE_NAME[@],$(PACKAGE_NAME),g' \
-e 's,[@]PACKAGE_TARNAME[@],$(PACKAGE_TARNAME),g' \
-e 's,[@]PACKAGE_BUGREPORT[@],$(PACKAGE_BUGREPORT),g' \

81
ccid/doc/README.rst
View File

@@ -5,6 +5,8 @@
.. _libccid: http://pcsclite.alioth.debian.org/ccid.html
.. |npa| replace:: :ref:`npa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |win| replace::
********************************************************************************
@@ -18,37 +20,46 @@ USB CCID Emulator
:Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko)
Welcome to the USB CCID Emulator. The purpose of the USB CCID Emulator is to forward
a PC/SC smartcard reader as a standard USB CCID reader. If the machine running
the USB CCID Emulator is in USB device mode, a local reader is forwareded via USB
to another machine. If in USB host mode, a USB CCID reader is virtually plugged
into the machine running the USB CCID Emulator. Applications on Windows and
Unix-like systems can access the USB CCID Emulator through PC/SC as if it were a
real smart card reader.
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 |npa|
also |PACE| can be performed by the emulator.
The USB CCID Emulator accesses a smart card through a local reader. Simple
commands such as transmitting an APDU (``SCardTransmit`` and accordingly
``PC_to_RDR_XfrBlock``) are directly forwarded to the local reader/smart card.
USB CCID Emulator can perform secure PIN verification and modification
(``FEATURE_VERIFY_PIN_DIRECT`` or ``FEATURE_MODIFY_PIN_DIRECT`` and accordingly
``PC_to_RDR_Secure``). Moreover the USB CCID Emulator has support the for Password
Authenticated Connection Establishment (PACE) using |npa|
(``FEATURE_EXECUTE_PACE``). Thus USB CCID Emulator can be used with the German
identity card ("neuer Personalausweis", nPA) similar to a "Standardleser"
(CAT-S) or "Komfortleser" (CAT-K).
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. [#f1]_
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``
================================== ============================================================
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.
.. [#f1] Note that the heavily outdated `Windows USB CCID driver <http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_ does not support secure PIN entry or PIN modification. USB CCID Emulator comes with a patch for libccid_ to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction.
.. include:: autotools.rst
Running the USB CCID Emulator has the following dependencies:
- Linux Kernel with GadgetFS_
- OpenSC_
- |npa| (only if support for PACE is enabled)
- |npa| (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
@@ -60,14 +71,14 @@ 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`. A guide focused on Debian based systems to run
and compile :program:`gadgetfs`, you can find `here
the kernel module :program:`gadgetfs`. A guide focused on Debian based systems
to run and compile GadgetFS_, you can find `here
<http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_.
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)>`_.
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
@@ -78,11 +89,10 @@ loading the module, you maybe want to check out `this patch
Hints on OpenSC
---------------
Without the |npa| the USB CCID Emulator links against libopensc, which is
discouraged and hindered since OpenSC version >= 0.12. (We really need to get
rid of this dependency or integrate better into the OpenSC-framework.) You need
the OpenSC components to be installed (especially :file:`libopensc.so`). Here
is an example of how to get the standard installation of OpenSC_::
Without the |npa| the USB CCID Emulator links against OpenSC, which is discouraged
and hindered since OpenSC version >= 0.12. You need 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
OPENSC=opensc
@@ -103,19 +113,14 @@ configure the USB CCID Emulator to use it::
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 smart card driver. To initialize PACE using the PC/SC API you need to
patch libccid and pcsc-lite (see directory patches).
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
<http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_. To initialize
|PACE| using the PC/SC API you need to patch libccid_ (see :file:`patches`).
.. program-output:: ccid-emulator --help
cats-test can be used to test the PACE capabilities of a smart card reader with
PACE support (such as the USB CCID Emulator or any other "Standardleser" CAT-S or
"Komfortleser" CAT-C) via PC/SC.
.. program-output:: cats-test
.. include:: questions.rst

83
ccid/doc/README.rst.in
View File

@@ -5,6 +5,8 @@
.. _libccid: http://pcsclite.alioth.debian.org/ccid.html
.. |npa| replace:: :ref:`npa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |win| replace::
********************************************************************************
@@ -18,37 +20,46 @@
:Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko)
Welcome to the @PACKAGE_NAME@. The purpose of the @PACKAGE_NAME@ is to forward
a PC/SC smartcard reader as a standard USB CCID reader. If the machine running
the @PACKAGE_NAME@ is in USB device mode, a local reader is forwareded via USB
to another machine. If in USB host mode, a USB CCID reader is virtually plugged
into the machine running the @PACKAGE_NAME@. Applications on Windows and
Unix-like systems can access the @PACKAGE_NAME@ through PC/SC as if it were a
real smart card reader.
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 |npa|
also |PACE| can be performed by the emulator.
The @PACKAGE_NAME@ accesses a smart card through a local reader. Simple
commands such as transmitting an APDU (``SCardTransmit`` and accordingly
``PC_to_RDR_XfrBlock``) are directly forwarded to the local reader/smart card.
@PACKAGE_NAME@ can perform secure PIN verification and modification
(``FEATURE_VERIFY_PIN_DIRECT`` or ``FEATURE_MODIFY_PIN_DIRECT`` and accordingly
``PC_to_RDR_Secure``). Moreover the @PACKAGE_NAME@ has support the for Password
Authenticated Connection Establishment (PACE) using |npa|
(``FEATURE_EXECUTE_PACE``). Thus @PACKAGE_NAME@ can be used with the German
identity card ("neuer Personalausweis", nPA) similar to a "Standardleser"
(CAT-S) or "Komfortleser" (CAT-K).
If the machine running :command:`@PACKAGE@` is in USB device mode, a local
reader is forwareded via USB to another machine. If in USB host mode, the USB
CCID reader will locally be present.
Applications on Windows and Unix-like systems can access the @PACKAGE_NAME@
through PC/SC as if it was a real smart card reader. No installation of a smart
card driver is required since USB CCID drivers are usually shipped with the
modern OS. [#f1]_
Here is a subset of USB CCID commands supported by the @PACKAGE_NAME@ with
their PC/SC counterpart:
================================== ============================================================
USB CCID PC/SC
================================== ============================================================
``PC_to_RDR_XfrBlock`` ``SCardTransmit``
``PC_to_RDR_Secure`` ``FEATURE_VERIFY_PIN_DIRECT``, ``FEATURE_MODIFY_PIN_DIRECT``
``PC_to_RDR_Secure`` (proprietary) ``FEATURE_EXECUTE_PACE``
================================== ============================================================
The @PACKAGE_NAME@ is implemented using GadgetFS_. Some fragments of the source
code are based on the GadgetFS example and on the source code of the OpenSC_
tools.
.. [#f1] Note that the heavily outdated `Windows USB CCID driver <http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_ does not support secure PIN entry or PIN modification. @PACKAGE_NAME@ comes with a patch for libccid_ to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction.
.. include:: autotools.rst
Running the @PACKAGE_NAME@ has the following dependencies:
- Linux Kernel with GadgetFS_
- OpenSC_
- |npa| (only if support for PACE is enabled)
- |npa| (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
@@ -60,14 +71,14 @@ 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`. A guide focused on Debian based systems to run
and compile :program:`gadgetfs`, you can find `here
the kernel module :program:`gadgetfs`. A guide focused on Debian based systems
to run and compile GadgetFS_, you can find `here
<http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_.
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)>`_.
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
@@ -78,11 +89,10 @@ loading the module, you maybe want to check out `this patch
Hints on OpenSC
---------------
Without the |npa| the @PACKAGE_NAME@ links against libopensc, which is
discouraged and hindered since OpenSC version >= 0.12. (We really need to get
rid of this dependency or integrate better into the OpenSC-framework.) You need
the OpenSC components to be installed (especially :file:`libopensc.so`). Here
is an example of how to get the standard installation of OpenSC_::
Without the |npa| the @PACKAGE_NAME@ links against OpenSC, which is discouraged
and hindered since OpenSC version >= 0.12. You need 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
OPENSC=opensc
@@ -103,19 +113,14 @@ configure the @PACKAGE_NAME@ to use it::
Usage
=====
The @PACKAGE_NAME@ has various command line options to customize the appearance on
the USB host. In order to run the @PACKAGE_NAME@ GadgetFS_ must be loaded and
mounted. The @PACKAGE_NAME@ is compatible with the unix driver libccid_ and the
windows smart card driver. To initialize PACE using the PC/SC API you need to
patch libccid and pcsc-lite (see directory patches).
The @PACKAGE_NAME@ has various command line options to customize the appearance
on the USB host. In order to run the @PACKAGE_NAME@ GadgetFS_ must be loaded
and mounted. The @PACKAGE_NAME@ is compatible with the unix driver libccid_
and the `Windows USB CCID driver
<http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_. To initialize
|PACE| using the PC/SC API you need to patch libccid_ (see :file:`patches`).
.. program-output:: ccid-emulator --help
cats-test can be used to test the PACE capabilities of a smart card reader with
PACE support (such as the @PACKAGE_NAME@ or any other "Standardleser" CAT-S or
"Komfortleser" CAT-C) via PC/SC.
.. program-output:: cats-test
.. program-output:: @PACKAGE@ --help
.. include:: questions.rst

16
doc/index.rst
View File

@@ -8,29 +8,31 @@ Welcome to the |vsmartcard|. |vsmartcard| is an umbrella project for various pro
Currently the following projects are part of |vsmartcard|:
.. toctree::
:titlesonly:
virtualsmartcard/README
pcsc-relay/README
npa/README
ccid/README
npa/README
.. toctree::
:hidden:
virtualsmartcard/autotools
pcsc-relay/autotools
npa/autotools
ccid/autotools
virtualsmartcard/questions
pcsc-relay/questions
npa/questions
ccid/questions
npa/autotools
npa/questions
pcsc-relay/autotools
pcsc-relay/questions
virtualsmartcard/autotools
virtualsmartcard/questions
Looking for a feature the included programs do not offer? Want to extend the
functionality of some library? Apart from requesting a new feature, you can
have a look at these programming guides and try yourself:
.. toctree::
:titlesonly:
virtualsmartcard/api
npa/api

51
npa/doc/README.rst
View File

@@ -1,8 +1,13 @@
.. highlight:: sh
.. _OpenSC: http://www.opensc-project.org
.. _OpenSC with PACE: http://github.com/frankmorgner/OpenSC
.. _OpenSSL: http://www.openssl.org
.. _OpenPACE: http://openpace.sourceforge.net
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |npa-tool| replace:: :command:`npa-tool`
.. _npa:
@@ -15,21 +20,18 @@ nPA Smart Card Library
:License:
GPL version 3
:Tested Platforms:
- Linux (Debian, Ubuntu, OpenMoko)
- Windows
- Linux (Debian, Ubuntu, OpenMoko)
:Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Welcome to the nPA Smart Card Library. The purpose of the nPA Smart Card Library is to offer an easy to use API for the new
German identity card (neuer Personalausweis, nPA). The library also implements
secure messaging, which could also be used for other cards.
The nPA Smart Card Library offers an easy to use API for the new German identity card
(neuer Personalausweis, nPA). The library also implements secure messaging,
which could also be used for other cards. The included |npa-tool| can
be used for PIN management or to send APDUs inside a secure channel.
The nPA Smart Card Library is implemented using OpenPACE_.
Some fragments of the source code are based on the source code of the OpenSC tools.
The included npa-tool has support for Password Authenticated Connection
Establishment (PACE). npa-tool can be used for PIN management or to encrypt
APDUs inside a secure messaging channel established with PACE.
The nPA Smart Card Library is implemented using OpenPACE_. Some fragments of the
source code are based on the source code of the OpenSC_ tools.
.. _npa-install:
@@ -39,15 +41,15 @@ APDUs inside a secure messaging channel established with PACE.
The nPA Smart Card Library has the following dependencies:
- `OpenSC with PACE`_
- OpenSSL with OpenPACE_
- OpenSSL_ with OpenPACE_
------------------------------
Hints on OpenSSL with OpenPACE
------------------------------
The nPA Smart Card Library links against OpenSSL, which must be patched with OpenPACE_.
Here is an example of how to get the standard installation of OpenSSL with
The nPA Smart Card Library links against OpenSSL_, which must be patched with
OpenPACE_. Here is an example of how to get the standard installation of
OpenPACE_::
PREFIX=/tmp/install
@@ -61,9 +63,10 @@ OpenPACE_::
make
make install
Building the nPA Smart Card Library with OpenPACE_ is done best using :command:`pkg-config`. The file
:file:`libcrypto.pc` should be located in ``$INSTALL/lib/pkgconfig``. Here is how
to configure the nPA Smart Card Library to use it::
Building the nPA Smart Card Library with OpenPACE_ is done best using
:command:`pkg-config`. The file :file:`libcrypto.pc` should be located in
``$INSTALL/lib/pkgconfig``. Here is how to configure the nPA Smart Card Library to use
it::
./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
@@ -100,15 +103,15 @@ configure the nPA Smart Card Library to use it::
Usage
=====
When testing PACE with either PIN, CAN, MRZ or PUK run npa-tool. Here you can
enter APDUs which are to be converted according to the secure messaging
parameter and to be sent to the card. Herefor insert the APDU in hex (upper or
lower case) with a colon to separate the bytes or without it. Example APDUs can
be found in the file apdus.
To pass a secret to |npa-tool| for |PACE|, command line parameters or
environment variables can be used. If the smart card reader supports |PACE|,
the PIN pad is used. If none of these options is applies, npa-tool will show a
password prompt.
To pass a secret to npa-tool, the command line parameters or the environment
variables PIN/CAN/MRZ/PUK/NEWPIN can be used. If none of these options is used,
npa-tool will show a password prompt.
|npa-tool| can send arbitrary APDUs to the nPA in the secure channel. APDUs
are entered interactively or through a file. APDUs are formatted in hex (upper
or lower case) with an optional colon to separate the bytes. Example APDUs can
be found in :file:`apdus`.
.. program-output:: npa-tool --help

49
npa/doc/README.rst.in
View File

@@ -1,8 +1,13 @@
.. highlight:: sh
.. _OpenSC: http://www.opensc-project.org
.. _OpenSC with PACE: http://github.com/frankmorgner/OpenSC
.. _OpenSSL: http://www.openssl.org
.. _OpenPACE: http://openpace.sourceforge.net
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |npa-tool| replace:: :command:`npa-tool`
.. _npa:
@@ -20,16 +25,13 @@
:Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Welcome to the @PACKAGE_NAME@. The purpose of the @PACKAGE_NAME@ is to offer an easy to use API for the new
German identity card (neuer Personalausweis, nPA). The library also implements
secure messaging, which could also be used for other cards.
The @PACKAGE_NAME@ offers an easy to use API for the new German identity card
(neuer Personalausweis, nPA). The library also implements secure messaging,
which could also be used for other cards. The included |npa-tool| can
be used for PIN management or to send APDUs inside a secure channel.
The @PACKAGE_NAME@ is implemented using OpenPACE_.
Some fragments of the source code are based on the source code of the OpenSC tools.
The included npa-tool has support for Password Authenticated Connection
Establishment (PACE). npa-tool can be used for PIN management or to encrypt
APDUs inside a secure messaging channel established with PACE.
The @PACKAGE_NAME@ is implemented using OpenPACE_. Some fragments of the
source code are based on the source code of the OpenSC_ tools.
.. _npa-install:
@@ -39,15 +41,15 @@ APDUs inside a secure messaging channel established with PACE.
The @PACKAGE_NAME@ has the following dependencies:
- `OpenSC with PACE`_
- OpenSSL with OpenPACE_
- OpenSSL_ with OpenPACE_
------------------------------
Hints on OpenSSL with OpenPACE
------------------------------
The @PACKAGE_NAME@ links against OpenSSL, which must be patched with OpenPACE_.
Here is an example of how to get the standard installation of OpenSSL with
The @PACKAGE_NAME@ links against OpenSSL_, which must be patched with
OpenPACE_. Here is an example of how to get the standard installation of
OpenPACE_::
PREFIX=/tmp/install
@@ -61,9 +63,10 @@ OpenPACE_::
make
make install
Building the @PACKAGE_NAME@ with OpenPACE_ is done best using :command:`pkg-config`. The file
:file:`libcrypto.pc` should be located in ``$INSTALL/lib/pkgconfig``. Here is how
to configure the @PACKAGE_NAME@ to use it::
Building the @PACKAGE_NAME@ with OpenPACE_ is done best using
:command:`pkg-config`. The file :file:`libcrypto.pc` should be located in
``$INSTALL/lib/pkgconfig``. Here is how to configure the @PACKAGE_NAME@ to use
it::
./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
@@ -100,15 +103,15 @@ configure the @PACKAGE_NAME@ to use it::
Usage
=====
When testing PACE with either PIN, CAN, MRZ or PUK run npa-tool. Here you can
enter APDUs which are to be converted according to the secure messaging
parameter and to be sent to the card. Herefor insert the APDU in hex (upper or
lower case) with a colon to separate the bytes or without it. Example APDUs can
be found in the file apdus.
To pass a secret to |npa-tool| for |PACE|, command line parameters or
environment variables can be used. If the smart card reader supports |PACE|,
the PIN pad is used. If none of these options is applies, npa-tool will show a
password prompt.
To pass a secret to npa-tool, the command line parameters or the environment
variables PIN/CAN/MRZ/PUK/NEWPIN can be used. If none of these options is used,
npa-tool will show a password prompt.
|npa-tool| can send arbitrary APDUs to the nPA in the secure channel. APDUs
are entered interactively or through a file. APDUs are formatted in hex (upper
or lower case) with an optional colon to separate the bytes. Example APDUs can
be found in :file:`apdus`.
.. program-output:: npa-tool --help

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

@@ -1,4 +1,5 @@
do_subst = sed \
-e 's,[@]PACKAGE[@],$(PACKAGE),g' \
-e 's,[@]PACKAGE_NAME[@],$(PACKAGE_NAME),g' \
-e 's,[@]PACKAGE_TARNAME[@],$(PACKAGE_TARNAME),g' \
-e 's,[@]PACKAGE_BUGREPORT[@],$(PACKAGE_BUGREPORT),g' \

61
pcsc-relay/doc/README.rst
View File

@@ -1,52 +1,58 @@
.. highlight:: sh
.. _libnfc: http://www.libnfc.org/
.. _OpenPICC: http://www.openpcd.org/OpenPICC
.. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _pcsc-relay:
********************************************************************************
PC/SC Relay
********************************************************************************
:Authors:
- Dominik Oepen <oepen@informatik.hu-berlin.de>
- Frank Morgner <morgner@informatik.hu-berlin.de>
- Dominik Oepen <oepen@informatik.hu-berlin.de>
:License:
GPL version 3
:Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko)
:Potential Platforms:
- Windows
- Unix-like operating systems (Mac OS, Solaris, BSD, ...)
- Linux (Debian, Ubuntu, OpenMoko)
:Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Welcome to pcsc-relay. The purpose of pcsc-relay is to forward APDUs from the
OpenPICC or from a libnfc device to a smart card via the PCSC middleware. You
can use this program in combination with the virtual smart card to emulate a
ISO/IEC 14443 smart card.
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
backends:
- libnfc_
- OpenPICC_
Command APDUs are received with the contact-less interface and forwarded to an
existing smart card via PC/SC. The Response APDUs are then sent back via RFID.
You can use PC/SC Relay in combination with the :ref:`vicc` to completely
emulate an ISO/IEC 14443 smart card.
.. note::
This software can actually be used in a relay attack allowing full access
to the card... `We discussed the impact especially on the German identity
to the card. `We discussed the impact especially on the German identity
card
<http://media.ccc.de/browse/congress/2010/27c3-4297-de-die_gesamte_technik_ist_sicher.html>`_,
but it generally concerns *all NFC smart cards*.
but it generally concerns *all* contact-less smart cards.
.. include:: autotools.rst
pcsc-relay has the following dependencies:
PC/SC Relay has the following dependencies:
- PC/SC middleware
- libnfc_
.. program-output:: pcsc-relay --help
---------------
Hints on libnfc
---------------
pcsc-relay links against libnfc_. Here is an example of how to get the standard
PC/SC Relay links against libnfc_. Here is an example of how to get the standard
installation of the latter::
PREFIX=/tmp/install
@@ -58,9 +64,9 @@ installation of the latter::
make
make install
Building pcsc-relay with libnfc_ is done best using :command:`pkg-config`. The file
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 pcsc-relay to use it::
configure PC/SC Relay to use it::
./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
@@ -69,12 +75,21 @@ configure pcsc-relay to use it::
Hints on PC/SC middleware
-------------------------
PC/SC 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
pcsc-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. Microsoft's developement environment Visual Studio includes
all necessary data for building pcsc-relay.
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.
Microsoft's developement environment Visual Studio includes all necessary data
for building PC/SC Relay.
=====
Usage
=====
.. program-output:: pcsc-relay --help
.. include:: questions.rst

61
pcsc-relay/doc/README.rst.in
View File

@@ -1,52 +1,58 @@
.. highlight:: sh
.. _libnfc: http://www.libnfc.org/
.. _OpenPICC: http://www.openpcd.org/OpenPICC
.. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _pcsc-relay:
********************************************************************************
@PACKAGE_NAME@
********************************************************************************
:Authors:
- Dominik Oepen <oepen@informatik.hu-berlin.de>
- Frank Morgner <morgner@informatik.hu-berlin.de>
- Dominik Oepen <oepen@informatik.hu-berlin.de>
:License:
GPL version 3
:Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko)
:Potential Platforms:
- Windows
- Unix-like operating systems (Mac OS, Solaris, BSD, ...)
- Linux (Debian, Ubuntu, OpenMoko)
:Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Welcome to pcsc-relay. The purpose of pcsc-relay is to forward APDUs from the
OpenPICC or from a libnfc device to a smart card via the PCSC middleware. You
can use this program in combination with the virtual smart card to emulate a
ISO/IEC 14443 smart card.
Welcome to @PACKAGE_NAME@. The purpose of @PACKAGE_NAME@ is to relay a smart
card using an contact-less interface. Currently the following contact-less
backends:
- libnfc_
- OpenPICC_
Command APDUs are received with the contact-less interface and forwarded to an
existing smart card via PC/SC. The Response APDUs are then sent back via RFID.
You can use @PACKAGE_NAME@ in combination with the :ref:`vicc` to completely
emulate an ISO/IEC 14443 smart card.
.. note::
This software can actually be used in a relay attack allowing full access
to the card... `We discussed the impact especially on the German identity
to the card. `We discussed the impact especially on the German identity
card
<http://media.ccc.de/browse/congress/2010/27c3-4297-de-die_gesamte_technik_ist_sicher.html>`_,
but it generally concerns *all NFC smart cards*.
but it generally concerns *all* contact-less smart cards.
.. include:: autotools.rst
pcsc-relay has the following dependencies:
@PACKAGE_NAME@ has the following dependencies:
- PC/SC middleware
- libnfc_
.. program-output:: pcsc-relay --help
---------------
Hints on libnfc
---------------
pcsc-relay links against libnfc_. Here is an example of how to get the standard
@PACKAGE_NAME@ links against libnfc_. Here is an example of how to get the standard
installation of the latter::
PREFIX=/tmp/install
@@ -58,9 +64,9 @@ installation of the latter::
make
make install
Building pcsc-relay with libnfc_ is done best using :command:`pkg-config`. The file
Building @PACKAGE_NAME@ 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 pcsc-relay to use it::
configure @PACKAGE_NAME@ to use it::
./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
@@ -69,12 +75,21 @@ configure pcsc-relay to use it::
Hints on PC/SC middleware
-------------------------
PC/SC 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
pcsc-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. Microsoft's developement environment Visual Studio includes
all necessary data for building pcsc-relay.
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 @PACKAGE_NAME@ 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.
Microsoft's developement environment Visual Studio includes all necessary data
for building @PACKAGE_NAME@.
=====
Usage
=====
.. program-output:: @PACKAGE@ --help
.. include:: questions.rst

49
virtualsmartcard/doc/README.rst
View File

@@ -11,7 +11,10 @@
.. |vpicc| replace:: :abbr:`vpicc (virtual smart card)`
.. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)`
.. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. _vicc:
********************************************************************************
Virtual Smart Card
@@ -28,17 +31,25 @@ Virtual Smart Card
:Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Welcome to the Virtual Smart Card. The purpose of the Virtual Smart Card is to emulate a
smart card and make it accessible through PCSC. Currently the virtual smart
card supports almost all commands of ISO-7816 including secure messaging.
Besides a plain ISO-7816 smart card it is also possible to emulate a German
ePass (only basic access control) and a rudimentary Cryptoflex smart card. The
|vpicc| can be accessed through the |vpcd| which is a driver for
:command:`pcscd` of PCSC-Lite_.
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:
By default the vicc communicates with the vpcd through a socket on localhost
port 35963. The file :file:`utils.py` was taken from Henryk Plötz's
cyberflex-shell_.
- Generic ISO-7816 smart card including secure messaging
- German electronic identity card (nPA) with |EAC| including |PACE|
- German electronic passport (ePass) with basic access control
- Cryptoflex smart card (incomplete)
The |vpcd| is a smart card driver for PCSC-Lite_. It allows
smart card applications to access the |vpicc| through the PC/SC API. By
default |vpicc| communicates with |vpcd| through a socket on localhost port
35963. 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_.
.. include:: autotools.rst
@@ -52,28 +63,26 @@ the following:
- PBKDF2_
- PIP_
The |vpcd| has the following dependencies:
- PCSC-Lite_
The |vpcd| depends on PCSC-Lite_.
================================================================================
Running the Virtual Smart Card
================================================================================
First you need to make sure that pcscd loads the |vpcd|. You might need to run
:command:`update-reader.conf` to update pcscd's configuration file. Then
:command:`pcscd -f -d` should say something like "Attempting startup of
First you need to make sure that :command:`pcscd` loads the |vpcd|. You might
need to run :command:`update-reader.conf` to update its configuration file.
Then :command:`pcscd -f -d` should say something like "Attempting startup of
Virtual PCD"
Now you can run :command:`vicc` which connects to the |vpcd|. The command
:command:`vicc --help` gives an overview about the command line options.
You should now be able to access the |vpicc| through the system's
PC/SC API via |vpcd|/pcscd. You can use the opensc-explorer or pcsc_scan to test
that.
.. program-output:: vicc --help
You should now be able to access the |vpicc| through the PC/SC API via
|vpcd|/pcscd. You can use the :command:`opensc-explorer` or
:command:`pcsc_scan` for testing.
.. include:: questions.rst

49
virtualsmartcard/doc/README.rst.in
View File

@@ -11,7 +11,10 @@
.. |vpicc| replace:: :abbr:`vpicc (virtual smart card)`
.. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)`
.. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. _vicc:
********************************************************************************
@PACKAGE_NAME@
@@ -28,17 +31,25 @@
:Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Welcome to the @PACKAGE_NAME@. The purpose of the @PACKAGE_NAME@ is to emulate a
smart card and make it accessible through PCSC. Currently the virtual smart
card supports almost all commands of ISO-7816 including secure messaging.
Besides a plain ISO-7816 smart card it is also possible to emulate a German
ePass (only basic access control) and a rudimentary Cryptoflex smart card. The
|vpicc| can be accessed through the |vpcd| which is a driver for
:command:`pcscd` of PCSC-Lite_.
@PACKAGE_NAME@ emulates a smart card and makes it accessible through PC/SC.
Currently the @PACKAGE_NAME@ supports the following types of smart cards:
By default the vicc communicates with the vpcd through a socket on localhost
port 35963. The file :file:`utils.py` was taken from Henryk Plötz's
cyberflex-shell_.
- Generic ISO-7816 smart card including secure messaging
- German electronic identity card (nPA) with |EAC| including |PACE|
- German electronic passport (ePass) with basic access control
- Cryptoflex smart card (incomplete)
The |vpcd| is a smart card driver for PCSC-Lite_. It allows
smart card applications to access the |vpicc| through the PC/SC API. By
default |vpicc| communicates with |vpcd| through a socket on localhost port
35963. 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_.
.. include:: autotools.rst
@@ -52,28 +63,26 @@ the following:
- PBKDF2_
- PIP_
The |vpcd| has the following dependencies:
- PCSC-Lite_
The |vpcd| depends on PCSC-Lite_.
================================================================================
Running the @PACKAGE_NAME@
================================================================================
First you need to make sure that pcscd loads the |vpcd|. You might need to run
:command:`update-reader.conf` to update pcscd's configuration file. Then
:command:`pcscd -f -d` should say something like "Attempting startup of
First you need to make sure that :command:`pcscd` loads the |vpcd|. You might
need to run :command:`update-reader.conf` to update its configuration file.
Then :command:`pcscd -f -d` should say something like "Attempting startup of
Virtual PCD"
Now you can run :command:`vicc` which connects to the |vpcd|. The command
:command:`vicc --help` gives an overview about the command line options.
You should now be able to access the |vpicc| through the system's
PC/SC API via |vpcd|/pcscd. You can use the opensc-explorer or pcsc_scan to test
that.
.. program-output:: vicc --help
You should now be able to access the |vpicc| through the PC/SC API via
|vpcd|/pcscd. You can use the :command:`opensc-explorer` or
:command:`pcsc_scan` for testing.
.. include:: questions.rst