documentation; refs #27

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;
     }