using a dedicated folder for documentation in each subproject

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

npa/doc/Doxyfile.in

@@ -0,0 +1,12 @@
+FILE_PATTERNS          = *.h
+GENERATE_HTML          = YES
+GENERATE_LATEX         = NO
+GENERATE_TAGFILE       = @builddir@/@PACKAGE_NAME@.tag
+GENERATE_XML           = YES
+INPUT                  = @top_srcdir@/src/npa
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OUTPUT_DIRECTORY       = @builddir@
+PROJECT_NAME           = @PACKAGE_NAME@
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+STRIP_FROM_PATH        = @top_srcdir@/src
+XML_OUTPUT             = xml

npa/doc/Makefile.am

@@ -0,0 +1,25 @@
+ACLOCAL_AMFLAGS = -I m4
+
+do_subst = sed \
+	   -e 's,[@]PACKAGE_NAME[@],$(PACKAGE_NAME),g' \
+	   -e 's,[@]PACKAGE_VERSION[@],$(PACKAGE_VERSION),g' \
+	   -e 's,[@]builddir[@],$(builddir),g' \
+	   -e 's,[@]prefix[@],$(prefix),g' \
+	   -e 's,[@]exec_prefix[@],$(exec_prefix),g' \
+	   -e 's,[@]libdir[@],$(libdir),g' \
+	   -e 's,[@]includedir[@],$(includedir),g' \
+	   -e 's,[@]VERSION[@],$(VERSION),g' \
+	   -e 's,[@]OPENSC_LIBS[@],$(OPENSC_LIBS),g' \
+	   -e 's,[@]top_srcdir[@],$(top_srcdir),g'
+
+EXTRA_DIST = README.rst Doxyfile.in example.c
+
+if DOC_ENABLED
+.PHONY: doc
+doc :
+	$(do_subst) < Doxyfile.in > Doxyfile
+	$(DOXYGEN) Doxyfile
+endif
+
+clean-local:
+	rm -f Doxyfile

npa/doc/README.rst

@@ -0,0 +1,148 @@
+.. highlight:: sh
+
+.. _OpenSC: http://www.opensc-project.org/opensc
+.. _OpenPACE: http://sourceforge.net/projects/openpace/
+
+
+***
+npa
+***
+
+:Author:
+    Frank Morgner <morgner@informatik.hu-berlin.de>
+:License:
+    GPL version 3
+:Tested Platforms:
+    Linux (Debian, Ubuntu, OpenMoko)
+
+Welcome to npa. The purpose of npa 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.
+
+npa 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:
+
+============
+Installation
+============
+
+npa uses the GNU Build System to compile and install. If you are unfamiliar
+with it, please have a look at the 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 the npa directory to get the missing standard
+auxiliary files::
+    
+    autoreconf -i
+
+npa 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 npa with OpenPACE_ is done best using ``pkg-config``.  The file
+``libcrypto.pc`` should be located in ``$INSTALL/lib/pkgconfig``. Here is how
+to configure npa 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 ``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 ``libopensc.so`` should be located in ``$PREFIX/lib``. Here is how to
+configure npa 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 npa to ``/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"
+
+=========
+Questions
+=========
+
+For questions, please use http://sourceforge.net/projects/vsmartcard/support
+
+

npa/doc/api.rst

@@ -0,0 +1,82 @@
+.. highlight:: c
+
+********************************
+Programming with the nPA Library
+********************************
+
+The nPA library includes a generic implementation for Secure Messaging (SM),
+which might also be used in conjunction with other cards. It is implemented to
+be close to ISO 7816-8 focusing only on encoding rather than implementing
+everything that is needed to get a secure channel. All cryptographic work is
+done by call back functions, which should be appropriatly set for the specific
+card.
+
+Using the German identity card (neuer Personalausweis, nPA) requires user
+authentication via entry of the PIN. Transmitting the PIN in plaintext is
+risky, since it would be transmitted over the air and could be snooped. That's
+why the PACE keyagreement is used to verify the PIN and establish an SM channel
+to the nPA. :npa:`EstablishPACEChannel` does exactly that and if everything
+went fine, it initializes :npa:`sm_ctx` for use of the SM channel. Now
+:npa:`sm_transmit_apdu` can be used to securely transmit arbitrary APDUs to the
+card. You could for example change your PIN or even continue the Extended
+Access Control (EAC) with Terminal Authentication (TA) and Chit Authenitcation
+(CA).
+
+Please consider the following overview to the API as incomplete. The `Doxygen
+documentation <_static/doxygen-npa/modules.html>`_ should be used as programmer's
+reference since it is more detailed.
+
+=====================
+Secure Messaging (SM)
+=====================
+
+The complete documentation can be found `here
+<_static/doxygen-npa/group__sm.html>`_.
+
+-----
+Types
+-----
+.. doxygenstruct:: sm_ctx
+
+---------
+Functions
+---------
+.. doxygenfunction:: sm_transmit_apdu
+.. doxygenfunction:: sm_ctx_clear_free
+
+==============================================================
+Interface to German identity card (neuer Personalausweis, nPA)
+==============================================================
+
+The complete documentation can be found `here
+<_static/doxygen-npa/group__npa.html>`_.
+
+-----
+Types
+-----
+.. doxygenstruct:: establish_pace_channel_input
+.. doxygenstruct:: establish_pace_channel_output
+
+---------
+Functions
+---------
+.. doxygenfunction:: EstablishPACEChannel
+.. doxygenfunction:: npa_reset_retry_counter
+
+-------
+Defines
+-------
+.. doxygendefine:: npa_change_pin
+.. doxygendefine:: npa_unblock_pin
+
+=======
+Example
+=======
+
+In order to compile and execute this example you need to correctly :ref:`set up
+your environment <npa-usage>`.
+
+.. literalinclude:: example.c
+    :lines: 20-
+
+.. @author Frank Morgner <morgner@informatik.hu-berlin.de>

npa/doc/example.c

@@ -0,0 +1 @@
+../src/example.c