• Table of contents
• Architecture
  • High Level Design
    • GUI (Graphical User Interface)
    • IFD (Interface Device)
    • EventManger
    • SAL (Service Access Layer)
    • Dispatcher
    • Add-ons
    • Bindings
    • Crypto
    • Browser Integration
  • Modularization of the source code
  • Control Interfaces
  • TLS Design

Architecture¶

On this wiki page and subsequent wiki pages the design and architecture of the Open eCard App is described. The pages are derived mainly from the following two papers:

• http://www.ecsec.de/pub/2012_Sicherheit.pdf
• http://www.ecsec.de/pub/2013_OID_Platform.pdf

High Level Design¶

The Open eCard design is inspired by the eCard API Framework specified in BSI-TR03112 which itself relays on the standards CEN15480 and ISO/IEC24727. An overview of this high level design is provided in the following picture:

As the figure depicted the design is covered by multiple modules. This has the advantage that the components are more or less independent and exchangeable for instance the default IFD is implemented for a smart card stack called PC/SC but it might be simply replaced by an implementation for SICCT smart card terminal. Another example is the GUI module the richclient application uses a Swing implementation of the UI and in the Android client there it is replaced by an Android specific UI implementation. Following the main modules are explained.

GUI (Graphical User Interface)¶

The GUI is connected via an abstract interface which allow to easily exchange the underlying implementation. The abstract interface is required because an implementation is always specific for a platform for instance the Swing GUI of the Richclient is not usable on Android because the Java implementation of android does not provide the Swing framework. So an abstract description of the user interface was necessary, the abstract components are usable by all components requiring a interaction with the user. The platform dependent user interface implementation has to interpret the abstract components and visualize them. An UML description of the abstract interface is available here.

IFD (Interface Device)¶

The IFD provides a message oriented interface according to ISO/IEC 24727-4 which is capable to access ISO/IEC 7816-4 based devices like smart cards. As you can see in the the design picture the IFD contains sub modules which provide additional interfaces for the communication with the devices. The depicted PACE module enables the application to use the PACE protocol which allows secure communication between the device and the terminal accessing the device.

EventManger¶

The EventManager is responsible to detect hardware relevant events and propagates them to the rest of the system. Examples for such events are the addition or removal of a card reader or a card. The CardRecognition module of the EventManager is used to identify inserted cards. The recognition module is also extensible so it is easily possible to support a new smart card or device by providing a so called CardInfo file which is an XML file containing a description of the card. The description maps the ISO/IEC 7816 operations to the functions provided by the eCard API Framework.

SAL (Service Access Layer)¶

Similar to the IFD is the SAL a message oriented interface according to ISO/IEC 24727-3. The SAL provides als an extension mechanism, which enables the addition of new authentication protocols without changing major parts of the implementation.

Dispatcher¶

The Dispatcher provides a centralized entry point for the handling of incoming and outgoing messages. This reduces the amount of Java code and the complexity of the Open eCard App.

Add-ons¶

The Add-on system is an Framework which allows to extend the basic eID platform with different kinds of add-ons. The add-ons are manage by an AddonManager which uses currently two registries to load add-ons. There is a classpath registry which is responsible for loading the packages from the classpath so it just loads the integrated add-ons. For external add-ons there is a file registry which loads the add-on packages from a specific directory. If you would like to know more about the add-on system and development take look at our wiki site about add-ons. The page is here.

Bindings¶

Add-ons_interact via _Bindings with applications of service providers. The components implements a transport mechanism like HTTP or SOAP and direct the messages in an abstract form to the add-ons.

Crypto¶

The Crypto component encapsulates common cryptographic functions, which are used by other components. It is based on the Bouncy Castle crypto library which makes it easy to port it to platforms without support for the full Java Cryptography Architecture (JCA), such as Android for instance.

Browser Integration¶

The Browser Integration module is just s symbol for applications in general, this is not restricted to just a browser. So every other application may e.g. call the localhost interface to invoke for instance the getStatus control interface to retrieve the current state of the eID client. Also the usage of an PKCS11 module for the browser or other applications which are able to use such modules is possible. More information of the PKCS11 topic are available in on the wiki page here.

Modularization of the source code¶

The project is written in Java and there are several build tools available. The Open eCard Team has chosen Maven as the way to go. Maven allows to define project with several sub projects/modules this made the process of transforming the abstract modularized design into the projects source code organization. An overview of the currently available modules is provided on the Project Structure page.

Control Interfaces¶

The eID client provides currently some interfaces to allows external applications to invoke functions via control interfaces which are accessible via the localhost interface. The following interfaces are available.

eID Activation	Triggers the authentication with the German eID card or other cards based on TLS authentication.
GetStatus	Returns status information about the eID client.
WaitForChange	Returns status changes after a previous GetStatus call.
ShowUI	Opens specific parts of the user interface.

 
Detailed information about the control interface calls are available on a separate wiki page here.

TLS Design¶

The primary library for cryptography related tasks in the Open eCard App is the Bouncy Castle library which is also used for the TLS connection. The design of the TLS interfaces is depicted in the TLS Design wiki page.