added autogenerated files for easier development checkout

git-svn-id: https://vsmartcard.svn.sourceforge.net/svnroot/vsmartcard@606 96b47cad-a561-4643-ad3b-153ac7d7599c

ccid/doc/README.rst

@@ -0,0 +1,99 @@
+.. highlight:: sh
+
+.. _OpenSC: http://www.opensc-project.org/opensc
+.. _GadgetFS: http://www.linux-usb.org/gadget/
+.. _libccid: http://pcsclite.alioth.debian.org/ccid.html
+
+
+********************************************************************************
+CCID Emulator
+********************************************************************************
+
+:Author:
+    Frank Morgner <morgner@informatik.hu-berlin.de>
+:License:
+    GPL version 3
+: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/).
+
+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:
+
+- Linux Kernel with GadgetFS_
+- OpenSC_
+- :ref:`npa` (only if support for PACE is enabled)
+
+
+-----------------
+Hints on GadgetFS
+-----------------
+
+To create an 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
+<http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module>`_.
+
+On OpenMoko it is likely that you need to `patch your kernel
+<http://docs.openmoko.org/trac/ticket/2206>`_. If you also want to switch
+multiple times between :program:`gadgetfs` and :program:`g_ether`, `another patch is needed
+<http://docs.openmoko.org/trac/ticket/2240)>`_.
+
+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
+<http://comments.gmane.org/gmane.linux.usb.general/47440>`_.
+
+
+---------------
+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_::
+
+    PREFIX=/tmp/install
+    OPENSC=opensc
+    svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC
+    cd $OPENSC
+    autoreconf -i
+    ./configure --prefix=$PREFIX
+    make
+    make install
+
+Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to
+configure the CCID Emulator to use it::
+
+    ./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc"
+
+
+=====
+Usage
+=====
+
+The CCID Emulator has various command line options to customize the appearance on
+the USB host. In order to run the CCID Emulator GadgetFS_ must be loaded and
+mounted.  The 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).
+
+cats-test can be used to test the PACE capabilities of a smart card reader with
+PACE support (such as the CCID Emulator or any other "Standardleser" CAT-S or
+"Komfortleser" CAT-C) via PC/SC.
+
+
+.. include:: questions.rst

ccid/doc/autotools.rst

@@ -0,0 +1,20 @@
+.. highlight:: sh
+
+=============
+Installation
+=============
+
+The 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
+around and can not find it, you are probably working bleeding edge in the
+repository.  Run the following command in :file:`ccid-emulator` to
+get the missing standard auxiliary files::
+    
+    autoreconf -i
+
+To configure (:command:`configure --help` lists possible options), build and
+install the CCID Emulator now do the following::
+    
+    ./configure
+    make
+    make install

ccid/doc/questions.rst

@@ -0,0 +1,6 @@
+========
+Question
+========
+
+Do you have questions, suggestions or contributions? Feedback of any kind is
+more than welcome! Please use our `project trackers <http://sourceforge.net/projects/vsmartcard/support>`_.

npa/doc/README.rst

@@ -0,0 +1,139 @@
+.. highlight:: sh
+
+.. _OpenSC: http://www.opensc-project.org/opensc
+.. _OpenPACE: http://sourceforge.net/projects/openpace/
+
+
+.. _npa:
+
+********************************************************************************
+nPA smart card library
+********************************************************************************
+
+:Author:
+    Frank Morgner <morgner@informatik.hu-berlin.de>
+:License:
+    GPL version 3
+:Tested Platforms:
+    Linux (Debian, Ubuntu, OpenMoko)
+:Potential Platforms:
+    - Windows
+    - Unix-like operating systems (Mac OS, Solaris, BSD, ...)
+
+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 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.
+
+
+.. _npa-install:
+
+.. include:: autotools.rst
+
+The nPA smart card library has the following dependencies:
+
+- OpenSC_
+- OpenSSL with OpenPACE_
+
+
+------------------------------
+Hints on OpenSSL with OpenPACE
+------------------------------
+
+libnpa links against libcrypto, which must be patched with OpenPACE_. Here is
+an example of how to get the standard installation of OpenSSL with OpenPACE_::
+ 
+    PREFIX=/tmp/install
+    OPENPACE=openpace
+    svn co https://openpace.svn.sourceforge.net/svnroot/openpace $OPENPACE
+    cd $OPENPACE
+    make patch_with_openpace
+    cd openssl-*/
+    ./config experimental-pace --prefix=$PREFIX
+    make depend
+    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::
+
+    ./configure PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
+
+
+---------------
+Hints on OpenSC
+---------------
+
+libnpa 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
+    svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC
+    cd $OPENSC
+    autoreconf -i
+    # adding PKG_CONFIG_PATH here lets OpenSC use OpenSSL with OpenPACE
+    ./configure --prefix=$PREFIX PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
+    make
+    make install
+
+Now :file:`libopensc.so` should be located in ``$PREFIX/lib``. Here is how to
+configure the nPA smart card library to use it::
+
+    ./configure OPENSC_LIBS="-L$PREFIX/lib -lopensc"
+
+
+.. _npa-usage:
+
+=====
+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, 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.
+
+----------------------
+Linking against libnpa
+----------------------
+
+Following the section `Installation`_ above, you have installed OpenSC_,
+OpenPACE_ and the nPA smart card library to :file:`/tmp/install`. To compile a program using libnpa you
+need to get the header files from OpenSC_ as well.
+Here is how
+to compile an external program with these libraries::
+
+    PREFIX=/tmp/install
+    OPENSC=opensc
+    svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC
+    cc example.c -I$OPENSC/src \
+        $(env PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig \
+            pkg-config --cflags --libs npa)
+
+Alternatively you can specify libraries and flags by hand::
+
+    PREFIX=/tmp/install
+    OPENSC=opensc
+    svn co http://www.opensc-project.org/svn/opensc/trunk $OPENSC
+    cc example.c -I$OPENSC/src \
+        -I$PREFIX/include \
+        -L$PREFIX/lib -lcrypto -lnpa -lopensc"
+
+
+.. include:: questions.rst

npa/doc/autotools.rst

@@ -0,0 +1,20 @@
+.. highlight:: sh
+
+=============
+Installation
+=============
+
+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
+around and can not find it, you are probably working bleeding edge in the
+repository.  Run the following command in :file:`npa` to
+get the missing standard auxiliary files::
+    
+    autoreconf -i
+
+To configure (:command:`configure --help` lists possible options), build and
+install the nPA smart card library now do the following::
+    
+    ./configure
+    make
+    make install

npa/doc/questions.rst

@@ -0,0 +1,6 @@
+========
+Question
+========
+
+Do you have questions, suggestions or contributions? Feedback of any kind is
+more than welcome! Please use our `project trackers <http://sourceforge.net/projects/vsmartcard/support>`_.

pcsc-relay/doc/README.rst

@@ -0,0 +1,71 @@
+.. highlight:: sh
+
+.. _libnfc: http://www.libnfc.org/
+.. _PCSC-lite: http://pcsclite.alioth.debian.org/
+
+
+********************************************************************************
+pcsc-relay
+********************************************************************************
+
+:Authors:
+    - Dominik Oepen <oepen@informatik.hu-berlin.de>
+    - Frank Morgner <morgner@informatik.hu-berlin.de>
+:License:
+    GPL version 3
+:Tested Platforms:
+    Linux (Debian, Ubuntu, OpenMoko)
+:Potential Platforms:
+    - Windows
+    - Unix-like operating systems (Mac OS, Solaris, BSD, ...)
+
+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. 
+
+
+.. include:: autotools.rst
+
+pcsc-relay has the following dependencies:
+
+- PC/SC middleware
+- libnfc_
+
+
+---------------
+Hints on libnfc
+---------------
+
+pcsc-relay links against libnfc_. Here is an example of how to get the standard
+installation of the latter::
+ 
+    PREFIX=/tmp/install
+    LIBNFC=libnfc
+    svn co http://libnfc.googlecode.com/svn/trunk $LIBNFC
+    cd $LIBNFC
+    autoreconf -i
+    ./configure --prefix=$PREFIX
+    make
+    make install
+
+Building pcsc-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 PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
+
+
+-------------------------
+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.
+
+
+.. include:: questions.rst

pcsc-relay/doc/autotools.rst

@@ -0,0 +1,20 @@
+.. highlight:: sh
+
+=============
+Installation
+=============
+
+The pcsc-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
+around and can not find it, you are probably working bleeding edge in the
+repository.  Run the following command in :file:`pcsc-relay` to
+get the missing standard auxiliary files::
+    
+    autoreconf -i
+
+To configure (:command:`configure --help` lists possible options), build and
+install the pcsc-relay now do the following::
+    
+    ./configure
+    make
+    make install

pcsc-relay/doc/questions.rst

@@ -0,0 +1,6 @@
+========
+Question
+========
+
+Do you have questions, suggestions or contributions? Feedback of any kind is
+more than welcome! Please use our `project trackers <http://sourceforge.net/projects/vsmartcard/support>`_.

virtualsmartcard/doc/README.rst

@@ -0,0 +1,77 @@
+.. highlight:: sh
+
+.. _PBKDF2: https://www.dlitz.net/software/python-pbkdf2/
+.. _PCSC-lite: http://pcsclite.alioth.debian.org/
+.. _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
+.. _pyscard: http://pyscard.sourceforge.net/
+
+.. |vpicc| replace:: :abbr:`vpicc (virtual smart card)`
+.. |vpcd| replace:: :abbr:`vpcd (virtual smart card reader)`
+
+
+********************************************************************************
+Virtual Smart Card
+********************************************************************************
+
+:Authors:
+    - Frank Morgner <morgner@informatik.hu-berlin.de>
+    - Dominik Oepen <oepen@informatik.hu-berlin.de>
+:License:
+    GPL version 3
+:Tested Platforms:
+    - Linux (Debian, Ubuntu, OpenMoko)
+    - Windows (only |vpicc|, not |vpcd|)
+: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_.
+
+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_.
+
+
+.. include:: autotools.rst
+
+Depending on your usage of the |vpicc| you might or might not need
+the following:
+
+- Python_
+- pyscard_
+- PyCrypto_
+- PBKDF2_
+- PIP_
+
+The |vpcd| has the following dependencies:
+
+- 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
+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.
+
+
+.. include:: questions.rst

virtualsmartcard/doc/autotools.rst

@@ -0,0 +1,20 @@
+.. highlight:: sh
+
+=============
+Installation
+=============
+
+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
+around and can not find it, you are probably working bleeding edge in the
+repository.  Run the following command in :file:`virtualsmartcard` to
+get the missing standard auxiliary files::
+    
+    autoreconf -i
+
+To configure (:command:`configure --help` lists possible options), build and
+install the Virtual Smart Card now do the following::
+    
+    ./configure
+    make
+    make install

virtualsmartcard/doc/questions.rst

@@ -0,0 +1,6 @@
+========
+Question
+========
+
+Do you have questions, suggestions or contributions? Feedback of any kind is
+more than welcome! Please use our `project trackers <http://sourceforge.net/projects/vsmartcard/support>`_.