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

working on documentation

Browse Source
This commit is contained in:
Frank Morgner
2013-05-13 08:15:05 +02:00
parent ae8c086606
commit 54579ae7d7
25 changed files with 305 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
ccid/doc/README.txt
View File

@@ -1,16 +1,16 @@
.. highlight:: sh .. highlight:: sh
.. |npa| replace:: :ref:`npa` .. |libnpa| replace:: :ref:`libnpa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. _ccid-emulator: .. _ccid-emulator:
################# ################################################################################
USB CCID Emulator USB CCID Emulator
################# ################################################################################
:Author: :Author:
Frank Morgner <morgner@informatik.hu-berlin.de> `Frank Morgner <morgner@informatik.hu-berlin.de>`_
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
@@ -18,7 +18,7 @@ USB CCID Emulator
The USB CCID Emulator forwards a locally present PC/SC smart card reader as a 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 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| enabling secure PIN entry and PIN modification. In combination with the |libnpa|
also |PACE| can be performed by the emulator. also |PACE| can be performed by the emulator.
If the machine running :command:`ccid-emulator` is in USB device mode, a local If the machine running :command:`ccid-emulator` is in USB device mode, a local
@@ -56,7 +56,7 @@ 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) - |libnpa| (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
@@ -69,8 +69,7 @@ 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 the kernel module :program:`gadgetfs`. A guide focused on Debian based systems
to run and compile GadgetFS, you can find in the `OpenMoko Wiki to run and compile GadgetFS, you can find in the `OpenMoko Wiki`_.
<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
@@ -86,24 +85,28 @@ 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 OpenSC, which is discouraged Without the |libnpa| the USB CCID Emulator needs the OpenSC components to be
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 installed (especially :file:`libopensc.so`). Here is an example of how to get
the standard installation of OpenSC without |PACE|:: the standard installation of OpenSC without |PACE|::
PREFIX=/tmp/install PREFIX=/tmp/install
OPENSC=opensc VSMARTCARD=vsmartcard
svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard $VSMARTCARD
cd $OPENSC cd $VSMARTCARD/ccid/src/opensc
autoreconf -i autoreconf --verbose --install
./configure --prefix=$PREFIX ./configure --prefix=$PREFIX
make make install && cd -
make install
Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to
configure the USB CCID Emulator to use it:: configure the USB CCID Emulator to use it::
./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc" 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.
***** *****
@@ -113,9 +116,9 @@ Usage
The USB CCID Emulator has various command line options to customize the appearance 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 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 mounted. The USB CCID Emulator is compatible with the unix driver libccid_
and the `Windows USB CCID driver and the `Windows USB CCID driver`_. To initialize |PACE| using the PC/SC API
<http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_. To initialize you need to patch libccid (see :file:`patches`). On Windows, the USB CCID Emulator
|PACE| using the PC/SC API you need to patch libccid_ (see :file:`patches`). currently has no support for |PACE|.
.. program-output:: ccid-emulator --help .. program-output:: ccid-emulator --help
@@ -129,8 +132,9 @@ Notes and References
.. target-notes:: .. target-notes::
.. [#f1] Note that the heavily outdated `Windows USB CCID driver`_ 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.
.. _`Windows USB CCID driver`: http://msdn.microsoft.com/en-us/windows/hardware/gg487509
.. _`OpenSC`: http://www.opensc-project.org/opensc
.. _`GadgetFS`: http://www.linux-usb.org/gadget/ .. _`GadgetFS`: http://www.linux-usb.org/gadget/
.. _`OpenSC`: http://www.opensc-project.org/opensc
.. _`libccid`: http://pcsclite.alioth.debian.org/ccid.html .. _`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>`_
.. [#f1] Note that the heavily outdated Windows USB CCID driver 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.

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

@@ -1,36 +1,36 @@
.. highlight:: sh .. highlight:: sh
.. |npa| replace:: :ref:`npa` .. |libnpa| replace:: :ref:`libnpa`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. _ccid-emulator: .. _ccid-emulator:
################# ################################################################################
USB CCID Emulator @PACKAGE_NAME@
################# ################################################################################
:Author: :Author:
Frank Morgner <morgner@informatik.hu-berlin.de> `Frank Morgner <morgner@informatik.hu-berlin.de>`_
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
Linux (Debian, Ubuntu, OpenMoko) Linux (Debian, Ubuntu, OpenMoko)
The USB CCID Emulator forwards a locally present PC/SC smart card reader as a The @PACKAGE_NAME@ forwards a locally present PC/SC smart card reader as a
standard USB CCID reader. USB CCID Emulator can be used as trusted intermediary standard USB CCID reader. @PACKAGE_NAME@ can be used as trusted intermediary
enabling secure PIN entry and PIN modification. In combination with the |npa| enabling secure PIN entry and PIN modification. In combination with the |libnpa|
also |PACE| can be performed by the emulator. also |PACE| can be performed by the emulator.
If the machine running :command:`ccid-emulator` is in USB device mode, a local 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 reader is forwareded via USB to another machine. If in USB host mode, the USB
CCID reader will locally be present. CCID reader will locally be present.
Applications on Windows and Unix-like systems can access the USB CCID Emulator 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 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 card driver is required since USB CCID drivers are usually shipped with the
modern OS. [#f1]_ modern OS. [#f1]_
Here is a subset of USB CCID commands supported by the USB CCID Emulator with Here is a subset of USB CCID commands supported by the @PACKAGE_NAME@ with
their PC/SC counterpart: their PC/SC counterpart:
================================== ============================================================ ================================== ============================================================
@@ -41,7 +41,7 @@ USB CCID PC/SC
``PC_to_RDR_Secure`` (proprietary) ``FEATURE_EXECUTE_PACE`` ``PC_to_RDR_Secure`` (proprietary) ``FEATURE_EXECUTE_PACE``
================================== ============================================================ ================================== ============================================================
The USB CCID Emulator 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.
@@ -52,13 +52,13 @@ tools.
.. include:: autotools.txt .. include:: autotools.txt
Running the USB CCID Emulator 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) - |libnpa| (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 @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
modern Windows and Unix-like systems by default. modern Windows and Unix-like systems by default.
@@ -69,8 +69,7 @@ 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 the kernel module :program:`gadgetfs`. A guide focused on Debian based systems
to run and compile GadgetFS, you can find in the `OpenMoko Wiki to run and compile GadgetFS, you can find in the `OpenMoko Wiki`_.
<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
@@ -86,36 +85,40 @@ 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 OpenSC, which is discouraged Without the |libnpa| the @PACKAGE_NAME@ needs the OpenSC components to be
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 installed (especially :file:`libopensc.so`). Here is an example of how to get
the standard installation of OpenSC without |PACE|:: the standard installation of OpenSC without |PACE|::
PREFIX=/tmp/install PREFIX=/tmp/install
OPENSC=opensc VSMARTCARD=vsmartcard
svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC git clone git://vsmartcard.git.sourceforge.net/gitroot/vsmartcard $VSMARTCARD
cd $OPENSC cd $VSMARTCARD/ccid/src/opensc
autoreconf -i autoreconf --verbose --install
./configure --prefix=$PREFIX ./configure --prefix=$PREFIX
make make install && cd -
make install
Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to
configure the USB CCID Emulator to use it:: configure the @PACKAGE_NAME@ to use it::
./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc" 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 Usage
***** *****
The USB CCID Emulator has various command line options to customize the appearance The @PACKAGE_NAME@ 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 on the USB host. In order to run the @PACKAGE_NAME@ GadgetFS must be loaded
and mounted. The USB CCID Emulator is compatible with the unix driver libccid_ and mounted. The @PACKAGE_NAME@ is compatible with the unix driver libccid_
and the `Windows USB CCID driver and the `Windows USB CCID driver`_. To initialize |PACE| using the PC/SC API
<http://msdn.microsoft.com/en-us/windows/hardware/gg487509>`_. To initialize you need to patch libccid (see :file:`patches`). On Windows, the @PACKAGE_NAME@
|PACE| using the PC/SC API you need to patch libccid_ (see :file:`patches`). currently has no support for |PACE|.
.. program-output:: ccid-emulator --help .. program-output:: ccid-emulator --help
@@ -129,8 +132,9 @@ Notes and References
.. target-notes:: .. target-notes::
.. [#f1] Note that the heavily outdated `Windows USB CCID driver`_ 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.
.. _`Windows USB CCID driver`: http://msdn.microsoft.com/en-us/windows/hardware/gg487509
.. _`OpenSC`: http://www.opensc-project.org/opensc
.. _`GadgetFS`: http://www.linux-usb.org/gadget/ .. _`GadgetFS`: http://www.linux-usb.org/gadget/
.. _`OpenSC`: http://www.opensc-project.org/opensc
.. _`libccid`: http://pcsclite.alioth.debian.org/ccid.html .. _`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>`_
.. [#f1] Note that the heavily outdated Windows USB CCID driver 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.

8
ccid/doc/autotools.txt
View File

@@ -5,10 +5,10 @@ Installation
************ ************
The USB CCID Emulator uses the GNU Build System to compile and install. If you are 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 have a look unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
around and can not find it, you are probably working bleeding edge in the it, you are probably working bleeding edge in the repository. Run the
repository. Run the following command in :file:`ccid-emulator` to following command in :file:`ccid-emulator` to get the missing standard
get the missing standard auxiliary files:: auxiliary files::
autoreconf --verbose --install autoreconf --verbose --install

2
ccid/doc/download.txt
View File

@@ -4,7 +4,7 @@
Download Download
******** ********
You can find the latest release of USB CCID Emulator `here You can find the latest release of USB CCID Emulator on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_. <http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository:: Alternatively, you can clone our git repository::

8
doc/autotools.txt.in
View File

@@ -5,10 +5,10 @@ Installation
************ ************
The @PACKAGE_NAME@ uses the GNU Build System to compile and install. If you are The @PACKAGE_NAME@ uses the GNU Build System to compile and install. If you are
unfamiliar with it, please have a look at :file:`INSTALL`. If you have a look unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
around and can not find it, you are probably working bleeding edge in the it, you are probably working bleeding edge in the repository. Run the
repository. Run the following command in :file:`@PACKAGE_TARNAME@` to following command in :file:`@PACKAGE_TARNAME@` to get the missing standard
get the missing standard auxiliary files:: auxiliary files::
autoreconf --verbose --install autoreconf --verbose --install

6
doc/conf.py
View File

@@ -74,7 +74,7 @@ release = '2012-04-11'
# List of patterns, relative to source directory, that match files and # List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files. # directories to ignore when looking for source files.
exclude_patterns = ['_build', '*/questions.txt', '*/autotools.txt', '*/download.txt'] exclude_patterns = ['_build', '*/questions.txt', '*/autotools.txt', '*/download.txt', '*/relay-note.txt']
# The reST default role (used for this markup: `text`) to use for all documents. # The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None #default_role = None
@@ -148,10 +148,10 @@ html_use_smartypants = True
#html_additional_pages = {} #html_additional_pages = {}
# If false, no module index is generated. # If false, no module index is generated.
#html_domain_indices = True html_domain_indices = False
# If false, no index is generated. # If false, no index is generated.
#html_use_index = True html_use_index = False
# If true, the index is split into individual pages for each letter. # If true, the index is split into individual pages for each letter.
#html_split_index = False #html_split_index = False

2
doc/download.txt.in
View File

@@ -4,7 +4,7 @@
Download Download
******** ********
You can find the latest release of @PACKAGE_NAME@ `here You can find the latest release of @PACKAGE_NAME@ on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_. <http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository:: Alternatively, you can clone our git repository::

46
npa/doc/README.txt
View File

@@ -1,17 +1,20 @@
.. highlight:: sh .. highlight:: sh
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. |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)`
.. |CSCA| replace:: :abbr:`CSCA (Country Signing Certificate Authority)`
.. |npa-tool| replace:: :command:`npa-tool` .. |npa-tool| replace:: :command:`npa-tool`
.. _libnpa:
.. _npa: ################################################################################
######################
nPA Smart Card Library nPA Smart Card Library
###################### ################################################################################
:Author: :Author:
Frank Morgner <morgner@informatik.hu-berlin.de> `Frank Morgner <morgner@informatik.hu-berlin.de>`_
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
@@ -40,17 +43,17 @@ compatible with OpenSC.
The nPA Smart Card Library has the following dependencies: The nPA Smart Card Library has the following dependencies:
- OpenSSL_
- OpenPACE_ - OpenPACE_
- OpenSC_ - OpenSC_
- OpenSSL_
==================================== ====================================
Installation of OpenPACE and OpenSSL Installation of OpenPACE and OpenSSL
==================================== ====================================
The nPA Smart Card Library links against OpenSSL_, which must be patched for OpenPACE_. The nPA Smart Card Library links against OpenSSL, which must be patched for OpenPACE.
Here is an example of how to get the standard installation of OpenPACE_ (with Here is an example of how to get the standard installation of OpenPACE (with
the required binaries for OpenSSL):: the required binaries for OpenSSL)::
PREFIX=/tmp/install PREFIX=/tmp/install
@@ -69,7 +72,7 @@ The file :file:`libcrypto.pc` should be located in ``$INSTALL/lib/pkgconfig``.
Installation of OpenSC Installation of OpenSC
====================== ======================
The nPA Smart Card Library need the OpenSC components to be installed (especially The nPA Smart Card Library needs the OpenSC components to be installed (especially
:file:`libopensc.so`). Here is an example of how to get a suitable installation :file:`libopensc.so`). Here is an example of how to get a suitable installation
of OpenSC:: of OpenSC::
@@ -84,9 +87,9 @@ of OpenSC::
Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Now :file:`libopensc.so` should be located in ``$PREFIX/lib``.
========================================== ================================================================================
Installation of the nPA Smart Card Library Installation of the nPA Smart Card Library
========================================== ================================================================================
To complete this step-by-step guide, here is how to install nPA Smart Card Library:: To complete this step-by-step guide, here is how to install nPA Smart Card Library::
@@ -105,17 +108,24 @@ Usage
The API to libnpa is documented in :ref:`npa-api`. It includes a simple The API to libnpa is documented in :ref:`npa-api`. It includes a simple
programming example. Here we will focus on the command line interface to the programming example. Here we will focus on the command line interface to the
library offered by the |npa-tool|. library offered by the |npa-tool|. It can perform |EAC| (i.e. |PACE|, |TA|,
|CA|) and read data groups from the identity card.
To pass a secret to |npa-tool| for |PACE|, command line parameters or 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|, environment variables can be used. If the smart card reader supports |PACE|,
the PIN pad is used. If none of these options apply, |npa-tool| will show a its PIN pad is used. If none of these options apply, |npa-tool| will show a
password prompt. password prompt.
|npa-tool| can send arbitrary APDUs to the nPA in the secure channel. APDUs The certificates certificate chain for |TA| should be passed in the correct
are entered interactively or through a file. APDUs are formatted in hex (upper order (finishing with the terminal certificate) so that the card can verify it.
or lower case) with an optional colon to separate the bytes. Example APDUs can |CA| is always done when the terminal's signature has been verified
be found in :file:`apdus`. successfully. The appropriate |CSCA| certificate will automatically be looked
up by OpenPACE.
|npa-tool| can send arbitrary APDUs to the nPA in the secure channel (after
|PACE| or |EAC|). 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 .. program-output:: npa-tool --help
@@ -150,6 +160,6 @@ Notes and References
.. target-notes:: .. target-notes::
.. _OpenPACE: http://openpace.sourceforge.net
.. _OpenSC: https://github.com/OpenSC/OpenSC .. _OpenSC: https://github.com/OpenSC/OpenSC
.. _OpenSSL: http://www.openssl.org .. _OpenSSL: http://www.openssl.org
.. _OpenPACE: http://openpace.sourceforge.net

64
npa/doc/README.txt.in
View File

@@ -1,17 +1,20 @@
.. highlight:: sh .. highlight:: sh
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. |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)`
.. |CSCA| replace:: :abbr:`CSCA (Country Signing Certificate Authority)`
.. |npa-tool| replace:: :command:`npa-tool` .. |npa-tool| replace:: :command:`npa-tool`
.. _libnpa:
.. _npa: ################################################################################
@PACKAGE_NAME@
###################### ################################################################################
nPA Smart Card Library
######################
:Author: :Author:
Frank Morgner <morgner@informatik.hu-berlin.de> `Frank Morgner <morgner@informatik.hu-berlin.de>`_
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
@@ -20,14 +23,14 @@ nPA Smart Card Library
:Potential Platforms: :Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...) Unix-like operating systems (Mac OS, Solaris, BSD, ...)
The nPA Smart Card Library offers an easy to use API for the new German identity card The @PACKAGE_NAME@ offers an easy to use API for the new German identity card
(neuer Personalausweis, nPA). The library also implements secure messaging, (neuer Personalausweis, nPA). The library also implements secure messaging,
which could also be used for other cards. The included |npa-tool| can 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. be used for PIN management or to send APDUs inside a secure channel.
The nPA Smart Card Library is implemented using OpenPACE_ and OpenSC_. nPA Smart Card Library The @PACKAGE_NAME@ is implemented using OpenPACE_ and OpenSC_. @PACKAGE_NAME@
implements and initializes Secure Messaging wrappers of OpenSC to allow a implements and initializes Secure Messaging wrappers of OpenSC to allow a
transparent SM usage in OpenSC. This allows nPA Smart Card Library to be fully transparent SM usage in OpenSC. This allows @PACKAGE_NAME@ to be fully
compatible with OpenSC. compatible with OpenSC.
@@ -38,19 +41,19 @@ compatible with OpenSC.
.. include:: autotools.txt .. include:: autotools.txt
The nPA Smart Card Library has the following dependencies: The @PACKAGE_NAME@ has the following dependencies:
- OpenSSL_
- OpenPACE_ - OpenPACE_
- OpenSC_ - OpenSC_
- OpenSSL_
==================================== ====================================
Installation of OpenPACE and OpenSSL Installation of OpenPACE and OpenSSL
==================================== ====================================
The nPA Smart Card Library links against OpenSSL_, which must be patched for OpenPACE_. The @PACKAGE_NAME@ links against OpenSSL, which must be patched for OpenPACE.
Here is an example of how to get the standard installation of OpenPACE_ (with Here is an example of how to get the standard installation of OpenPACE (with
the required binaries for OpenSSL):: the required binaries for OpenSSL)::
PREFIX=/tmp/install PREFIX=/tmp/install
@@ -69,7 +72,7 @@ The file :file:`libcrypto.pc` should be located in ``$INSTALL/lib/pkgconfig``.
Installation of OpenSC Installation of OpenSC
====================== ======================
The nPA Smart Card Library need the OpenSC components to be installed (especially The @PACKAGE_NAME@ needs the OpenSC components to be installed (especially
:file:`libopensc.so`). Here is an example of how to get a suitable installation :file:`libopensc.so`). Here is an example of how to get a suitable installation
of OpenSC:: of OpenSC::
@@ -84,11 +87,11 @@ of OpenSC::
Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Now :file:`libopensc.so` should be located in ``$PREFIX/lib``.
========================================== ================================================================================
Installation of the nPA Smart Card Library Installation of the @PACKAGE_NAME@
========================================== ================================================================================
To complete this step-by-step guide, here is how to install nPA Smart Card Library:: To complete this step-by-step guide, here is how to install @PACKAGE_NAME@::
cd $VSMARTCARD/npa cd $VSMARTCARD/npa
autoreconf --verbose --install autoreconf --verbose --install
@@ -105,17 +108,24 @@ Usage
The API to libnpa is documented in :ref:`npa-api`. It includes a simple The API to libnpa is documented in :ref:`npa-api`. It includes a simple
programming example. Here we will focus on the command line interface to the programming example. Here we will focus on the command line interface to the
library offered by the |npa-tool|. library offered by the |npa-tool|. It can perform |EAC| (i.e. |PACE|, |TA|,
|CA|) and read data groups from the identity card.
To pass a secret to |npa-tool| for |PACE|, command line parameters or 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|, environment variables can be used. If the smart card reader supports |PACE|,
the PIN pad is used. If none of these options apply, |npa-tool| will show a its PIN pad is used. If none of these options apply, |npa-tool| will show a
password prompt. password prompt.
|npa-tool| can send arbitrary APDUs to the nPA in the secure channel. APDUs The certificates certificate chain for |TA| should be passed in the correct
are entered interactively or through a file. APDUs are formatted in hex (upper order (finishing with the terminal certificate) so that the card can verify it.
or lower case) with an optional colon to separate the bytes. Example APDUs can |CA| is always done when the terminal's signature has been verified
be found in :file:`apdus`. successfully. The appropriate |CSCA| certificate will automatically be looked
up by OpenPACE.
|npa-tool| can send arbitrary APDUs to the nPA in the secure channel (after
|PACE| or |EAC|). 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 .. program-output:: npa-tool --help
@@ -124,8 +134,8 @@ Linking against libnpa
---------------------- ----------------------
Following the section Installation_ above, you have installed OpenSSL, Following the section Installation_ above, you have installed OpenSSL,
OpenPACE, OpenSC and the nPA Smart Card Library to `$PREFIX` which points to OpenPACE, OpenSC and the @PACKAGE_NAME@ to `$PREFIX` which points to
:file:`/tmp/install`. To compile a program using nPA Smart Card Library you also need :file:`/tmp/install`. To compile a program using @PACKAGE_NAME@ you also need
the OpenSC header files, which are located in the OpenSC header files, which are located in
:file:`$VSMARTCARD/npa/src/opensc` Here is how to compile an external program :file:`$VSMARTCARD/npa/src/opensc` Here is how to compile an external program
with these libraries:: with these libraries::
@@ -150,6 +160,6 @@ Notes and References
.. target-notes:: .. target-notes::
.. _OpenPACE: http://openpace.sourceforge.net
.. _OpenSC: https://github.com/OpenSC/OpenSC .. _OpenSC: https://github.com/OpenSC/OpenSC
.. _OpenSSL: http://www.openssl.org .. _OpenSSL: http://www.openssl.org
.. _OpenPACE: http://openpace.sourceforge.net

17
npa/doc/api.txt
View File

@@ -26,17 +26,19 @@ Authentication (:npa:`perform_terminal_authentication`) and Chip Authentication
will be initialized for the new SM channel. Again, libopensc can directly be will be initialized for the new SM channel. Again, libopensc can directly be
used to read identity attributes, for example. used to read identity attributes, for example.
Please consider the following overview to the API as incomplete. The `Doxygen .. note::
documentation <../_static/doxygen-npa/modules.html>`_ should be used as programmer's Please consider the following overview to the API as incomplete. The
reference since it is more detailed. `Doxygen documentation <../_static/doxygen-npa/modules.html>`_ should be
used as programmer's.
============================================================== ==============================================================
Interface to German identity card (neuer Personalausweis, nPA) Interface to German identity card (neuer Personalausweis, nPA)
============================================================== ==============================================================
The complete documentation can be found `here .. seealso::
<../_static/doxygen-npa/group__npa.html>`__. `Doxygen documentation of the nPA module
<../_static/doxygen-npa/group__npa.html>`__.
--------- ---------
Functions Functions
@@ -68,8 +70,9 @@ your environment <npa-usage>`.
Generic ISO 7816 Secure Messaging (SM) Generic ISO 7816 Secure Messaging (SM)
====================================== ======================================
The complete documentation can be found `here .. seealso::
<../_static/doxygen-npa/group__sm.html>`__. `Doxygen documentation of the SM module
<../_static/doxygen-npa/group__sm.html>`__.
----- -----
Types Types

8
npa/doc/autotools.txt
View File

@@ -5,10 +5,10 @@ Installation
************ ************
The nPA Smart Card Library uses the GNU Build System to compile and install. If you are The nPA Smart Card Library uses the GNU Build System to compile and install. If you are
unfamiliar with it, please have a look at :file:`INSTALL`. If you have a look unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
around and can not find it, you are probably working bleeding edge in the it, you are probably working bleeding edge in the repository. Run the
repository. Run the following command in :file:`npa` to following command in :file:`npa` to get the missing standard
get the missing standard auxiliary files:: auxiliary files::
autoreconf --verbose --install autoreconf --verbose --install

2
npa/doc/download.txt
View File

@@ -4,7 +4,7 @@
Download Download
******** ********
You can find the latest release of nPA Smart Card Library `here You can find the latest release of nPA Smart Card Library on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_. <http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository:: Alternatively, you can clone our git repository::

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

@@ -16,7 +16,7 @@ do_subst = $(SED) \
-e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \ -e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \
-e 's,[@]top_srcdir[@],$(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 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
doc: *.in doc: *.in
$(do_subst) < autotools.txt.in > autotools.txt $(do_subst) < autotools.txt.in > autotools.txt

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

@@ -2,13 +2,13 @@
.. _pcsc-relay: .. _pcsc-relay:
########### ################################################################################
PC/SC Relay PC/SC Relay
########### ################################################################################
:Authors: :Authors:
- Frank Morgner <morgner@informatik.hu-berlin.de> - `Frank Morgner <morgner@informatik.hu-berlin.de>`_
- Dominik Oepen <oepen@informatik.hu-berlin.de> - `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
@@ -19,21 +19,28 @@ PC/SC Relay
Welcome to PC/SC Relay. The purpose of PC/SC Relay is to relay a smart 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 card using an contact-less interface. Currently the following contact-less
backends: backends are supported:
- libnfc_ - `Hardware supported by libnfc`_
- OpenPICC_ - OpenPICC_
Command APDUs are received with the contact-less interface and forwarded to an Command APDUs are received with the contact-less interface and relayed. The
existing smart card via PC/SC. The Response APDUs are then sent back via RFID. Response APDUs are then sent back via RFID. The contact-less data will be
You can use PC/SC Relay in combination with the :ref:`vicc` to completely relayed to one of the following:
emulate an ISO/IEC 14443 smart card.
.. note:: - to a smart card inserted into one of the systems smart card readers. The
This software can actually be used in a relay attack allowing full access smart card reader must be accessible with PC/SC.
to the card. We discussed the impact especially on the `Relay attack - to a :ref:`vicc` that directly connects to :command:`pcsc-relay`. The virtual
against the German ID card`_, but it generally concerns *all* contact-less smart card's native interface is used and (despite its name) PC/SC Relay
smart cards. does not need to access PC/SC in this case.
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.
.. include:: relay-note.txt
.. include:: download.txt .. include:: download.txt
@@ -50,19 +57,20 @@ PC/SC Relay has the following dependencies:
Hints on libnfc Hints on libnfc
=============== ===============
PC/SC Relay links against libnfc_. Here is an example of how to get the standard Here is an example of how to get the standard
installation of the latter:: installation of libnfc::
PREFIX=/tmp/install PREFIX=/tmp/install
LIBNFC=libnfc LIBNFC=libnfc
svn co http://libnfc.googlecode.com/svn/trunk $LIBNFC git clone https://code.google.com/p/libnfc $LIBNFC
cd $LIBNFC cd $LIBNFC
autoreconf -i autoreconf -i
# See `./configure --help` for enabling support of additional hardware
./configure --prefix=$PREFIX ./configure --prefix=$PREFIX
make make
make install make install
Building PC/SC 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 PC/SC Relay to use it:: configure PC/SC Relay to use it::
@@ -75,12 +83,13 @@ Hints on PC/SC middleware
A PC/SC middleware is included by default in most modern operating systems. On 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 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 compile PC/SC Relay you will need to install the PCSC-Lite headers from
your distribution. your distribution.
Windows also ships with a PC/SC middleware in form of the Winscard module. Windows also ships with a PC/SC middleware in form of the Winscard module.
Microsoft's developement environment Visual Studio includes all necessary data PC/SC Relay can be (cross) compiled with MinGW-w64. Also, Microsoft's
for building PC/SC Relay. developement environment Visual Studio includes all necessary data for building
PC/SC Relay.
***** *****
@@ -99,7 +108,7 @@ Notes and References
.. target-notes:: .. target-notes::
.. _`Hardware supported by libnfc`: http://nfc-tools.org/index.php?title=Devices_compatibility_matrix
.. _libnfc: http://www.libnfc.org/ .. _libnfc: http://www.libnfc.org/
.. _OpenPICC: http://www.openpcd.org/OpenPICC .. _OpenPICC: http://www.openpcd.org/OpenPICC
.. _PCSC-lite: http://pcsclite.alioth.debian.org/ .. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _`Relay attack against the German ID card`: http://media.ccc.de/browse/congress/2010/27c3-4297-de-die_gesamte_technik_ist_sicher.html

63
pcsc-relay/doc/README.txt.in
View File

@@ -2,13 +2,13 @@
.. _pcsc-relay: .. _pcsc-relay:
########### ################################################################################
PC/SC Relay @PACKAGE_NAME@
########### ################################################################################
:Authors: :Authors:
- Frank Morgner <morgner@informatik.hu-berlin.de> - `Frank Morgner <morgner@informatik.hu-berlin.de>`_
- Dominik Oepen <oepen@informatik.hu-berlin.de> - `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
@@ -17,23 +17,30 @@ PC/SC Relay
:Potential Platforms: :Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...) Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Welcome to PC/SC Relay. The purpose of PC/SC Relay is to relay a smart 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 card using an contact-less interface. Currently the following contact-less
backends: backends are supported:
- libnfc_ - `Hardware supported by libnfc`_
- OpenPICC_ - OpenPICC_
Command APDUs are received with the contact-less interface and forwarded to an Command APDUs are received with the contact-less interface and relayed. The
existing smart card via PC/SC. The Response APDUs are then sent back via RFID. Response APDUs are then sent back via RFID. The contact-less data will be
You can use PC/SC Relay in combination with the :ref:`vicc` to completely relayed to one of the following:
emulate an ISO/IEC 14443 smart card.
.. note:: - to a smart card inserted into one of the systems smart card readers. The
This software can actually be used in a relay attack allowing full access smart card reader must be accessible with PC/SC.
to the card. We discussed the impact especially on the `Relay attack - to a :ref:`vicc` that directly connects to :command:`pcsc-relay`. The virtual
against the German ID card`_, but it generally concerns *all* contact-less smart card's native interface is used and (despite its name) @PACKAGE_NAME@
smart cards. does not need to access PC/SC in this case.
With @PACKAGE_NAME@ 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.
.. include:: relay-note.txt
.. include:: download.txt .. include:: download.txt
@@ -41,7 +48,7 @@ emulate an ISO/IEC 14443 smart card.
.. include:: autotools.txt .. include:: autotools.txt
PC/SC Relay has the following dependencies: @PACKAGE_NAME@ has the following dependencies:
- PC/SC middleware - PC/SC middleware
- libnfc_ - libnfc_
@@ -50,21 +57,22 @@ PC/SC Relay has the following dependencies:
Hints on libnfc Hints on libnfc
=============== ===============
PC/SC Relay links against libnfc_. Here is an example of how to get the standard Here is an example of how to get the standard
installation of the latter:: installation of libnfc::
PREFIX=/tmp/install PREFIX=/tmp/install
LIBNFC=libnfc LIBNFC=libnfc
svn co http://libnfc.googlecode.com/svn/trunk $LIBNFC git clone https://code.google.com/p/libnfc $LIBNFC
cd $LIBNFC cd $LIBNFC
autoreconf -i autoreconf -i
# See `./configure --help` for enabling support of additional hardware
./configure --prefix=$PREFIX ./configure --prefix=$PREFIX
make make
make install make install
Building PC/SC 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 PC/SC Relay to use it:: configure @PACKAGE_NAME@ to use it::
./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
@@ -75,12 +83,13 @@ Hints on PC/SC middleware
A PC/SC middleware is included by default in most modern operating systems. On 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 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 compile @PACKAGE_NAME@ you will need to install the PCSC-Lite headers from
your distribution. your distribution.
Windows also ships with a PC/SC middleware in form of the Winscard module. Windows also ships with a PC/SC middleware in form of the Winscard module.
Microsoft's developement environment Visual Studio includes all necessary data @PACKAGE_NAME@ can be (cross) compiled with MinGW-w64. Also, Microsoft's
for building PC/SC Relay. developement environment Visual Studio includes all necessary data for building
@PACKAGE_NAME@.
***** *****
@@ -99,7 +108,7 @@ Notes and References
.. target-notes:: .. target-notes::
.. _`Hardware supported by libnfc`: http://nfc-tools.org/index.php?title=Devices_compatibility_matrix
.. _libnfc: http://www.libnfc.org/ .. _libnfc: http://www.libnfc.org/
.. _OpenPICC: http://www.openpcd.org/OpenPICC .. _OpenPICC: http://www.openpcd.org/OpenPICC
.. _PCSC-lite: http://pcsclite.alioth.debian.org/ .. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _`Relay attack against the German ID card`: http://media.ccc.de/browse/congress/2010/27c3-4297-de-die_gesamte_technik_ist_sicher.html

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

@@ -5,10 +5,10 @@ Installation
************ ************
The PC/SC Relay uses the GNU Build System to compile and install. If you are 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 have a look unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
around and can not find it, you are probably working bleeding edge in the it, you are probably working bleeding edge in the repository. Run the
repository. Run the following command in :file:`pcsc-relay` to following command in :file:`pcsc-relay` to get the missing standard
get the missing standard auxiliary files:: auxiliary files::
autoreconf --verbose --install autoreconf --verbose --install

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

@@ -4,7 +4,7 @@
Download Download
******** ********
You can find the latest release of PC/SC Relay `here You can find the latest release of PC/SC Relay on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_. <http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository:: Alternatively, you can clone our git repository::

6
pcsc-relay/doc/relay-note.txt Normal file
View File

@@ -0,0 +1,6 @@
.. note::
This software can actually be used in a relay attack allowing full access
to the card. We discussed the impact especially on the `Relay attack
against the German ID card
<http://media.ccc.de/browse/congress/2010/27c3-4297-de-die_gesamte_technik_ist_sicher.html>`_,
but it generally concerns *all* contact-less smart cards.

2
virtualsmartcard/doc/Makefile.am
View File

@@ -17,7 +17,7 @@ do_subst = $(SED) \
-e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \ -e 's,[@]abs_top_srcdir[@],$(abs_top_srcdir),g' \
-e 's,[@]top_srcdir[@],$(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 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
dist_noinst_SCRIPTS = generate_modules.py dist_noinst_SCRIPTS = generate_modules.py

35
virtualsmartcard/doc/README.txt
View File

@@ -2,21 +2,21 @@
.. |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)` .. |BAC| replace:: :abbr:`BAC (Basic Access Control)`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |TA| replace:: :abbr:`TA (Terminal Authenticatation)` .. |TA| replace:: :abbr:`TA (Terminal Authenticatation)`
.. |CA| replace:: :abbr:`CA (Chip Authentication)` .. |CA| replace:: :abbr:`CA (Chip Authentication)`
.. |BAC| replace:: :abbr:`BAC (Basic Access Control)` .. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. _vicc: .. _vicc:
################## ################################################################################
Virtual Smart Card Virtual Smart Card
################## ################################################################################
:Authors: :Authors:
- Frank Morgner <morgner@informatik.hu-berlin.de> - `Frank Morgner <morgner@informatik.hu-berlin.de>`_
- Dominik Oepen <oepen@informatik.hu-berlin.de> - `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
@@ -46,6 +46,9 @@ reader.
The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_. The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_.
.. include:: relay-note.txt
.. include:: download.txt .. include:: download.txt
@@ -59,13 +62,14 @@ the following:
- PyCrypto_ - PyCrypto_
- PBKDF2_ - PBKDF2_
- PIP_ - PIP_
- OpenPACE_ (nPA emulation)
The |vpcd| depends on PCSC-Lite_. The |vpcd| depends on PCSC-Lite_.
****************************** ********************************************************************************
Running the Virtual Smart Card Running the Virtual Smart Card
****************************** ********************************************************************************
Fitxt you need to make sure that :command:`pcscd` loads the |vpcd|. You might Fitxt 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. need to run :command:`update-reader.conf` to update its configuration file.
@@ -82,9 +86,9 @@ You should now be able to access the |vpicc| through the PC/SC API via
:command:`pcsc_scan` for testing. :command:`pcsc_scan` for testing.
========================================================== ================================================================================
Accessing the Virtual Smart Card from Windows applications Accessing the Virtual Smart Card from Windows applications
========================================================== ================================================================================
Running |vpcd| under Windows is currently not supported, because it implements Running |vpcd| under Windows is currently not supported, because it implements
a smart card driver specific for PCSC-Lite (:command:`pcscd`). This means, that a smart card driver specific for PCSC-Lite (:command:`pcscd`). This means, that
@@ -121,10 +125,11 @@ Notes and References
.. target-notes:: .. target-notes::
.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/
.. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _PIP: http://www.pythonware.com/products/pil/
.. _PyCrypto: http://pycrypto.org/
.. _Python: http://www.python.org/
.. _cyberflex-shell: https://github.com/henryk/cyberflex-shell .. _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/ .. _pyscard: http://pyscard.sourceforge.net/
.. _PyCrypto: http://pycrypto.org/
.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/
.. _PIP: http://www.pythonware.com/products/pil/
.. _OpenPACE: http://openpace.sourceforge.net

47
virtualsmartcard/doc/README.txt.in
View File

@@ -2,21 +2,21 @@
.. |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)` .. |BAC| replace:: :abbr:`BAC (Basic Access Control)`
.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` .. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)`
.. |TA| replace:: :abbr:`TA (Terminal Authenticatation)` .. |TA| replace:: :abbr:`TA (Terminal Authenticatation)`
.. |CA| replace:: :abbr:`CA (Chip Authentication)` .. |CA| replace:: :abbr:`CA (Chip Authentication)`
.. |BAC| replace:: :abbr:`BAC (Basic Access Control)` .. |EAC| replace:: :abbr:`EAC (Extended Access Control)`
.. _vicc: .. _vicc:
################## ################################################################################
Virtual Smart Card @PACKAGE_NAME@
################## ################################################################################
:Authors: :Authors:
- Frank Morgner <morgner@informatik.hu-berlin.de> - `Frank Morgner <morgner@informatik.hu-berlin.de>`_
- Dominik Oepen <oepen@informatik.hu-berlin.de> - `Dominik Oepen <oepen@informatik.hu-berlin.de>`_
:License: :License:
GPL version 3 GPL version 3
:Tested Platforms: :Tested Platforms:
@@ -25,8 +25,8 @@ Virtual Smart Card
:Potential Platforms: :Potential Platforms:
Unix-like operating systems (Mac OS, Solaris, BSD, ...) Unix-like operating systems (Mac OS, Solaris, BSD, ...)
Virtual Smart Card emulates a smart card and makes it accessible through PC/SC. @PACKAGE_NAME@ emulates a smart card and makes it accessible through PC/SC.
Currently the Virtual Smart Card supports the following types of smart cards: Currently the @PACKAGE_NAME@ supports the following types of smart cards:
- Generic ISO-7816 smart card including secure messaging - Generic ISO-7816 smart card including secure messaging
- German electronic identity card (nPA) with complete support for |EAC| (|PACE|, |TA|, |CA|) - German electronic identity card (nPA) with complete support for |EAC| (|PACE|, |TA|, |CA|)
@@ -39,13 +39,16 @@ 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|, 35963. But the |vpicc| does not need to run on the same machine as the |vpcd|,
they can connect over the internet for example. they can connect over the internet for example.
Although the Virtual Smart Card is a software emulator, you can use 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 :ref:`pcsc-relay` to make it accessible to an external contact-less smart card
reader. reader.
The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_. The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_.
.. include:: relay-note.txt
.. include:: download.txt .. include:: download.txt
@@ -59,13 +62,14 @@ the following:
- PyCrypto_ - PyCrypto_
- PBKDF2_ - PBKDF2_
- PIP_ - PIP_
- OpenPACE_ (nPA emulation)
The |vpcd| depends on PCSC-Lite_. The |vpcd| depends on PCSC-Lite_.
****************************** ********************************************************************************
Running the Virtual Smart Card Running the @PACKAGE_NAME@
****************************** ********************************************************************************
Fitxt you need to make sure that :command:`pcscd` loads the |vpcd|. You might Fitxt 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. need to run :command:`update-reader.conf` to update its configuration file.
@@ -82,9 +86,9 @@ You should now be able to access the |vpicc| through the PC/SC API via
:command:`pcsc_scan` for testing. :command:`pcsc_scan` for testing.
========================================================== ================================================================================
Accessing the Virtual Smart Card from Windows applications Accessing the @PACKAGE_NAME@ from Windows applications
========================================================== ================================================================================
Running |vpcd| under Windows is currently not supported, because it implements Running |vpcd| under Windows is currently not supported, because it implements
a smart card driver specific for PCSC-Lite (:command:`pcscd`). This means, that a smart card driver specific for PCSC-Lite (:command:`pcscd`). This means, that
@@ -121,10 +125,11 @@ Notes and References
.. target-notes:: .. target-notes::
.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/
.. _PCSC-lite: http://pcsclite.alioth.debian.org/
.. _PIP: http://www.pythonware.com/products/pil/
.. _PyCrypto: http://pycrypto.org/
.. _Python: http://www.python.org/
.. _cyberflex-shell: https://github.com/henryk/cyberflex-shell .. _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/ .. _pyscard: http://pyscard.sourceforge.net/
.. _PyCrypto: http://pycrypto.org/
.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/
.. _PIP: http://www.pythonware.com/products/pil/
.. _OpenPACE: http://openpace.sourceforge.net

33
virtualsmartcard/doc/api.txt
View File

@@ -58,14 +58,14 @@ hook into. Here we only want to give an overview to the design, the complete
details can be found in section `Documentation to Virtual Smart Card`_. details can be found in section `Documentation to Virtual Smart Card`_.
Back to the cryptoflex example. Back to the cryptoflex example.
:class:`virtualsmartcard.VirtualSmartcard.VirtualICC` provides the connection :class:`~virtualsmartcard.VirtualSmartcard.VirtualICC` provides the connection
to the virtual smart card reader. It fetches an |APDU| and other requests from to the virtual smart card reader. It fetches an |APDU| and other requests from
the |vpcd|. In :class:`virtualsmartcard.VirtualSmartcard.VirtualICC` an |APDU| the |vpcd|. In :class:`~virtualsmartcard.VirtualSmartcard.VirtualICC` an |APDU|
is only a buffer that is forwarded to the smart card OS. First we modify is only a buffer that is forwarded to the smart card OS. First we modify
:class:`virtualsmartcard.VirtualSmartcard.VirtualICC` to recognize a new type :class:`~virtualsmartcard.VirtualSmartcard.VirtualICC` to recognize a new type
``"cryptoflex"`` and to load ``"cryptoflex"`` and to load
:class:`virtualsmartcard.VirtualSmartcard.CryptoflexOS`. The :class:`~virtualsmartcard.VirtualSmartcard.CryptoflexOS`. The
:class:`virtualsmartcard.CardGenerator` is used to create a file system and a :class:`~virtualsmartcard.CardGenerator` is used to create a file system and a
|SAM| specific to the cryptoflex (we come back to this later). |SAM| specific to the cryptoflex (we come back to this later).
.. literalinclude:: virtualsmartcard/VirtualSmartcard.py .. literalinclude:: virtualsmartcard/VirtualSmartcard.py
@@ -75,14 +75,14 @@ is only a buffer that is forwarded to the smart card OS. First we modify
Responses from our cryptoflex card look the same as for the 7816 card. But when Responses from our cryptoflex card look the same as for the 7816 card. But when
a command was successfull (or not) there is a little difference in what is a command was successfull (or not) there is a little difference in what is
returned. So we need to edit returned. So we need to edit
:class:`virtualsmartcard.VirtualSmartcard.CryptoflexOS.formatResult`, which is :class:`~virtualsmartcard.VirtualSmartcard.CryptoflexOS.formatResult`, which is
called to encode the |SWs| and the resulting data. called to encode the |SWs| and the resulting data.
.. literalinclude:: virtualsmartcard/VirtualSmartcard.py .. literalinclude:: virtualsmartcard/VirtualSmartcard.py
:pyobject: CryptoflexOS.formatResult :pyobject: CryptoflexOS.formatResult
Note that this also requires some insight knowledge about how Note that this also requires some insight knowledge about how
:class:`virtualsmartcard.VirtualSmartcard.Iso7816OS` works (see `above :class:`~virtualsmartcard.VirtualSmartcard.Iso7816OS` works (see `above
<Documentation to Virtual Smart Card>`_). <Documentation to Virtual Smart Card>`_).
The previously created |SAM| handles keys, encryption, secure messaging and so The previously created |SAM| handles keys, encryption, secure messaging and so
@@ -90,9 +90,9 @@ on (we will not go into more details here). The file system creates, selects
and reads contents of files or directories. File handling for our cryptoflex and reads contents of files or directories. File handling for our cryptoflex
card is similar to ISO 7816, but the meaning of P1, P2 and the |APDU| data is card is similar to ISO 7816, but the meaning of P1, P2 and the |APDU| data is
completely different when creating a file on the smart card. So we derive completely different when creating a file on the smart card. So we derive
:class:`virtualsmartcard.cards.cryptoflex.CryptoflexMF` from :class:`~virtualsmartcard.cards.cryptoflex.CryptoflexMF` from
:class:`virtualsmartcard.SmartcardFilesystem.MF` and modify :class:`~virtualsmartcard.SmartcardFilesystem.MF` and modify
:class:`virtualsmartcard.cards.cryptoflex.CryptoflexMF.create` to our needs. :class:`~virtualsmartcard.cards.cryptoflex.CryptoflexMF.create` to our needs.
.. literalinclude:: virtualsmartcard/cards/cryptoflex.py .. literalinclude:: virtualsmartcard/cards/cryptoflex.py
:pyobject: CryptoflexMF.create :pyobject: CryptoflexMF.create
@@ -112,18 +112,11 @@ If you have a card entirely different to ISO 7816, you surely want to avoid all
magic that is done while parsing a buffer (an |APDU|). As example we will magic that is done while parsing a buffer (an |APDU|). As example we will
connect to an other smart card using PC/SC and forward it to |vpcd|. connect to an other smart card using PC/SC and forward it to |vpcd|.
.. 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
card
<http://media.ccc.de/browse/congress/2010/27c3-4297-de-die_gesamte_technik_ist_sicher.html>`_,
but it generally concerns *all smart cards*.
As before with the cryptoflex card, we let As before with the cryptoflex card, we let
:class:`virtualsmartcard.VirtualSmartcard.VirtualICC` recognize the new type :class:`~virtualsmartcard.VirtualSmartcard.VirtualICC` recognize the new type
``"relay"``. :class:`virtualsmartcard.VirtualSmartcard.RelayOS` overwrites all ``"relay"``. :class:`~virtualsmartcard.VirtualSmartcard.RelayOS` overwrites all
main functions from the template main functions from the template
:class:`virtualsmartcard.VirtualSmartcard.SmartcardOS`. Its functions correspond :class:`~virtualsmartcard.VirtualSmartcard.SmartcardOS`. Its functions correspond
to the :ref:`commands sent by vpcd <vpcd-commands>`. If you know how to use to the :ref:`commands sent by vpcd <vpcd-commands>`. If you know how to use
`pyscard <http://pyscard.sourceforge.net/>`_ then the rest is pretty straight `pyscard <http://pyscard.sourceforge.net/>`_ then the rest is pretty straight
forward, but see yourself... forward, but see yourself...

8
virtualsmartcard/doc/autotools.txt
View File

@@ -5,10 +5,10 @@ Installation
************ ************
The Virtual Smart Card uses the GNU Build System to compile and install. If you are 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 have a look unfamiliar with it, please have a look at :file:`INSTALL`. If you can not find
around and can not find it, you are probably working bleeding edge in the it, you are probably working bleeding edge in the repository. Run the
repository. Run the following command in :file:`virtualsmartcard` to following command in :file:`virtualsmartcard` to get the missing standard
get the missing standard auxiliary files:: auxiliary files::
autoreconf --verbose --install autoreconf --verbose --install

2
virtualsmartcard/doc/download.txt
View File

@@ -4,7 +4,7 @@
Download Download
******** ********
You can find the latest release of Virtual Smart Card `here You can find the latest release of Virtual Smart Card on `Sourceforge
<http://sourceforge.net/projects/vsmartcard/files>`_. <http://sourceforge.net/projects/vsmartcard/files>`_.
Alternatively, you can clone our git repository:: Alternatively, you can clone our git repository::

1
virtualsmartcard/doc/relay-note.txt Symbolic link
View File

@@ -0,0 +1 @@
../../pcsc-relay/doc/relay-note.txt