libraries/libpcscxx
1
0
Fork 0
Code Issues Releases Activity

documentation; refs #27

Browse Source
This commit is contained in:
Marc Wäckerlin
2014-01-31 13:32:31 +00:00
parent 0eb4a19c37
commit 1e45bea4d4
10 changed files with 140 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
doc/doxyfile.in
View File

@@ -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.

19
doc/examples/suisse-id-demo.cxx
View File

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

20
doc/examples/suisse-id-demo.hxx
View File

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

16
src/cardos.hxx
View File

@@ -19,15 +19,17 @@
// use e.g. #define CARDOS_LOG(X) std::clog<<X<<std::endl
#endif
/** @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 {
/// @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
/// @addtogroup cardosexception CardOS Exceptions
//@{
//============================================================================

8
src/cryptaux.hxx
View File

@@ -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

2
src/cryptoki.hxx
View File

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

5
src/openssl.hxx
View File

@@ -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 {
//============================================================================

78
src/overview.doc
View File

@@ -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
The first intention of this
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.
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
*/

2
src/pcsc.hxx
View File

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

19
src/suisseid.hxx
View File

@@ -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 {