From 93c1a69d7fd47cd155e78a9987ae4007db519cea Mon Sep 17 00:00:00 2001 From: frankmorgner Date: Wed, 11 Apr 2012 03:44:48 +0000 Subject: [PATCH] updated documentation git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@743 96b47cad-a561-4643-ad3b-153ac7d7599c --- ccid/doc/Makefile.am | 1 + ccid/doc/README.rst | 81 +++++++++++++++-------------- ccid/doc/README.rst.in | 83 ++++++++++++++++-------------- doc/index.rst | 16 +++--- npa/doc/README.rst | 51 +++++++++--------- npa/doc/README.rst.in | 49 +++++++++--------- pcsc-relay/doc/Makefile.am | 1 + pcsc-relay/doc/README.rst | 61 +++++++++++++--------- pcsc-relay/doc/README.rst.in | 61 +++++++++++++--------- virtualsmartcard/doc/README.rst | 49 +++++++++++------- virtualsmartcard/doc/README.rst.in | 49 +++++++++++------- 11 files changed, 285 insertions(+), 217 deletions(-) diff --git a/ccid/doc/Makefile.am b/ccid/doc/Makefile.am index e4374b0..9fc9aad 100644 --- a/ccid/doc/Makefile.am +++ b/ccid/doc/Makefile.am @@ -1,4 +1,5 @@ do_subst = sed \ + -e 's,[@]PACKAGE[@],$(PACKAGE),g' \ -e 's,[@]PACKAGE_NAME[@],$(PACKAGE_NAME),g' \ -e 's,[@]PACKAGE_TARNAME[@],$(PACKAGE_TARNAME),g' \ -e 's,[@]PACKAGE_BUGREPORT[@],$(PACKAGE_BUGREPORT),g' \ diff --git a/ccid/doc/README.rst b/ccid/doc/README.rst index aaa8287..046ccb4 100644 --- a/ccid/doc/README.rst +++ b/ccid/doc/README.rst @@ -5,6 +5,8 @@ .. _libccid: http://pcsclite.alioth.debian.org/ccid.html .. |npa| replace:: :ref:`npa` +.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` +.. |win| replace:: ******************************************************************************** @@ -18,37 +20,46 @@ USB CCID Emulator :Tested Platforms: Linux (Debian, Ubuntu, OpenMoko) -Welcome to the USB CCID Emulator. The purpose of the USB CCID Emulator is to forward -a PC/SC smartcard reader as a standard USB CCID reader. If the machine running -the USB CCID Emulator is in USB device mode, a local reader is forwareded via USB -to another machine. If in USB host mode, a USB CCID reader is virtually plugged -into the machine running the USB CCID Emulator. Applications on Windows and -Unix-like systems can access the USB CCID Emulator through PC/SC as if it were a -real smart card reader. +The USB CCID Emulator forwards a locally present PC/SC smart card reader as a +standard USB CCID reader. USB CCID Emulator can be used as trusted intermediary +enabling secure PIN entry and PIN modification. In combination with the |npa| +also |PACE| can be performed by the emulator. -The USB CCID Emulator accesses a smart card through a local reader. Simple -commands such as transmitting an APDU (``SCardTransmit`` and accordingly -``PC_to_RDR_XfrBlock``) are directly forwarded to the local reader/smart card. -USB CCID Emulator can perform secure PIN verification and modification -(``FEATURE_VERIFY_PIN_DIRECT`` or ``FEATURE_MODIFY_PIN_DIRECT`` and accordingly -``PC_to_RDR_Secure``). Moreover the USB CCID Emulator has support the for Password -Authenticated Connection Establishment (PACE) using |npa| -(``FEATURE_EXECUTE_PACE``). Thus USB CCID Emulator can be used with the German -identity card ("neuer Personalausweis", nPA) similar to a "Standardleser" -(CAT-S) or "Komfortleser" (CAT-K). +If the machine running :command:`ccid-emulator` is in USB device mode, a local +reader is forwareded via USB to another machine. If in USB host mode, the USB +CCID reader will locally be present. + +Applications on Windows and Unix-like systems can access the USB CCID Emulator +through PC/SC as if it was a real smart card reader. No installation of a smart +card driver is required since USB CCID drivers are usually shipped with the +modern OS. [#f1]_ + +Here is a subset of USB CCID commands supported by the USB CCID Emulator with +their PC/SC counterpart: + +================================== ============================================================ +USB CCID PC/SC +================================== ============================================================ +``PC_to_RDR_XfrBlock`` ``SCardTransmit`` +``PC_to_RDR_Secure`` ``FEATURE_VERIFY_PIN_DIRECT``, ``FEATURE_MODIFY_PIN_DIRECT`` +``PC_to_RDR_Secure`` (proprietary) ``FEATURE_EXECUTE_PACE`` +================================== ============================================================ The USB CCID Emulator is implemented using GadgetFS_. Some fragments of the source code are based on the GadgetFS example and on the source code of the OpenSC_ tools. +.. [#f1] Note that the heavily outdated `Windows USB CCID driver `_ does not support secure PIN entry or PIN modification. USB CCID Emulator comes with a patch for libccid_ to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction. + + .. include:: autotools.rst Running the USB CCID Emulator has the following dependencies: - Linux Kernel with GadgetFS_ - OpenSC_ -- |npa| (only if support for PACE is enabled) +- |npa| (only if support for |PACE| is enabled) Whereas using the USB CCID Emulator on the host system as smart card reader only needs a usable PC/SC middleware with USB CCID driver. This is the case for most @@ -60,14 +71,14 @@ Hints on GadgetFS ----------------- To create a USB Gadget in both USB host and USB client mode, you need to load -the kernel module :program:`gadgetfs`. A guide focused on Debian based systems to run -and compile :program:`gadgetfs`, you can find `here +the kernel module :program:`gadgetfs`. A guide focused on Debian based systems +to run and compile GadgetFS_, you can find `here `_. On OpenMoko it is likely that you need to `patch your kernel `_. 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 +patch is needed `_. If you are using a more recent version of :program:`dummy_hcd` and get an error loading the module, you maybe want to check out `this patch @@ -78,11 +89,10 @@ loading the module, you maybe want to check out `this patch Hints on OpenSC --------------- -Without the |npa| the USB CCID Emulator links against libopensc, which is -discouraged and hindered since OpenSC version >= 0.12. (We really need to get -rid of this dependency or integrate better into the OpenSC-framework.) You need -the OpenSC components to be installed (especially :file:`libopensc.so`). Here -is an example of how to get the standard installation of OpenSC_:: +Without the |npa| the USB CCID Emulator links against OpenSC, which is discouraged +and hindered since OpenSC version >= 0.12. You need the OpenSC components to be +installed (especially :file:`libopensc.so`). Here is an example of how to get +the standard installation of OpenSC_ without |PACE|:: PREFIX=/tmp/install OPENSC=opensc @@ -103,19 +113,14 @@ configure the USB CCID Emulator to use it:: Usage ===== -The USB CCID Emulator has various command line options to customize the appearance on -the USB host. In order to run the USB CCID Emulator GadgetFS_ must be loaded and -mounted. The USB CCID Emulator is compatible with the unix driver libccid_ and the -windows smart card driver. To initialize PACE using the PC/SC API you need to -patch libccid and pcsc-lite (see directory patches). +The USB CCID Emulator has various command line options to customize the appearance +on the USB host. In order to run the USB CCID Emulator GadgetFS_ must be loaded +and mounted. The USB CCID Emulator is compatible with the unix driver libccid_ +and the `Windows USB CCID driver +`_. To initialize +|PACE| using the PC/SC API you need to patch libccid_ (see :file:`patches`). .. program-output:: ccid-emulator --help -cats-test can be used to test the PACE capabilities of a smart card reader with -PACE support (such as the USB CCID Emulator or any other "Standardleser" CAT-S or -"Komfortleser" CAT-C) via PC/SC. - -.. program-output:: cats-test - .. include:: questions.rst diff --git a/ccid/doc/README.rst.in b/ccid/doc/README.rst.in index 8837490..1b97d1c 100644 --- a/ccid/doc/README.rst.in +++ b/ccid/doc/README.rst.in @@ -5,6 +5,8 @@ .. _libccid: http://pcsclite.alioth.debian.org/ccid.html .. |npa| replace:: :ref:`npa` +.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` +.. |win| replace:: ******************************************************************************** @@ -18,37 +20,46 @@ :Tested Platforms: Linux (Debian, Ubuntu, OpenMoko) -Welcome to the @PACKAGE_NAME@. The purpose of the @PACKAGE_NAME@ is to forward -a PC/SC smartcard reader as a standard USB CCID reader. If the machine running -the @PACKAGE_NAME@ is in USB device mode, a local reader is forwareded via USB -to another machine. If in USB host mode, a USB CCID reader is virtually plugged -into the machine running the @PACKAGE_NAME@. Applications on Windows and -Unix-like systems can access the @PACKAGE_NAME@ through PC/SC as if it were a -real smart card reader. +The @PACKAGE_NAME@ forwards a locally present PC/SC smart card reader as a +standard USB CCID reader. @PACKAGE_NAME@ can be used as trusted intermediary +enabling secure PIN entry and PIN modification. In combination with the |npa| +also |PACE| can be performed by the emulator. -The @PACKAGE_NAME@ accesses a smart card through a local reader. Simple -commands such as transmitting an APDU (``SCardTransmit`` and accordingly -``PC_to_RDR_XfrBlock``) are directly forwarded to the local reader/smart card. -@PACKAGE_NAME@ can perform secure PIN verification and modification -(``FEATURE_VERIFY_PIN_DIRECT`` or ``FEATURE_MODIFY_PIN_DIRECT`` and accordingly -``PC_to_RDR_Secure``). Moreover the @PACKAGE_NAME@ has support the for Password -Authenticated Connection Establishment (PACE) using |npa| -(``FEATURE_EXECUTE_PACE``). Thus @PACKAGE_NAME@ can be used with the German -identity card ("neuer Personalausweis", nPA) similar to a "Standardleser" -(CAT-S) or "Komfortleser" (CAT-K). +If the machine running :command:`@PACKAGE@` is in USB device mode, a local +reader is forwareded via USB to another machine. If in USB host mode, the USB +CCID reader will locally be present. + +Applications on Windows and Unix-like systems can access the @PACKAGE_NAME@ +through PC/SC as if it was a real smart card reader. No installation of a smart +card driver is required since USB CCID drivers are usually shipped with the +modern OS. [#f1]_ + +Here is a subset of USB CCID commands supported by the @PACKAGE_NAME@ with +their PC/SC counterpart: + +================================== ============================================================ +USB CCID PC/SC +================================== ============================================================ +``PC_to_RDR_XfrBlock`` ``SCardTransmit`` +``PC_to_RDR_Secure`` ``FEATURE_VERIFY_PIN_DIRECT``, ``FEATURE_MODIFY_PIN_DIRECT`` +``PC_to_RDR_Secure`` (proprietary) ``FEATURE_EXECUTE_PACE`` +================================== ============================================================ The @PACKAGE_NAME@ is implemented using GadgetFS_. Some fragments of the source code are based on the GadgetFS example and on the source code of the OpenSC_ tools. +.. [#f1] Note that the heavily outdated `Windows USB CCID driver `_ does not support secure PIN entry or PIN modification. @PACKAGE_NAME@ comes with a patch for libccid_ to support |PACE|, because it is not yet standardised in USB CCID. However, the traditional commands can be used without restriction. + + .. include:: autotools.rst Running the @PACKAGE_NAME@ has the following dependencies: - Linux Kernel with GadgetFS_ - OpenSC_ -- |npa| (only if support for PACE is enabled) +- |npa| (only if support for |PACE| is enabled) Whereas using the @PACKAGE_NAME@ on the host system as smart card reader only needs a usable PC/SC middleware with USB CCID driver. This is the case for most @@ -60,14 +71,14 @@ Hints on GadgetFS ----------------- To create a USB Gadget in both USB host and USB client mode, you need to load -the kernel module :program:`gadgetfs`. A guide focused on Debian based systems to run -and compile :program:`gadgetfs`, you can find `here +the kernel module :program:`gadgetfs`. A guide focused on Debian based systems +to run and compile GadgetFS_, you can find `here `_. On OpenMoko it is likely that you need to `patch your kernel `_. 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 +patch is needed `_. If you are using a more recent version of :program:`dummy_hcd` and get an error loading the module, you maybe want to check out `this patch @@ -78,11 +89,10 @@ loading the module, you maybe want to check out `this patch Hints on OpenSC --------------- -Without the |npa| the @PACKAGE_NAME@ links against libopensc, which is -discouraged and hindered since OpenSC version >= 0.12. (We really need to get -rid of this dependency or integrate better into the OpenSC-framework.) You need -the OpenSC components to be installed (especially :file:`libopensc.so`). Here -is an example of how to get the standard installation of OpenSC_:: +Without the |npa| the @PACKAGE_NAME@ links against OpenSC, which is discouraged +and hindered since OpenSC version >= 0.12. You need the OpenSC components to be +installed (especially :file:`libopensc.so`). Here is an example of how to get +the standard installation of OpenSC_ without |PACE|:: PREFIX=/tmp/install OPENSC=opensc @@ -103,19 +113,14 @@ configure the @PACKAGE_NAME@ to use it:: Usage ===== -The @PACKAGE_NAME@ has various command line options to customize the appearance on -the USB host. In order to run the @PACKAGE_NAME@ GadgetFS_ must be loaded and -mounted. The @PACKAGE_NAME@ is compatible with the unix driver libccid_ and the -windows smart card driver. To initialize PACE using the PC/SC API you need to -patch libccid and pcsc-lite (see directory patches). +The @PACKAGE_NAME@ has various command line options to customize the appearance +on the USB host. In order to run the @PACKAGE_NAME@ GadgetFS_ must be loaded +and mounted. The @PACKAGE_NAME@ is compatible with the unix driver libccid_ +and the `Windows USB CCID driver +`_. To initialize +|PACE| using the PC/SC API you need to patch libccid_ (see :file:`patches`). -.. program-output:: ccid-emulator --help - -cats-test can be used to test the PACE capabilities of a smart card reader with -PACE support (such as the @PACKAGE_NAME@ or any other "Standardleser" CAT-S or -"Komfortleser" CAT-C) via PC/SC. - -.. program-output:: cats-test +.. program-output:: @PACKAGE@ --help .. include:: questions.rst diff --git a/doc/index.rst b/doc/index.rst index 410cc81..cebd1a4 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -8,29 +8,31 @@ Welcome to the |vsmartcard|. |vsmartcard| is an umbrella project for various pro Currently the following projects are part of |vsmartcard|: .. toctree:: + :titlesonly: virtualsmartcard/README pcsc-relay/README - npa/README ccid/README + npa/README .. toctree:: :hidden: - virtualsmartcard/autotools - pcsc-relay/autotools - npa/autotools ccid/autotools - virtualsmartcard/questions - pcsc-relay/questions - npa/questions ccid/questions + npa/autotools + npa/questions + pcsc-relay/autotools + pcsc-relay/questions + virtualsmartcard/autotools + virtualsmartcard/questions Looking for a feature the included programs do not offer? Want to extend the functionality of some library? Apart from requesting a new feature, you can have a look at these programming guides and try yourself: .. toctree:: + :titlesonly: virtualsmartcard/api npa/api diff --git a/npa/doc/README.rst b/npa/doc/README.rst index c567fea..130f525 100644 --- a/npa/doc/README.rst +++ b/npa/doc/README.rst @@ -1,8 +1,13 @@ .. highlight:: sh +.. _OpenSC: http://www.opensc-project.org .. _OpenSC with PACE: http://github.com/frankmorgner/OpenSC +.. _OpenSSL: http://www.openssl.org .. _OpenPACE: http://openpace.sourceforge.net +.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` +.. |npa-tool| replace:: :command:`npa-tool` + .. _npa: @@ -15,21 +20,18 @@ nPA Smart Card Library :License: GPL version 3 :Tested Platforms: - - Linux (Debian, Ubuntu, OpenMoko) - Windows + - Linux (Debian, Ubuntu, OpenMoko) :Potential Platforms: Unix-like operating systems (Mac OS, Solaris, BSD, ...) -Welcome to the nPA Smart Card Library. The purpose of the nPA Smart Card Library is to offer an easy to use API for the new -German identity card (neuer Personalausweis, nPA). The library also implements -secure messaging, which could also be used for other cards. +The nPA Smart Card Library offers an easy to use API for the new German identity card +(neuer Personalausweis, nPA). The library also implements secure messaging, +which could also be used for other cards. The included |npa-tool| can +be used for PIN management or to send APDUs inside a secure channel. -The nPA Smart Card Library is implemented using OpenPACE_. -Some fragments of the source code are based on the source code of the OpenSC tools. - -The included npa-tool has support for Password Authenticated Connection -Establishment (PACE). npa-tool can be used for PIN management or to encrypt -APDUs inside a secure messaging channel established with PACE. +The nPA Smart Card Library is implemented using OpenPACE_. Some fragments of the +source code are based on the source code of the OpenSC_ tools. .. _npa-install: @@ -39,15 +41,15 @@ APDUs inside a secure messaging channel established with PACE. The nPA Smart Card Library has the following dependencies: - `OpenSC with PACE`_ -- OpenSSL with OpenPACE_ +- OpenSSL_ with OpenPACE_ ------------------------------ Hints on OpenSSL with OpenPACE ------------------------------ -The nPA Smart Card Library links against OpenSSL, which must be patched with OpenPACE_. -Here is an example of how to get the standard installation of OpenSSL with +The nPA Smart Card Library links against OpenSSL_, which must be patched with +OpenPACE_. Here is an example of how to get the standard installation of OpenPACE_:: PREFIX=/tmp/install @@ -61,9 +63,10 @@ OpenPACE_:: make make install -Building the nPA Smart Card Library with OpenPACE_ is done best using :command:`pkg-config`. The file -:file:`libcrypto.pc` should be located in ``$INSTALL/lib/pkgconfig``. Here is how -to configure the nPA Smart Card Library to use it:: +Building the nPA Smart Card Library with OpenPACE_ is done best using +:command:`pkg-config`. The file :file:`libcrypto.pc` should be located in +``$INSTALL/lib/pkgconfig``. Here is how to configure the nPA Smart Card Library to use +it:: ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig @@ -100,15 +103,15 @@ configure the nPA Smart Card Library to use it:: Usage ===== -When testing PACE with either PIN, CAN, MRZ or PUK run npa-tool. Here you can -enter APDUs which are to be converted according to the secure messaging -parameter and to be sent to the card. Herefor insert the APDU in hex (upper or -lower case) with a colon to separate the bytes or without it. Example APDUs can -be found in the file apdus. +To pass a secret to |npa-tool| for |PACE|, command line parameters or +environment variables can be used. If the smart card reader supports |PACE|, +the PIN pad is used. If none of these options is applies, npa-tool will show a +password prompt. -To pass a secret to npa-tool, the command line parameters or the environment -variables PIN/CAN/MRZ/PUK/NEWPIN can be used. If none of these options is used, -npa-tool will show a password prompt. +|npa-tool| can send arbitrary APDUs to the nPA in the secure channel. APDUs +are entered interactively or through a file. APDUs are formatted in hex (upper +or lower case) with an optional colon to separate the bytes. Example APDUs can +be found in :file:`apdus`. .. program-output:: npa-tool --help diff --git a/npa/doc/README.rst.in b/npa/doc/README.rst.in index 88529ba..64e480c 100644 --- a/npa/doc/README.rst.in +++ b/npa/doc/README.rst.in @@ -1,8 +1,13 @@ .. highlight:: sh +.. _OpenSC: http://www.opensc-project.org .. _OpenSC with PACE: http://github.com/frankmorgner/OpenSC +.. _OpenSSL: http://www.openssl.org .. _OpenPACE: http://openpace.sourceforge.net +.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` +.. |npa-tool| replace:: :command:`npa-tool` + .. _npa: @@ -20,16 +25,13 @@ :Potential Platforms: Unix-like operating systems (Mac OS, Solaris, BSD, ...) -Welcome to the @PACKAGE_NAME@. The purpose of the @PACKAGE_NAME@ is to offer an easy to use API for the new -German identity card (neuer Personalausweis, nPA). The library also implements -secure messaging, which could also be used for other cards. +The @PACKAGE_NAME@ offers an easy to use API for the new German identity card +(neuer Personalausweis, nPA). The library also implements secure messaging, +which could also be used for other cards. The included |npa-tool| can +be used for PIN management or to send APDUs inside a secure channel. -The @PACKAGE_NAME@ is implemented using OpenPACE_. -Some fragments of the source code are based on the source code of the OpenSC tools. - -The included npa-tool has support for Password Authenticated Connection -Establishment (PACE). npa-tool can be used for PIN management or to encrypt -APDUs inside a secure messaging channel established with PACE. +The @PACKAGE_NAME@ is implemented using OpenPACE_. Some fragments of the +source code are based on the source code of the OpenSC_ tools. .. _npa-install: @@ -39,15 +41,15 @@ APDUs inside a secure messaging channel established with PACE. The @PACKAGE_NAME@ has the following dependencies: - `OpenSC with PACE`_ -- OpenSSL with OpenPACE_ +- OpenSSL_ with OpenPACE_ ------------------------------ Hints on OpenSSL with OpenPACE ------------------------------ -The @PACKAGE_NAME@ links against OpenSSL, which must be patched with OpenPACE_. -Here is an example of how to get the standard installation of OpenSSL with +The @PACKAGE_NAME@ links against OpenSSL_, which must be patched with +OpenPACE_. Here is an example of how to get the standard installation of OpenPACE_:: PREFIX=/tmp/install @@ -61,9 +63,10 @@ OpenPACE_:: make make install -Building the @PACKAGE_NAME@ with OpenPACE_ is done best using :command:`pkg-config`. The file -:file:`libcrypto.pc` should be located in ``$INSTALL/lib/pkgconfig``. Here is how -to configure the @PACKAGE_NAME@ to use it:: +Building the @PACKAGE_NAME@ with OpenPACE_ is done best using +:command:`pkg-config`. The file :file:`libcrypto.pc` should be located in +``$INSTALL/lib/pkgconfig``. Here is how to configure the @PACKAGE_NAME@ to use +it:: ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig @@ -100,15 +103,15 @@ configure the @PACKAGE_NAME@ to use it:: Usage ===== -When testing PACE with either PIN, CAN, MRZ or PUK run npa-tool. Here you can -enter APDUs which are to be converted according to the secure messaging -parameter and to be sent to the card. Herefor insert the APDU in hex (upper or -lower case) with a colon to separate the bytes or without it. Example APDUs can -be found in the file apdus. +To pass a secret to |npa-tool| for |PACE|, command line parameters or +environment variables can be used. If the smart card reader supports |PACE|, +the PIN pad is used. If none of these options is applies, npa-tool will show a +password prompt. -To pass a secret to npa-tool, the command line parameters or the environment -variables PIN/CAN/MRZ/PUK/NEWPIN can be used. If none of these options is used, -npa-tool will show a password prompt. +|npa-tool| can send arbitrary APDUs to the nPA in the secure channel. APDUs +are entered interactively or through a file. APDUs are formatted in hex (upper +or lower case) with an optional colon to separate the bytes. Example APDUs can +be found in :file:`apdus`. .. program-output:: npa-tool --help diff --git a/pcsc-relay/doc/Makefile.am b/pcsc-relay/doc/Makefile.am index bc13502..c4320d7 100644 --- a/pcsc-relay/doc/Makefile.am +++ b/pcsc-relay/doc/Makefile.am @@ -1,4 +1,5 @@ do_subst = sed \ + -e 's,[@]PACKAGE[@],$(PACKAGE),g' \ -e 's,[@]PACKAGE_NAME[@],$(PACKAGE_NAME),g' \ -e 's,[@]PACKAGE_TARNAME[@],$(PACKAGE_TARNAME),g' \ -e 's,[@]PACKAGE_BUGREPORT[@],$(PACKAGE_BUGREPORT),g' \ diff --git a/pcsc-relay/doc/README.rst b/pcsc-relay/doc/README.rst index c814504..144b4e2 100644 --- a/pcsc-relay/doc/README.rst +++ b/pcsc-relay/doc/README.rst @@ -1,52 +1,58 @@ .. highlight:: sh .. _libnfc: http://www.libnfc.org/ +.. _OpenPICC: http://www.openpcd.org/OpenPICC .. _PCSC-lite: http://pcsclite.alioth.debian.org/ +.. _pcsc-relay: ******************************************************************************** PC/SC Relay ******************************************************************************** :Authors: - - Dominik Oepen - Frank Morgner + - Dominik Oepen :License: GPL version 3 :Tested Platforms: - Linux (Debian, Ubuntu, OpenMoko) -:Potential Platforms: - Windows - - Unix-like operating systems (Mac OS, Solaris, BSD, ...) + - Linux (Debian, Ubuntu, OpenMoko) +:Potential Platforms: + Unix-like operating systems (Mac OS, Solaris, BSD, ...) -Welcome to pcsc-relay. The purpose of pcsc-relay is to forward APDUs from the -OpenPICC or from a libnfc device to a smart card via the PCSC middleware. You -can use this program in combination with the virtual smart card to emulate a -ISO/IEC 14443 smart card. +Welcome to PC/SC Relay. The purpose of PC/SC Relay is to relay a smart +card using an contact-less interface. Currently the following contact-less +backends: + +- libnfc_ +- OpenPICC_ + +Command APDUs are received with the contact-less interface and forwarded to an +existing smart card via PC/SC. The Response APDUs are then sent back via RFID. +You can use PC/SC Relay in combination with the :ref:`vicc` to completely +emulate an ISO/IEC 14443 smart card. .. note:: This software can actually be used in a relay attack allowing full access - to the card... `We discussed the impact especially on the German identity + to the card. `We discussed the impact especially on the German identity card `_, - but it generally concerns *all NFC smart cards*. + but it generally concerns *all* contact-less smart cards. .. include:: autotools.rst -pcsc-relay has the following dependencies: +PC/SC Relay has the following dependencies: - PC/SC middleware - libnfc_ -.. program-output:: pcsc-relay --help - - --------------- Hints on libnfc --------------- -pcsc-relay links against libnfc_. Here is an example of how to get the standard +PC/SC Relay links against libnfc_. Here is an example of how to get the standard installation of the latter:: PREFIX=/tmp/install @@ -58,9 +64,9 @@ installation of the latter:: make make install -Building pcsc-relay with libnfc_ is done best using :command:`pkg-config`. The file +Building PC/SC Relay with libnfc_ is done best using :command:`pkg-config`. The file :file:`libnfc.pc` should be located in ``$INSTALL/lib/pkgconfig``. Here is how to -configure pcsc-relay to use it:: +configure PC/SC Relay to use it:: ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig @@ -69,12 +75,21 @@ configure pcsc-relay to use it:: Hints on PC/SC middleware ------------------------- -PC/SC is included by default in most modern operating systems. On Unix-like -systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To compile -pcsc-relay you will need to install the PCSC-Lite headers from your -distribution. Windows also ships with a PC/SC middleware in form of the -Winscard module. Microsoft's developement environment Visual Studio includes -all necessary data for building pcsc-relay. +A PC/SC middleware is included by default in most modern operating systems. On +Unix-like systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To +compile PC/SC Relay you will need to install the PCSC-Lite_ headers from +your distribution. + +Windows also ships with a PC/SC middleware in form of the Winscard module. +Microsoft's developement environment Visual Studio includes all necessary data +for building PC/SC Relay. + + +===== +Usage +===== + +.. program-output:: pcsc-relay --help .. include:: questions.rst diff --git a/pcsc-relay/doc/README.rst.in b/pcsc-relay/doc/README.rst.in index d1696a9..5919596 100644 --- a/pcsc-relay/doc/README.rst.in +++ b/pcsc-relay/doc/README.rst.in @@ -1,52 +1,58 @@ .. highlight:: sh .. _libnfc: http://www.libnfc.org/ +.. _OpenPICC: http://www.openpcd.org/OpenPICC .. _PCSC-lite: http://pcsclite.alioth.debian.org/ +.. _pcsc-relay: ******************************************************************************** @PACKAGE_NAME@ ******************************************************************************** :Authors: - - Dominik Oepen - Frank Morgner + - Dominik Oepen :License: GPL version 3 :Tested Platforms: - Linux (Debian, Ubuntu, OpenMoko) -:Potential Platforms: - Windows - - Unix-like operating systems (Mac OS, Solaris, BSD, ...) + - Linux (Debian, Ubuntu, OpenMoko) +:Potential Platforms: + Unix-like operating systems (Mac OS, Solaris, BSD, ...) -Welcome to pcsc-relay. The purpose of pcsc-relay is to forward APDUs from the -OpenPICC or from a libnfc device to a smart card via the PCSC middleware. You -can use this program in combination with the virtual smart card to emulate a -ISO/IEC 14443 smart card. +Welcome to @PACKAGE_NAME@. The purpose of @PACKAGE_NAME@ is to relay a smart +card using an contact-less interface. Currently the following contact-less +backends: + +- libnfc_ +- OpenPICC_ + +Command APDUs are received with the contact-less interface and forwarded to an +existing smart card via PC/SC. The Response APDUs are then sent back via RFID. +You can use @PACKAGE_NAME@ in combination with the :ref:`vicc` to completely +emulate an ISO/IEC 14443 smart card. .. note:: This software can actually be used in a relay attack allowing full access - to the card... `We discussed the impact especially on the German identity + to the card. `We discussed the impact especially on the German identity card `_, - but it generally concerns *all NFC smart cards*. + but it generally concerns *all* contact-less smart cards. .. include:: autotools.rst -pcsc-relay has the following dependencies: +@PACKAGE_NAME@ has the following dependencies: - PC/SC middleware - libnfc_ -.. program-output:: pcsc-relay --help - - --------------- Hints on libnfc --------------- -pcsc-relay links against libnfc_. Here is an example of how to get the standard +@PACKAGE_NAME@ links against libnfc_. Here is an example of how to get the standard installation of the latter:: PREFIX=/tmp/install @@ -58,9 +64,9 @@ installation of the latter:: make make install -Building pcsc-relay with libnfc_ is done best using :command:`pkg-config`. The file +Building @PACKAGE_NAME@ with libnfc_ is done best using :command:`pkg-config`. The file :file:`libnfc.pc` should be located in ``$INSTALL/lib/pkgconfig``. Here is how to -configure pcsc-relay to use it:: +configure @PACKAGE_NAME@ to use it:: ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig @@ -69,12 +75,21 @@ configure pcsc-relay to use it:: Hints on PC/SC middleware ------------------------- -PC/SC is included by default in most modern operating systems. On Unix-like -systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To compile -pcsc-relay you will need to install the PCSC-Lite headers from your -distribution. Windows also ships with a PC/SC middleware in form of the -Winscard module. Microsoft's developement environment Visual Studio includes -all necessary data for building pcsc-relay. +A PC/SC middleware is included by default in most modern operating systems. On +Unix-like systems (Linux, OS X, Sun OS) it is realized by PCSC-Lite_. To +compile @PACKAGE_NAME@ you will need to install the PCSC-Lite_ headers from +your distribution. + +Windows also ships with a PC/SC middleware in form of the Winscard module. +Microsoft's developement environment Visual Studio includes all necessary data +for building @PACKAGE_NAME@. + + +===== +Usage +===== + +.. program-output:: @PACKAGE@ --help .. include:: questions.rst diff --git a/virtualsmartcard/doc/README.rst b/virtualsmartcard/doc/README.rst index 7d7cf3a..7a8a65c 100644 --- a/virtualsmartcard/doc/README.rst +++ b/virtualsmartcard/doc/README.rst @@ -11,7 +11,10 @@ .. |vpicc| replace:: :abbr:`vpicc (virtual smart card)` .. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)` +.. |EAC| replace:: :abbr:`EAC (Extended Access Control)` +.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` +.. _vicc: ******************************************************************************** Virtual Smart Card @@ -28,17 +31,25 @@ Virtual Smart Card :Potential Platforms: Unix-like operating systems (Mac OS, Solaris, BSD, ...) -Welcome to the Virtual Smart Card. The purpose of the Virtual Smart Card is to emulate a -smart card and make it accessible through PCSC. Currently the virtual smart -card supports almost all commands of ISO-7816 including secure messaging. -Besides a plain ISO-7816 smart card it is also possible to emulate a German -ePass (only basic access control) and a rudimentary Cryptoflex smart card. The -|vpicc| can be accessed through the |vpcd| which is a driver for -:command:`pcscd` of PCSC-Lite_. +Virtual Smart Card emulates a smart card and makes it accessible through PC/SC. +Currently the Virtual Smart Card supports the following types of smart cards: -By default the vicc communicates with the vpcd through a socket on localhost -port 35963. The file :file:`utils.py` was taken from Henryk Plötz's -cyberflex-shell_. +- Generic ISO-7816 smart card including secure messaging +- German electronic identity card (nPA) with |EAC| including |PACE| +- German electronic passport (ePass) with basic access control +- Cryptoflex smart card (incomplete) + +The |vpcd| is a smart card driver for PCSC-Lite_. It allows +smart card applications to access the |vpicc| through the PC/SC API. By +default |vpicc| communicates with |vpcd| through a socket on localhost port +35963. But the |vpicc| does not need to run on the same machine as the |vpcd|, +they can connect over the internet for example. + +Although the Virtual Smart Card is a software emulator, you can use +:ref:`pcsc-relay` to make it accessible to an external contact-less smart card +reader. + +The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_. .. include:: autotools.rst @@ -52,28 +63,26 @@ the following: - PBKDF2_ - PIP_ -The |vpcd| has the following dependencies: - -- PCSC-Lite_ +The |vpcd| depends on PCSC-Lite_. ================================================================================ Running the Virtual Smart Card ================================================================================ -First you need to make sure that pcscd loads the |vpcd|. You might need to run -:command:`update-reader.conf` to update pcscd's configuration file. Then -:command:`pcscd -f -d` should say something like "Attempting startup of +First you need to make sure that :command:`pcscd` loads the |vpcd|. You might +need to run :command:`update-reader.conf` to update its configuration file. +Then :command:`pcscd -f -d` should say something like "Attempting startup of Virtual PCD" Now you can run :command:`vicc` which connects to the |vpcd|. The command :command:`vicc --help` gives an overview about the command line options. -You should now be able to access the |vpicc| through the system's -PC/SC API via |vpcd|/pcscd. You can use the opensc-explorer or pcsc_scan to test -that. - .. program-output:: vicc --help +You should now be able to access the |vpicc| through the PC/SC API via +|vpcd|/pcscd. You can use the :command:`opensc-explorer` or +:command:`pcsc_scan` for testing. + .. include:: questions.rst diff --git a/virtualsmartcard/doc/README.rst.in b/virtualsmartcard/doc/README.rst.in index 3206f08..e7c9b11 100644 --- a/virtualsmartcard/doc/README.rst.in +++ b/virtualsmartcard/doc/README.rst.in @@ -11,7 +11,10 @@ .. |vpicc| replace:: :abbr:`vpicc (virtual smart card)` .. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)` +.. |EAC| replace:: :abbr:`EAC (Extended Access Control)` +.. |PACE| replace:: :abbr:`PACE (Password Authenticated Connection Establishment)` +.. _vicc: ******************************************************************************** @PACKAGE_NAME@ @@ -28,17 +31,25 @@ :Potential Platforms: Unix-like operating systems (Mac OS, Solaris, BSD, ...) -Welcome to the @PACKAGE_NAME@. The purpose of the @PACKAGE_NAME@ is to emulate a -smart card and make it accessible through PCSC. Currently the virtual smart -card supports almost all commands of ISO-7816 including secure messaging. -Besides a plain ISO-7816 smart card it is also possible to emulate a German -ePass (only basic access control) and a rudimentary Cryptoflex smart card. The -|vpicc| can be accessed through the |vpcd| which is a driver for -:command:`pcscd` of PCSC-Lite_. +@PACKAGE_NAME@ emulates a smart card and makes it accessible through PC/SC. +Currently the @PACKAGE_NAME@ supports the following types of smart cards: -By default the vicc communicates with the vpcd through a socket on localhost -port 35963. The file :file:`utils.py` was taken from Henryk Plötz's -cyberflex-shell_. +- Generic ISO-7816 smart card including secure messaging +- German electronic identity card (nPA) with |EAC| including |PACE| +- German electronic passport (ePass) with basic access control +- Cryptoflex smart card (incomplete) + +The |vpcd| is a smart card driver for PCSC-Lite_. It allows +smart card applications to access the |vpicc| through the PC/SC API. By +default |vpicc| communicates with |vpcd| through a socket on localhost port +35963. But the |vpicc| does not need to run on the same machine as the |vpcd|, +they can connect over the internet for example. + +Although the @PACKAGE_NAME@ is a software emulator, you can use +:ref:`pcsc-relay` to make it accessible to an external contact-less smart card +reader. + +The file :file:`utils.py` was taken from Henryk Plötz's cyberflex-shell_. .. include:: autotools.rst @@ -52,28 +63,26 @@ the following: - PBKDF2_ - PIP_ -The |vpcd| has the following dependencies: - -- PCSC-Lite_ +The |vpcd| depends on PCSC-Lite_. ================================================================================ Running the @PACKAGE_NAME@ ================================================================================ -First you need to make sure that pcscd loads the |vpcd|. You might need to run -:command:`update-reader.conf` to update pcscd's configuration file. Then -:command:`pcscd -f -d` should say something like "Attempting startup of +First you need to make sure that :command:`pcscd` loads the |vpcd|. You might +need to run :command:`update-reader.conf` to update its configuration file. +Then :command:`pcscd -f -d` should say something like "Attempting startup of Virtual PCD" Now you can run :command:`vicc` which connects to the |vpcd|. The command :command:`vicc --help` gives an overview about the command line options. -You should now be able to access the |vpicc| through the system's -PC/SC API via |vpcd|/pcscd. You can use the opensc-explorer or pcsc_scan to test -that. - .. program-output:: vicc --help +You should now be able to access the |vpicc| through the PC/SC API via +|vpcd|/pcscd. You can use the :command:`opensc-explorer` or +:command:`pcsc_scan` for testing. + .. include:: questions.rst