diff --git a/doc/doxyfile.in b/doc/doxyfile.in index d6140ce..1de3527 100644 --- a/doc/doxyfile.in +++ b/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. diff --git a/doc/examples/suisse-id-demo.cxx b/doc/examples/suisse-id-demo.cxx index 93bd553..8d59034 100644 --- a/doc/examples/suisse-id-demo.cxx +++ b/doc/examples/suisse-id-demo.cxx @@ -11,7 +11,9 @@ #include #include +// 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=" <>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"<>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?"< #include +// implements a status cycle for text user interface class TextualCycle: public suisseid::StatusCycle { public: - + + // just pass the card to parent TextualCycle(mrw::Shared 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!"<slot()); try { + // log into the card using the user's pin session.login(pin); } catch (const cryptoki::wrong_pin& x) { std::cout<<"**** Wrong PIN!"< #include -/*! @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 diff --git a/src/cryptoki.hxx b/src/cryptoki.hxx index 7aed7a0..eb3a8b3 100644 --- a/src/cryptoki.hxx +++ b/src/cryptoki.hxx @@ -63,7 +63,7 @@ namespace pcsc { std::string version(); } -//! @see gcryptoki +//! @ref gcryptoki @copydoc gcryptoki namespace cryptoki { //! @addtogroup cryptokitypes diff --git a/src/openssl.hxx b/src/openssl.hxx index d23a8cd..c374720 100644 --- a/src/openssl.hxx +++ b/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 { //============================================================================ diff --git a/src/overview.doc b/src/overview.doc index 79440e6..ec1b9db 100644 --- a/src/overview.doc +++ b/src/overview.doc @@ -7,17 +7,71 @@ /*! @mainpage - There are three namespaces which correspond to the three modules - that are implemented here: - - - @ref gpcsc - - @ref gcryptoki - - @ref gopenssl - - 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. - + The first intention of this + + 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. + + 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 */ diff --git a/src/pcsc.hxx b/src/pcsc.hxx index ffea30f..99e66d0 100644 --- a/src/pcsc.hxx +++ b/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 { //============================================================================ diff --git a/src/suisseid.hxx b/src/suisseid.hxx index 7c79c00..9205a43 100644 --- a/src/suisseid.hxx +++ b/src/suisseid.hxx @@ -14,7 +14,7 @@ #include #include -/*! @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 {