From c1a94800cd13982924d9ae4446220390cee69102 Mon Sep 17 00:00:00 2001 From: frankmorgner Date: Thu, 3 Nov 2011 22:17:53 +0000 Subject: [PATCH] - update on ccid documentation - rebuilding documentation when any *.in file changes git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@613 96b47cad-a561-4643-ad3b-153ac7d7599c --- ccid/doc/Makefile.am | 2 +- ccid/doc/README.rst | 52 +++++++++++++++++++++----------- ccid/doc/README.rst.in | 52 +++++++++++++++++++++----------- npa/doc/Makefile.am | 2 +- pcsc-relay/doc/Makefile.am | 2 +- virtualsmartcard/doc/Makefile.am | 2 +- 6 files changed, 74 insertions(+), 38 deletions(-) diff --git a/ccid/doc/Makefile.am b/ccid/doc/Makefile.am index 82a30cd..3d4fdb3 100644 --- a/ccid/doc/Makefile.am +++ b/ccid/doc/Makefile.am @@ -15,7 +15,7 @@ do_subst = sed \ EXTRA_DIST = README.rst.in README.rst autotools.rst autotools.rst.in questions.rst questions.rst.in -doc: +doc: *.in $(do_subst) < autotools.rst.in > autotools.rst $(do_subst) < questions.rst.in > questions.rst $(do_subst) < README.rst.in > README.rst diff --git a/ccid/doc/README.rst b/ccid/doc/README.rst index cf440a2..0b32545 100644 --- a/ccid/doc/README.rst +++ b/ccid/doc/README.rst @@ -4,6 +4,8 @@ .. _GadgetFS: http://www.linux-usb.org/gadget/ .. _libccid: http://pcsclite.alioth.debian.org/ccid.html +.. |npa| replace:: :ref:`npa` + ******************************************************************************** CCID Emulator @@ -16,32 +18,48 @@ CCID Emulator :Tested Platforms: Linux (Debian, Ubuntu, OpenMoko) -Welcome to the CCID Emulator. The purpose of the CCID Emulator is to forward a PCSC -smartcard reader as a standard USB CCID reader. If the host system is in USB -device mode, the CCID Emulator forwards the local reader via USB to another -device. If in USB host mode, the CCID Emulator virtually plugges in a USB CCID -reader to the host system. the CCID Emulator has support for Password -Authenticated Connection Establishment (PACE) using OpenPACE -(http://sourceforge.net/projects/openpace/). +Welcome to the CCID Emulator. The purpose of the CCID Emulator is to forward +a PC/SC smartcard reader as a standard USB CCID reader. If the machine running +the 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 CCID Emulator. Applications on Windows and +Unix-like systems can access the CCID Emulator through PC/SC as if it were a +real smart card reader. -The 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. +The 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. +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 CCID Emulator has support the for Password +Authenticated Connection Establishment (PACE) using |npa| +(``FEATURE_EXECUTE_PACE``). Thus CCID Emulator can be used with the German +identity card ("neuer Personalausweis", nPA) similar to a "Standardleser" +(CAT-S) or "Komfortleser" (CAT-K). + +The 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. .. include:: autotools.rst -The CCID Emulator following dependencies: +Running the CCID Emulator has the following dependencies: - Linux Kernel with GadgetFS_ - OpenSC_ -- :ref:`npa` (only if support for PACE is enabled) +- |npa| (only if support for PACE is enabled) + +Whereas using the CCID Emulator on the host system as smart card reader only +needs a usable PC/SC middleware with USB CCID driver. This is the case for most +modern Windows and Unix-like systems by default. ----------------- Hints on GadgetFS ----------------- -To create an USB Gadget in both USB host and USB client mode, you need to load +To create a USB Gadget in both USB host and USB client mode, you need to load the kernel module :program:`gadgetfs`. A guide focused on Debian based systems to run and compile :program:`gadgetfs`, you can find `here `_. @@ -60,11 +78,11 @@ loading the module, you maybe want to check out `this patch Hints on OpenSC --------------- -Without :ref:`npa` the 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 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_:: PREFIX=/tmp/install OPENSC=opensc diff --git a/ccid/doc/README.rst.in b/ccid/doc/README.rst.in index 028373f..02e9e2e 100644 --- a/ccid/doc/README.rst.in +++ b/ccid/doc/README.rst.in @@ -4,6 +4,8 @@ .. _GadgetFS: http://www.linux-usb.org/gadget/ .. _libccid: http://pcsclite.alioth.debian.org/ccid.html +.. |npa| replace:: :ref:`npa` + ******************************************************************************** @PACKAGE_NAME@ @@ -16,32 +18,48 @@ :Tested Platforms: Linux (Debian, Ubuntu, OpenMoko) -Welcome to the @PACKAGE_NAME@. The purpose of the @PACKAGE_NAME@ is to forward a PCSC -smartcard reader as a standard USB CCID reader. If the host system is in USB -device mode, the @PACKAGE_NAME@ forwards the local reader via USB to another -device. If in USB host mode, the @PACKAGE_NAME@ virtually plugges in a USB CCID -reader to the host system. the @PACKAGE_NAME@ has support for Password -Authenticated Connection Establishment (PACE) using OpenPACE -(http://sourceforge.net/projects/openpace/). +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@ 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. +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). + +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. .. include:: autotools.rst -The @PACKAGE_NAME@ following dependencies: +Running the @PACKAGE_NAME@ has the following dependencies: - Linux Kernel with GadgetFS_ - OpenSC_ -- :ref:`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 +modern Windows and Unix-like systems by default. ----------------- Hints on GadgetFS ----------------- -To create an USB Gadget in both USB host and USB client mode, you need to load +To create a USB Gadget in both USB host and USB client mode, you need to load the kernel module :program:`gadgetfs`. A guide focused on Debian based systems to run and compile :program:`gadgetfs`, you can find `here `_. @@ -60,11 +78,11 @@ loading the module, you maybe want to check out `this patch Hints on OpenSC --------------- -Without :ref:`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 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_:: PREFIX=/tmp/install OPENSC=opensc diff --git a/npa/doc/Makefile.am b/npa/doc/Makefile.am index d31d895..0547d33 100644 --- a/npa/doc/Makefile.am +++ b/npa/doc/Makefile.am @@ -15,7 +15,7 @@ do_subst = sed \ EXTRA_DIST = README.rst.in README.rst Doxyfile.in example.c autotools.rst autotools.rst.in questions.rst questions.rst.in -doc: $(top_srcdir)/src/npa/*.h +doc: $(top_srcdir)/src/npa/*.h *.in $(do_subst) < Doxyfile.in > Doxyfile $(DOXYGEN) Doxyfile touch api.rst diff --git a/pcsc-relay/doc/Makefile.am b/pcsc-relay/doc/Makefile.am index 9048fdb..66638bd 100644 --- a/pcsc-relay/doc/Makefile.am +++ b/pcsc-relay/doc/Makefile.am @@ -15,7 +15,7 @@ do_subst = sed \ EXTRA_DIST = README.rst.in README.rst autotools.rst.in questions.rst.in autotools.rst questions.rst -doc: +doc: *.in $(do_subst) < autotools.rst.in > autotools.rst $(do_subst) < questions.rst.in > questions.rst $(do_subst) < README.rst.in > README.rst diff --git a/virtualsmartcard/doc/Makefile.am b/virtualsmartcard/doc/Makefile.am index 9c4d1fc..5ccc93b 100644 --- a/virtualsmartcard/doc/Makefile.am +++ b/virtualsmartcard/doc/Makefile.am @@ -19,7 +19,7 @@ EXTRA_DIST = README.rst.in README.rst autotools.rst.in questions.rst.in autotool dist_noinst_SCRIPTS = generate_modules.py -doc: $(top_srcdir)/src/vpicc/virtualsmartcard/*.py $(top_srcdir)/src/vpicc/virtualsmartcard/cards/*.py generate_modules.py +doc: $(top_srcdir)/src/vpicc/virtualsmartcard/*.py $(top_srcdir)/src/vpicc/virtualsmartcard/cards/*.py generate_modules.py *.in $(do_subst) < autotools.rst.in > autotools.rst $(do_subst) < questions.rst.in > questions.rst $(do_subst) < README.rst.in > README.rst