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 \ do_subst = sed \
-e 's,[@]PACKAGE[@],$(PACKAGE),g' \
-e 's,[@]PACKAGE_NAME[@],$(PACKAGE_NAME),g' \ -e 's,[@]PACKAGE_NAME[@],$(PACKAGE_NAME),g' \
-e 's,[@]PACKAGE_TARNAME[@],$(PACKAGE_TARNAME),g' \ -e 's,[@]PACKAGE_TARNAME[@],$(PACKAGE_TARNAME),g' \
-e 's,[@]PACKAGE_BUGREPORT[@],$(PACKAGE_BUGREPORT),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 .. _libccid: http://pcsclite.alioth.debian.org/ccid.html
.. |npa| replace:: :ref:`npa` .. |npa| replace:: :ref:`npa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |win| replace::
******************************************************************************** ********************************************************************************
@@ -18,37 +20,46 @@ USB CCID Emulator
:Tested Platforms: :Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko) Linux (Debian, Ubuntu, OpenMoko)
Welcome to the USB CCID Emulator. The purpose of the USB CCID Emulator is to forward The USB CCID Emulator forwards a locally present PC/SC smart card reader as a
a PC/SC smartcard reader as a standard USB CCID reader. If the machine running standard USB CCID reader. USB CCID Emulator can be used as trusted intermediary
the USB CCID Emulator is in USB device mode, a local reader is forwareded via USB enabling secure PIN entry and PIN modification. In combination with the |npa|
to another machine. If in USB host mode, a USB CCID reader is virtually plugged also |PACE| can be performed by the emulator.
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 accesses a smart card through a local reader. Simple If the machine running :command:`ccid-emulator` is in USB device mode, a local
commands such as transmitting an APDU (``SCardTransmit`` and accordingly reader is forwareded via USB to another machine. If in USB host mode, the USB
``PC_to_RDR_XfrBlock``) are directly forwarded to the local reader/smart card. CCID reader will locally be present.
USB CCID Emulator can perform secure PIN verification and modification
(``FEATURE_VERIFY_PIN_DIRECT`` or ``FEATURE_MODIFY_PIN_DIRECT`` and accordingly Applications on Windows and Unix-like systems can access the USB CCID Emulator
``PC_to_RDR_Secure``). Moreover the USB CCID Emulator has support the for Password through PC/SC as if it was a real smart card reader. No installation of a smart
Authenticated Connection Establishment (PACE) using |npa| card driver is required since USB CCID drivers are usually shipped with the
(``FEATURE_EXECUTE_PACE``). Thus USB CCID Emulator can be used with the German modern OS. [#f1]_
identity card ("neuer Personalausweis", nPA) similar to a "Standardleser"
(CAT-S) or "Komfortleser" (CAT-K). 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 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_ code are based on the GadgetFS example and on the source code of the OpenSC_
tools. 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 .. include:: autotools.rst
Running the USB CCID Emulator has the following dependencies: Running the USB CCID Emulator has the following dependencies:
- Linux Kernel with GadgetFS_ - Linux Kernel with GadgetFS_
- OpenSC_ - 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 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 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 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 the kernel module :program:`gadgetfs`. A guide focused on Debian based systems
and compile :program:`gadgetfs`, you can find `here to run and compile GadgetFS_, you can find `here
<http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_. <http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_.
On OpenMoko it is likely that you need to `patch your kernel 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 <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 multiple times between :program:`gadgetfs` and :program:`g_ether`, `another
<http://docs.openmoko.org/trac/ticket/2240)>`_. 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 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 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 Hints on OpenSC
--------------- ---------------
Without the |npa| the USB CCID Emulator links against libopensc, which is Without the |npa| the USB CCID Emulator links against OpenSC, which is discouraged
discouraged and hindered since OpenSC version >= 0.12. (We really need to get and hindered since OpenSC version >= 0.12. You need the OpenSC components to be
rid of this dependency or integrate better into the OpenSC-framework.) You need installed (especially :file:`libopensc.so`). Here is an example of how to get
the OpenSC components to be installed (especially :file:`libopensc.so`). Here the standard installation of OpenSC_ without |PACE|::
is an example of how to get the standard installation of OpenSC_::
PREFIX=/tmp/install PREFIX=/tmp/install
OPENSC=opensc OPENSC=opensc
@@ -103,19 +113,14 @@ configure the USB CCID Emulator to use it::
Usage Usage
===== =====
The USB CCID Emulator has various command line options to customize the appearance on The USB CCID Emulator has various command line options to customize the appearance
the USB host. In order to run the USB CCID Emulator GadgetFS_ must be loaded and on the USB host. In order to run the USB CCID Emulator GadgetFS_ must be loaded
mounted. The USB CCID Emulator is compatible with the unix driver libccid_ and the and mounted. The USB CCID Emulator is compatible with the unix driver libccid_
windows smart card driver. To initialize PACE using the PC/SC API you need to and the `Windows USB CCID driver
patch libccid and pcsc-lite (see directory patches). <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 .. 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 .. include:: questions.rst

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

@@ -5,6 +5,8 @@
.. _libccid: http://pcsclite.alioth.debian.org/ccid.html .. _libccid: http://pcsclite.alioth.debian.org/ccid.html
.. |npa| replace:: :ref:`npa` .. |npa| replace:: :ref:`npa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |win| replace::
******************************************************************************** ********************************************************************************
@@ -18,37 +20,46 @@
:Tested Platforms: :Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko) Linux (Debian, Ubuntu, OpenMoko)
Welcome to the @PACKAGE_NAME@. The purpose of the @PACKAGE_NAME@ is to forward The @PACKAGE_NAME@ forwards a locally present PC/SC smart card reader as a
a PC/SC smartcard reader as a standard USB CCID reader. If the machine running standard USB CCID reader. @PACKAGE_NAME@ can be used as trusted intermediary
the @PACKAGE_NAME@ is in USB device mode, a local reader is forwareded via USB enabling secure PIN entry and PIN modification. In combination with the |npa|
to another machine. If in USB host mode, a USB CCID reader is virtually plugged also |PACE| can be performed by the emulator.
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@ accesses a smart card through a local reader. Simple If the machine running :command:`@PACKAGE@` is in USB device mode, a local
commands such as transmitting an APDU (``SCardTransmit`` and accordingly reader is forwareded via USB to another machine. If in USB host mode, the USB
``PC_to_RDR_XfrBlock``) are directly forwarded to the local reader/smart card. CCID reader will locally be present.
@PACKAGE_NAME@ can perform secure PIN verification and modification
(``FEATURE_VERIFY_PIN_DIRECT`` or ``FEATURE_MODIFY_PIN_DIRECT`` and accordingly Applications on Windows and Unix-like systems can access the @PACKAGE_NAME@
``PC_to_RDR_Secure``). Moreover the @PACKAGE_NAME@ has support the for Password through PC/SC as if it was a real smart card reader. No installation of a smart
Authenticated Connection Establishment (PACE) using |npa| card driver is required since USB CCID drivers are usually shipped with the
(``FEATURE_EXECUTE_PACE``). Thus @PACKAGE_NAME@ can be used with the German modern OS. [#f1]_
identity card ("neuer Personalausweis", nPA) similar to a "Standardleser"
(CAT-S) or "Komfortleser" (CAT-K). 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 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_ code are based on the GadgetFS example and on the source code of the OpenSC_
tools. 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 .. include:: autotools.rst
Running the @PACKAGE_NAME@ has the following dependencies: Running the @PACKAGE_NAME@ has the following dependencies:
- Linux Kernel with GadgetFS_ - Linux Kernel with GadgetFS_
- OpenSC_ - 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 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 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 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 the kernel module :program:`gadgetfs`. A guide focused on Debian based systems
and compile :program:`gadgetfs`, you can find `here to run and compile GadgetFS_, you can find `here
<http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_. <http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_.
On OpenMoko it is likely that you need to `patch your kernel 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 <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 multiple times between :program:`gadgetfs` and :program:`g_ether`, `another
<http://docs.openmoko.org/trac/ticket/2240)>`_. 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 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 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 Hints on OpenSC
--------------- ---------------
Without the |npa| the @PACKAGE_NAME@ links against libopensc, which is Without the |npa| the @PACKAGE_NAME@ links against OpenSC, which is discouraged
discouraged and hindered since OpenSC version >= 0.12. (We really need to get and hindered since OpenSC version >= 0.12. You need the OpenSC components to be
rid of this dependency or integrate better into the OpenSC-framework.) You need installed (especially :file:`libopensc.so`). Here is an example of how to get
the OpenSC components to be installed (especially :file:`libopensc.so`). Here the standard installation of OpenSC_ without |PACE|::
is an example of how to get the standard installation of OpenSC_::
PREFIX=/tmp/install PREFIX=/tmp/install
OPENSC=opensc OPENSC=opensc
@@ -103,19 +113,14 @@ configure the @PACKAGE_NAME@ to use it::
Usage Usage
===== =====
The @PACKAGE_NAME@ has various command line options to customize the appearance on The @PACKAGE_NAME@ has various command line options to customize the appearance
the USB host. In order to run the @PACKAGE_NAME@ GadgetFS_ must be loaded and on the USB host. In order to run the @PACKAGE_NAME@ GadgetFS_ must be loaded
mounted. The @PACKAGE_NAME@ is compatible with the unix driver libccid_ and the and mounted. The @PACKAGE_NAME@ is compatible with the unix driver libccid_
windows smart card driver. To initialize PACE using the PC/SC API you need to and the `Windows USB CCID driver
patch libccid and pcsc-lite (see directory patches). <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 .. program-output:: @PACKAGE@ --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
.. include:: questions.rst .. 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|: Currently the following projects are part of |vsmartcard|:
.. toctree:: .. toctree::
:titlesonly:
virtualsmartcard/README virtualsmartcard/README
pcsc-relay/README pcsc-relay/README
npa/README
ccid/README ccid/README
npa/README
.. toctree:: .. toctree::
:hidden: :hidden:
virtualsmartcard/autotools
pcsc-relay/autotools
npa/autotools
ccid/autotools ccid/autotools
virtualsmartcard/questions
pcsc-relay/questions
npa/questions
ccid/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 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 functionality of some library? Apart from requesting a new feature, you can
have a look at these programming guides and try yourself: have a look at these programming guides and try yourself:
.. toctree:: .. toctree::
:titlesonly:
virtualsmartcard/api virtualsmartcard/api
npa/api npa/api

51
npa/doc/README.rst
View File

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

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

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

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

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

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

@@ -1,52 +1,58 @@
.. highlight:: sh .. highlight:: sh
.. _libnfc: http://www.libnfc.org/ .. _libnfc: http://www.libnfc.org/
.. _OpenPICC: http://www.openpcd.org/OpenPICC
.. _PCSC-lite: http://pcsclite.alioth.debian.org/ .. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _pcsc-relay:
******************************************************************************** ********************************************************************************
PC/SC Relay PC/SC Relay
******************************************************************************** ********************************************************************************
:Authors: :Authors:
- Dominik Oepen <oepen@informatik.hu-berlin.de>
- Frank Morgner <morgner@informatik.hu-berlin.de> - Frank Morgner <morgner@informatik.hu-berlin.de>
- Dominik Oepen <oepen@informatik.hu-berlin.de>
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko)
:Potential Platforms:
- Windows - 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 Welcome to PC/SC Relay. The purpose of PC/SC Relay is to relay a smart
OpenPICC or from a libnfc device to a smart card via the PCSC middleware. You card using an contact-less interface. Currently the following contact-less
can use this program in combination with the virtual smart card to emulate a backends:
ISO/IEC 14443 smart card.
- 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:: .. note::
This software can actually be used in a relay attack allowing full access 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 card
<http://media.ccc.de/browse/congress/2010/27c3-4297-de-die_gesamte_technik_ist_sicher.html>`_, <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 .. include:: autotools.rst
pcsc-relay has the following dependencies: PC/SC Relay has the following dependencies:
- PC/SC middleware - PC/SC middleware
- libnfc_ - libnfc_
.. program-output:: pcsc-relay --help
--------------- ---------------
Hints on libnfc 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:: installation of the latter::
PREFIX=/tmp/install PREFIX=/tmp/install
@@ -58,9 +64,9 @@ installation of the latter::
make make
make install 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 :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 ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
@@ -69,12 +75,21 @@ configure pcsc-relay to use it::
Hints on PC/SC middleware Hints on PC/SC middleware
------------------------- -------------------------
PC/SC is included by default in most modern operating systems. On Unix-like A PC/SC middleware is included by default in most modern operating systems. On
systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To compile Unix-like systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To
pcsc-relay you will need to install the PCSC-Lite headers from your compile PC/SC Relay you will need to install the PCSC-Lite_ headers from
distribution. Windows also ships with a PC/SC middleware in form of the your distribution.
Winscard module. Microsoft's developement environment Visual Studio includes
all necessary data for building pcsc-relay. 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 .. include:: questions.rst

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

@@ -1,52 +1,58 @@
.. highlight:: sh .. highlight:: sh
.. _libnfc: http://www.libnfc.org/ .. _libnfc: http://www.libnfc.org/
.. _OpenPICC: http://www.openpcd.org/OpenPICC
.. _PCSC-lite: http://pcsclite.alioth.debian.org/ .. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _pcsc-relay:
******************************************************************************** ********************************************************************************
@PACKAGE_NAME@ @PACKAGE_NAME@
******************************************************************************** ********************************************************************************
:Authors: :Authors:
- Dominik Oepen <oepen@informatik.hu-berlin.de>
- Frank Morgner <morgner@informatik.hu-berlin.de> - Frank Morgner <morgner@informatik.hu-berlin.de>
- Dominik Oepen <oepen@informatik.hu-berlin.de>
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko)
:Potential Platforms:
- Windows - 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 Welcome to @PACKAGE_NAME@. The purpose of @PACKAGE_NAME@ is to relay a smart
OpenPICC or from a libnfc device to a smart card via the PCSC middleware. You card using an contact-less interface. Currently the following contact-less
can use this program in combination with the virtual smart card to emulate a backends:
ISO/IEC 14443 smart card.
- 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:: .. note::
This software can actually be used in a relay attack allowing full access 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 card
<http://media.ccc.de/browse/congress/2010/27c3-4297-de-die_gesamte_technik_ist_sicher.html>`_, <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 .. include:: autotools.rst
pcsc-relay has the following dependencies: @PACKAGE_NAME@ has the following dependencies:
- PC/SC middleware - PC/SC middleware
- libnfc_ - libnfc_
.. program-output:: pcsc-relay --help
--------------- ---------------
Hints on libnfc 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:: installation of the latter::
PREFIX=/tmp/install PREFIX=/tmp/install
@@ -58,9 +64,9 @@ installation of the latter::
make make
make install 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 :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 ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
@@ -69,12 +75,21 @@ configure pcsc-relay to use it::
Hints on PC/SC middleware Hints on PC/SC middleware
------------------------- -------------------------
PC/SC is included by default in most modern operating systems. On Unix-like A PC/SC middleware is included by default in most modern operating systems. On
systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To compile Unix-like systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To
pcsc-relay you will need to install the PCSC-Lite headers from your compile @PACKAGE_NAME@ you will need to install the PCSC-Lite_ headers from
distribution. Windows also ships with a PC/SC middleware in form of the your distribution.
Winscard module. Microsoft's developement environment Visual Studio includes
all necessary data for building pcsc-relay. 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 .. include:: questions.rst

49
virtualsmartcard/doc/README.rst
View File

@@ -11,7 +11,10 @@
.. |vpicc| replace:: :abbr:`vpicc (virtual smart card)` .. |vpicc| replace:: :abbr:`vpicc (virtual smart card)`
.. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)` .. |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 Virtual Smart Card
@@ -28,17 +31,25 @@ Virtual Smart Card
:Potential Platforms: :Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...) 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 Virtual Smart Card emulates a smart card and makes it accessible through PC/SC.
smart card and make it accessible through PCSC. Currently the virtual smart Currently the Virtual Smart Card supports the following types of smart cards:
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_.
By default the vicc communicates with the vpcd through a socket on localhost - Generic ISO-7816 smart card including secure messaging
port 35963. The file :file:`utils.py` was taken from Henryk Plötz's - German electronic identity card (nPA) with |EAC| including |PACE|
cyberflex-shell_. - 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 .. include:: autotools.rst
@@ -52,28 +63,26 @@ the following:
- PBKDF2_ - PBKDF2_
- PIP_ - PIP_
The |vpcd| has the following dependencies: The |vpcd| depends on PCSC-Lite_.
- PCSC-Lite_
================================================================================ ================================================================================
Running the Virtual Smart Card Running the Virtual Smart Card
================================================================================ ================================================================================
First you need to make sure that pcscd loads the |vpcd|. You might need to run First you need to make sure that :command:`pcscd` loads the |vpcd|. You might
:command:`update-reader.conf` to update pcscd's configuration file. Then need to run :command:`update-reader.conf` to update its configuration file.
:command:`pcscd -f -d` should say something like "Attempting startup of Then :command:`pcscd -f -d` should say something like "Attempting startup of
Virtual PCD" Virtual PCD"
Now you can run :command:`vicc` which connects to the |vpcd|. The command Now you can run :command:`vicc` which connects to the |vpcd|. The command
:command:`vicc --help` gives an overview about the command line options. :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 .. 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 .. include:: questions.rst

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

@@ -11,7 +11,10 @@
.. |vpicc| replace:: :abbr:`vpicc (virtual smart card)` .. |vpicc| replace:: :abbr:`vpicc (virtual smart card)`
.. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)` .. |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@ @PACKAGE_NAME@
@@ -28,17 +31,25 @@
:Potential Platforms: :Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...) Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Welcome to the @PACKAGE_NAME@. The purpose of the @PACKAGE_NAME@ is to emulate a @PACKAGE_NAME@ emulates a smart card and makes it accessible through PC/SC.
smart card and make it accessible through PCSC. Currently the virtual smart Currently the @PACKAGE_NAME@ supports the following types of smart cards:
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_.
By default the vicc communicates with the vpcd through a socket on localhost - Generic ISO-7816 smart card including secure messaging
port 35963. The file :file:`utils.py` was taken from Henryk Plötz's - German electronic identity card (nPA) with |EAC| including |PACE|
cyberflex-shell_. - 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 .. include:: autotools.rst
@@ -52,28 +63,26 @@ the following:
- PBKDF2_ - PBKDF2_
- PIP_ - PIP_
The |vpcd| has the following dependencies: The |vpcd| depends on PCSC-Lite_.
- PCSC-Lite_
================================================================================ ================================================================================
Running the @PACKAGE_NAME@ Running the @PACKAGE_NAME@
================================================================================ ================================================================================
First you need to make sure that pcscd loads the |vpcd|. You might need to run First you need to make sure that :command:`pcscd` loads the |vpcd|. You might
:command:`update-reader.conf` to update pcscd's configuration file. Then need to run :command:`update-reader.conf` to update its configuration file.
:command:`pcscd -f -d` should say something like "Attempting startup of Then :command:`pcscd -f -d` should say something like "Attempting startup of
Virtual PCD" Virtual PCD"
Now you can run :command:`vicc` which connects to the |vpcd|. The command Now you can run :command:`vicc` which connects to the |vpcd|. The command
:command:`vicc --help` gives an overview about the command line options. :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 .. 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 .. include:: questions.rst