Open eCard

{{toc}}

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

h2. 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:

p=. !OpenECardHighLevelDesign.png(High level design of the Open eCard App)!

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.

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

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

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

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

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

h3. 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 [[Add-on System|here]].

h3. 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_.

h3. Crypto

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

h3. 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 [[PKCS11|here]].

h2. 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| Project Structure]] page.

h2. 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 [[Control Interface|here]].

h2. 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| TLS Design]] wiki page.