Compromise with documentation: Include the most important parts of libnpa with

breathe and reference the details with doxylink to external doxygen pages


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

doc/_static/doxygen-npa

@@ -0,0 +1 @@
+../doxygen/npa/html

doc/conf.py

@@ -11,7 +11,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os, breathe
+import sys, os, breathe, doxylink
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -25,7 +25,7 @@ import sys, os, breathe
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["breathe"]
+extensions = ["breathe", "doxylink"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -48,9 +48,9 @@ copyright = u'2011, Dominik Oepen, Frank Morgner'
 # built documents.
 #
 # The short X.Y version.
-version = '0.7'
+#version = '0.7'
 # The full version, including alpha/beta/rc tags.
-release = '0.7'
+release = '2011-05-20'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -215,5 +215,6 @@ man_pages = [
      [u'Dominik Oepen, Frank Morgner'], 1)
 ]
 
-breathe_projects = {"npa": "doxygen/npa"}
+breathe_projects = {"npa": "doxygen/npa/xml"}
 breathe_default_project = "npa"
+doxylink = { 'npa' : ('doxygen/npa/npa.tag', '_static/doxygen-npa/'), }

doc/doxygen/ccid

@@ -1 +0,0 @@
-../../ccid/doc/xml/

doc/doxygen/npa

@@ -1 +1 @@
-../../npa/doc/xml/
+../../npa/doc/

doc/index.rst

@@ -17,6 +17,7 @@ Contents:
    virtualsmartcard
    pcsc-relay
    npa
+   npaapi
    ccid
 
 Download

doc/npaapi.rst

@@ -0,0 +1,41 @@
+.. highlight:: c
+
+****************
+nPA API Overview
+****************
+
+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)
+=====================
+
+.. doxygenfile:: sm.h
+
+==============================================================
+Interface to German identity card (neuer Personalausweis, nPA)
+==============================================================
+
+.. doxygenfile:: npa.h
+
+.. @author Frank Morgner <morgner@informatik.hu-berlin.de>

npa/Doxyfile.in

@@ -7,7 +7,7 @@ FILE_PATTERNS          = *.h
 RECURSIVE              = YES
 EXAMPLE_PATH           = @top_srcdir@/src
 GENERATE_HTML          = YES
-GENERATE_TAGFILE       = @builddir@/doc/$(PROJECT).tag
+GENERATE_TAGFILE       = @builddir@/doc/@PACKAGE_NAME@.tag
 GENERATE_XML           = YES
 XML_OUTPUT             = xml
 OPTIMIZE_OUTPUT_FOR_C  = YES

npa/README.dox

@@ -80,11 +80,4 @@ Questions
 For questions, please use http://sourceforge.net/projects/vsmartcard/support
 
 
-=========
-API index
-=========
-
-.. doxygenindex::
-   :project: npa
-
 .. @author Frank Morgner <morgner@informatik.hu-berlin.de>

npa/src/npa/npa.h

@@ -20,7 +20,7 @@
 */
 /**
  * @file
- * @defgroup npa Smart card interface to the German identity card (neuer Personalausweis, nPA)
+ * @defgroup npa Interface to German identity card (neuer Personalausweis, nPA)
  * @{
  */
 #ifndef _CCID_NPA_H

npa/src/npa/sm.h

@@ -18,7 +18,7 @@
  */
 /**
  * @file
- * @defgroup sm Secure Messaging
+ * @defgroup sm Secure Messaging (SM)
  * @{
  */
 #ifndef _CCID_SM_H