documentation; refs #27

doc/doxyfile.in

@@ -723,21 +723,22 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see 
 # the \include command).
 
-EXAMPLE_PATH           = .
+EXAMPLE_PATH           = examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the 
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
 # and *.h) to filter out the source-files in the directories. If left 
 # blank all files are included.
 
-EXAMPLE_PATTERNS       = 
+EXAMPLE_PATTERNS       = *.[ch]xx \
+                         *.doc
 
 # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be 
 # searched for input files to be used with the \include or \dontinclude 
 # commands irrespective of the value of the RECURSIVE tag. 
 # Possible values are YES and NO. If left blank NO is used.
 
-EXAMPLE_RECURSIVE      = NO
+EXAMPLE_RECURSIVE      = YES
 
 # The IMAGE_PATH tag can be used to specify one or more files or 
 # directories that contain image that are included in the documentation (see 
@@ -1651,7 +1652,7 @@ GROUP_GRAPHS           = YES
 # collaboration diagrams in a style similar to the OMG's Unified Modeling 
 # Language.
 
-UML_LOOK               = YES
+UML_LOOK               = NO
 
 # If the UML_LOOK tag is enabled, the fields and methods are shown inside 
 # the class node. If there are many fields or methods and many nodes the 
@@ -1660,7 +1661,7 @@ UML_LOOK               = YES
 # managable. Set this to 0 for no limit. Note that the threshold may be 
 # exceeded by 50% before the limit is enforced.
 
-UML_LIMIT_NUM_FIELDS   = 10
+UML_LIMIT_NUM_FIELDS   = 1
 
 # If set to YES, the inheritance and collaboration graphs will show the 
 # relations between templates and their instances.

doc/examples/suisse-id-demo.cxx

@@ -11,7 +11,9 @@
 #include <QtNetwork/QSslCertificate>
 #include <QtCore/QDateTime>
 
+// show certificate information
 void show(const suisseid::Certificate& cert) {
+// makes use of qt library's certificate class
   QSslCertificate c(QByteArray(cert.data(), cert.size()), QSsl::Der);
   std::cout<<"Certificate info: CN="
            <<QString(c.subjectInfo(QSslCertificate::CommonName)
@@ -22,8 +24,9 @@ void show(const suisseid::Certificate& cert) {
            <<std::endl;
 }
 
+// call with option -h for help
 int main(int argc, char** argv) try {
-  std::string lib("libcvP11.so");
+  std::string lib("libcvP11.so"); // default pkcs#11/cryptoki library
   mrw::args::parse(argc, argv,
                    "Sign a text (optionally several times for performance"
                    " measurements).",
@@ -31,7 +34,9 @@ int main(int argc, char** argv) try {
                    <<mrw::args::decl("l", "library", "cryptoki lirary to load",
                                      mrw::args::decl::param_list()
                                      <<mrw::args::param(lib, "lib")));
+  // now lib contains the dynamic library to load
 
+  // scan for suisseid cards
   suisseid::Cards cards(suisseid::Scanner(lib).scan());
   for (suisseid::Cards::iterator card(cards.begin());
        card!=cards.end(); ++card) {
@@ -68,10 +73,11 @@ int main(int argc, char** argv) try {
                <<"  a: show authentication certificate"<<std::endl
                <<"  d: show digital signature certificate"<<std::endl
                <<"  q: quit"<<std::endl;
-      std::cin>>choice;
+      std::cin>>choice; // small user menu
       try {
         if (choice=="n") { // handled above in the while-loop
         } else if (choice=="c") {
+          // run a check of the card status
           TextualCycle check(*card);
           if (check.run())
             std::cout<<"----> SuisseID is fine"<<std::endl;
@@ -80,6 +86,7 @@ int main(int argc, char** argv) try {
         } else if (choice=="r") {
           std::cout<<"Not yet implemented."<<std::endl;
         } else if (choice=="p") {
+          // change card pins
           std::string oldpin, newpin;
           std::cout<<"Enter Old PIN: ";
           std::cin>>oldpin;
@@ -88,20 +95,26 @@ int main(int argc, char** argv) try {
           if (oldpin.size() && newpin.size())
             (*card)->changePins(newpin, oldpin);
         } else if (choice=="i") {
+          // install new certificates - not fully implemented
           TextualCycle check(*card);
           check.installCerts(true);
         } else if (choice=="z") {
+          // show all certificates on the card
           for (suisseid::Certificates::iterator cert(certs.begin());
                cert!=certs.end(); ++cert) {
             show(*cert);
           }
         } else if (choice=="a") {
+          // show authentication certificate only
           show((*card)->authenticationCertificate());
         } else if (choice=="d") {
+          // show authentication certificate only
           show((*card)->digitalSignatureCertificate());
         } else if (choice=="q") {
+          // done, user quits
           return 0;
         } else {
+          // unknown user command
           std::cout<<"I beg your pardon, Sir?"<<std::endl;
         }
       } catch (const std::exception& x) {
@@ -109,7 +122,7 @@ int main(int argc, char** argv) try {
       }
     } catch (std::exception& x) {
       std::cerr<<"**** ERROR: "<<x.what()<<std::endl;
-      choice="n"; // proceed
+      choice="n"; // proceed to next card
     }
   }
   return 0;

doc/examples/suisse-id-demo.hxx

@@ -12,19 +12,19 @@
 #include <iostream>
 #include <cassert>
 
+// implements a status cycle for text user interface
 class TextualCycle: public suisseid::StatusCycle {
 
   public:
 
+    // just pass the card to parent
     TextualCycle(mrw::Shared<suisseid::Card> card):
         StatusCycle(card) {
     }
 
   protected:
 
-    /// @name slots
-    //@{
-    
+    // callback: ask user for transport pin 
     virtual PinPukChange pinChangeTransportPin() {
       PinPukChange pinpuk;
       std::cout<<"Enter Transport PIN: ";
@@ -34,6 +34,7 @@ class TextualCycle: public suisseid::StatusCycle {
       return pinpuk;
     }
 
+    // callback: ask user for puk
     virtual PinPukChange pinChangePuk() {
       PinPukChange pinpuk;
       std::cout<<"Enter PUK to unlock PKCS#15 PIN: ";
@@ -43,37 +44,44 @@ class TextualCycle: public suisseid::StatusCycle {
       return pinpuk;
     }
     
+    // callback: tell user that transport pin is locked
     virtual void transportPinLocked() {
       std::cout<<"Transport PIN is Locked!"<<std::endl;
     }
 
+    // callback: tell user that pkcs15 pin is locked
     virtual void pkcs15PinLocked() {
       std::cout<<"PKCS#15 PIN is Locked!"<<std::endl;
     }
 
+    // callback: tell user that digital signature pin is locked
     virtual void sigGPinLocked() {
       std::cout<<"SigG PIN is Locked!"<<std::endl;
     }
 
+    // callback: tell user that puk is locked
     virtual void pukLocked() {
       std::cout<<"PUK is Locked!"<<std::endl;
     }
 
+    // callback: tell user that certificates will expire soon
     virtual void certsExpireSoon() {
       std::cout<<"Certificates Expire Soon!"<<std::endl;
     }
 
+    // callback: tell user that certificates have expired
     virtual void certsExpired() {
       std::cout<<"Certificates Expired!"<<std::endl;
     }
 
+    // callback: tell user that certificates have been revoked
     virtual void certsRevoked() {
       std::cout<<"Certificates Revoked!"<<std::endl;
     }
 
   public:
 
-    /// install certificates on the card
+    // install certificates on the card
     virtual bool installCerts(bool force = true) {
       std::cout<<"Installing Certificates ..."<<std::endl;
       std::string pin;
@@ -85,12 +93,14 @@ class TextualCycle: public suisseid::StatusCycle {
       }
       cryptoki::Session session(card()->slot());
       try {
+        // log into the card using the user's pin
         session.login(pin);
       } catch (const cryptoki::wrong_pin& x) {
         std::cout<<"**** Wrong PIN!"<<std::endl;
         std::cout<<x.what()<<std::endl;
         return false;
       }
+      // now store certificates on the card
       std::cout<<"**** Not implemented"<<std::endl;
       return true;
     }

src/cardos.hxx

@@ -19,14 +19,16 @@
 // use e.g. #define CARDOS_LOG(X) std::clog<<X<<std::endl
 #endif
 
-namespace cardos {
+/** @defgroup gcardos C++ Access to Siemens CardOS V4.4
+    Implements APDUs for accessing Siemens CardOS V4.4 smartcards. */
+//@{
+/// @defgroup cardosexception CardOS Exceptions
+/// @defgroup cardostypes CardOS Types
+/// @defgroup cardoslib CardOS Library
+//@}
 
-  /// @defgroup gcardos C++ Access to Siemens CardOS V4.4
-  /** Implements APDUs for accessing Siemens CardOS V4.4 smartcards. */
-  //@{
-  /// @defgroup cardosexception CardOS Exceptions
-  /// @defgroup cardostypes CardOS Types
-  /// @defgroup cardoslib CardOS Library
+/// @ref gcardos @copydoc gcardos
+namespace cardos {
 
   /// @addtogroup cardosexception CardOS Exceptions
   //@{

src/cryptaux.hxx

@@ -14,7 +14,11 @@
 #include <stdexcept>
 #include <algorithm>
 
-/*! @defgroup gcrypto Auxiliary Crypto-Functions */
+/*! @defgroup gcrypto Auxiliary Crypto-Functions
+    
+    Auxiliary often used funcions in cryptographic environment, such
+    as logging, converting binary from and to hexadecimal or creating
+    readable texts from binary data. */
 //@{
 
 #define CRYPTOLOG_QUOTE(X) CRYPTOLOG_QUOTE2(X)
@@ -68,7 +72,7 @@
 #  endif
 #endif
 
-//! @see gcrypto
+//! @ref gcrypto @copydoc gcrypto
 namespace crypto {
   
   static const std::string LETTER_CHARS

src/cryptoki.hxx

@@ -63,7 +63,7 @@ namespace pcsc {
   std::string version();
 }
 
-//! @see gcryptoki
+//! @ref gcryptoki @copydoc gcryptoki
 namespace cryptoki {
 
   //! @addtogroup cryptokitypes

src/openssl.hxx

@@ -60,12 +60,13 @@ namespace pcsc {
   std::string version();
 }
 
-/*! @defgroup gopenssl C++ Wrapper around OpenSSL API */
+/*! @defgroup gopenssl C++ Wrapper around OpenSSL API
+    Support for SSL-connections, engines, keys and certificates. */
 //@{
 //! @defgroup openssllib OpenSSL C++ Library
 //! @defgroup opensslexceptions OpenSSL Exceptions
 
-//! @see gopenssl
+//! @ref gopenssl @copydoc gpcsc
 namespace openssl {
 
   //============================================================================

src/overview.doc

@@ -7,17 +7,71 @@
 
 /*! @mainpage
 
-    There are three namespaces which correspond to the three modules
-    that are implemented here:
+    The first intention of this 
 
-    - @ref gpcsc
-    - @ref gcryptoki
-    - @ref gopenssl
+    There are several [Namespaces](namespaces.html) which correspond
+    to the [Modules](modules.html) that are implemented. All libraries
+    libraries deal with hardware token cryptography. Some libraries
+    are just clean C++-wrappers around the original libraries that are
+    implemented in ugliest C manner. The warppers care about memory-
+    and resource-management and implement a simple and easy C++
+    interface, including std::string for binary data and exceptions
+    for error handling.
 
-    All these three libraries deal with hardware token cryptografy and
-    all three libraries are implemented in ugliest C manner. The
-    warpper cares about memory- and resource-management and implements
-    a simple and easy C++ interface, including exceptions for error
-    handling.
+    For special documentations, such as global overviews and
+    tutorials, please refere to [Pages](pages.html).
 
+    @chapter mainoverview Overview of the Components
+
+    @dot
+    digraph g {
+      compound=true;
+      subgraph clustercard {
+        label="Hardware-Token";
+        token;
+      }
+      subgraph clustersystempcsc {
+        label="System Library PCSC-Lite";
+        pcscd;
+        libpcsclite [shape=component];
+      }
+      subgraph clusteropenssl {
+        label="OpenSSL Library";
+        OpenSSL [shape=component];
+      }
+      subgraph clustermiddleware {
+        label
+        ="Middleware for Hardware Access\ndynamically loaded shared object";
+        pkcs11 [label="libpkcs11.so\nlibcvP11.so\nlibcryptoki.so\n..."]
+               [shape=component];
+      }
+      subgraph clusterlibpcscxx {
+        label="C++ libpcscxx-Library";
+        node [shape=component];
+        pcsc [URL="\ref gpcsc"];
+        cryptoki [URL="\ref gcryptoki"];
+        cardos [URL="\ref gcardos"];
+        suisseid [URL="\ref gsuisseid"];
+        openssl [URL="\ref gopenssl"];
+        crypto [URL="\ref gcrypto"];
+        {rank=same pcsc; cryptoki; openssl; crypto;}
+      }
+      {rank=same OpenSSL; pkcs11;}
+      {pkcs11; OpenSSL; pcsc;} -> libpcsclite [lhead=clustersystempcsc];
+      libpcsclite -> pcscd;
+      pcscd -> token [lhead=clustercard];
+      cryptoki -> pkcs11 [lhead=clustermiddleware];
+      cardos -> pcsc;
+      suisseid -> cardos;
+      suisseid -> cryptoki;
+      openssl -> OpenSSL [lhead=clusteropenssl];
+    }
+    @enddot
+
+    @see gpcsc PCSC-Lite is a middleware to access a smart card using SCard API
+    @see gcryptoki Cryptoki, also known as PKCS#11 is a higher level API
+    @see gopenssl OpenSSL is a high level cryptography library
+    @see gcardos CardOS is an operating system on Siemens smart cards
+    @see gsuisseid SuisseID is a standardized digital identity in Switzerland
+    @see gcrypto Crypto implements some auxiliary crypto funtions
     */

src/pcsc.hxx

@@ -103,7 +103,7 @@ namespace pcsc {
 /*! @defgroup pcsclib PCSC C++ Library */
 /*! @defgroup pcscexceptions PCSC Exceptions */
 
-//! @see gpcsc
+//! @ref gpcsc @copydoc gpcsc
 namespace pcsc {
 
   //============================================================================

src/suisseid.hxx

@@ -14,7 +14,7 @@
 #include <mrw/vector.hxx>
 #include <mrw/shared.hxx>
 
-/*! @defgroup gsuisseid C+ Wrapper to access SuisseID smart cards
+/*! @defgroup gsuisseid C++ library to access SuisseID smart cards
 
     This library allows access to the Swiss digital identity cards
     (SuisseID).
@@ -23,14 +23,29 @@
     suisseid::Scanner to scan for a list of SuisseID cards on the system.
 
     @see http://www.suisseid.ch
-    @see http://postsuisseid.ch */
+    @see http://postsuisseid.ch
+
+*/
 //@{
 /*! @defgroup suisseidlib SuisseID Library */
 /*! @defgroup suisseidtypes SuisseID C++ Types and Auxiliary */
 /*! @defgroup suisseidconsts SuisseID C++ Constants */
 /*! @defgroup suisseidexceptions SuisseID Exceptions */
+/** @example suisse-id-demo.cxx
+
+    Usage of @ref gsuisseid This is a comprehensive example how you
+    can access a SuisseID and access to certificates on that card.
+
+    First implement a status cycle, here for @c std::cin and @c
+    std::cout as user interface in the @c suisse-id-demo.hxx header
+    file:
+
+    @include suisse-id-demo.hxx
+
+    Then instanciate and use this class from your code: */
 //@}
 
+/// @ref gsuisseid @copydoc gsuisseid
 namespace suisseid {