Add-on System¶

On this wiki page you'll find detailed information about the add-on development like the different kinds of add-ons and how they are enabled to communicate with core application.

Definition of Add-on in the Open eCard context¶

Add-on is the generic term for a component that enhances the functionality of the Open eCard App.

Extensions are independent from the context. Moreover, they are included directly into the user interface and can be executed by the user. For instance, an add-on that provides a PIN change functionality for smart cards is classified as an extension.

Plug-ins depend on the context in which the user uses the application. Performing an authentication to a service using a particular smart card, for instance, requires a plug-in which is capable of providing such functionality. Subsequently, plug-ins require a communication with bindings to interact with external applications and services. Furthermore, we distinguish between IFD, SAL, and application plug-ins.

Add-on Types¶

IFD Plug-ins¶

An IFD Plug-in represents a protocol which is used to extend the IFD. The protocol implementation may enable the IFD to perform a special user authentication method or establish a secure channel between a card and cardreader to protect the communication from being eavesdropped. Each protocol must have a unique identifier in form of a URI. The URI must be associated with the actual implementation as described in the IFD protocol implementation details. In addition, each protocol plug-in must implement the IFD Protocol Interface and must define protocol-specific AuthenticationProtocolData used in the EstablishChannel call and corresponding response message. An example for an IFD Plugin is the Password Authenticated Connection Establishment (PACE) protocol which is executed by the IFD. It is included as integrated add-on in the Open eCard App.

SAL Plug-ins¶

The SAL provides generic interfaces to common smart card services like Crypto services or differential identity services. The SAL can be extended by plug-ins, which provide implementations of protocols for the Crypto Services and the Differential Identity Services as required for the use of specific signature cards and electronic identity cards for example. The plugin concept is quite similar to the one used for the IFD. There is also an unique identifier necessary in the protocol implementation but an SAL protocol may have multiple steps and allows the definition more sophisticated user interfaces including a sequence of interaction steps to represent information dialogues and general user consents. For example the already included Extended Access Control (EAC) protocol is one of this kind. The protocol is used while authentication process with German eID card.

Application Plug-ins¶

Application plug-ins provide a mechanism to add additional functionality to the eID application with which external applications can communicate. Depending on the type of the underlying binding, this could be a browser, a PKCS#11 module or even a remote application. Protocol bindings realize the connection to the external world. While a broad variety of transport protocols could be supported, the most obvious choices are HTTP and SOAP,
as they are stipulated by [Fed12d, Section 3.2] for example. Given the properties of the activation mechanism, HTTP and SOAP, as well as similar transport protocols, the abstract requirements for a protocol binding are given as follows: A protocol binding must support

a request-response semantic,
a mapping mechanism to identify the appropriate plug-in for a request,
messages comprising a body, named parameters and attachments,
an error delivery mechanism, and
a redirect semantic.

Application Extensions¶

Extensions enhance – similar to plug-ins – the basic eID platform and provide additional functionality, but they do not depend on the context in which the eID application is used. Further, extensions are included into the user interface and can be started directly by the user. Similar to application plug-ins, the AppExtensionAction interface contains an execute function. However, this function does not have any parameters nor does it have a result. Therefore, it cannot be used with a binding and only be triggered manually.

Architecture of an Add-on package¶

General architecture¶

The Add-on Manifest¶

Types available in the configuration¶

Configuration of an Add-on in the client¶

Add-on Implementation¶

IFD protocol implementation details¶

This section describes the add-on system from the perspective of a developer.
The implementation of the add-on system is located in the maven module with the group Id org.openecard and the artifact Id addon.
All classes are in a sub namespace of org.openecard.addon. The module is divided into the following five packages:

org.openecard.addon
In this package are the main classes of the add-on system, for example the AddonManager or the different AddonRegistries.
org.openecard.addon.bind
This package includes all classes representing the interface between an addon and a specific binding. That is to say, here are the classes needed to convert a specific request, for example a HTTP request that arrives via the localhost binding, into a generic request, which is independent from binding and vice versa for the response.
org.openecard.addon.ifd
In here are the classes that specify the interface for an IFD protocol and the factory to instantiate such a protocol.
org.openecard.addon.manifest
This package accumulates all classes needed to convert (automatically) between the XML represantation of the add-on description and it's java object pendants.
org.openecard.addon.sal
In here are the classes that specify the interface for an SAL protocol and the factory to instantiate such a protocol.

Types of add-ons¶

In the context of Open eCard App, the terms add-on, plug-in and extension are defined as follows.

Add-on is the generic term for a component that enhances the functionality of the Open eCard App.

Extensions are independent from the context. Moreover, they are included directly into
the user interface and can be executed by the user. For instance, an add-on that provides a
PIN change functionality for smart cards is classified as an extension.

Plug-ins depend on the context in which the user uses the application. Performing
an authentication to a service using a particular smart card, for instance, requires a plug-in
which is capable of providing such functionality. Subsequently, plug-ins require a communication
with bindings to interact with external applications and services. Furthermore,
we distinguish between IFD, SAL, and application plug-ins.

Add-on development¶

This section describes the steps to take when developing an add-on.
As first step a new XML file called Addon.xml in the META-INF directory of the project should be created and the fields that describe the general part of the add-ons can already be filled.
An example file for a PIN Management addon could look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AddonBundleDescription>
    <ID>PIN-Plugin</ID>
    <Version>1.0</Version>
    <About />
    <License />
    <LocalizedName xml:lang="DE">PIN Verwaltung</LocalizedName>
    <LocalizedDescription xml:lang="DE">Verwaltung von PIN/ PUK und gegebenenfalls anderen Geheimnissen der Chipkarte.
    </LocalizedDescription>
    <LocalizedName xml:lang="EN">PIN Management</LocalizedName>
    <LocalizedDescription xml:lang="EN">Management of PIN/ PUK and possibly other secrets of the smart-card.</LocalizedDescription>
    <Logo>images/logo.png</Logo>
    <ConfigDescription />
    <BindingActions />
    <ApplicationActions />
    <IFDActions />
    <SALActions />
</AddonBundleDescription>

As can be seen, some fields can be localized. That fields are: LocalizedName, LocalizedDescription and About
The next step is to think about what actions should be offerd by the add-on and of what type these actions are.
For the PIN management example there are two actions. An action to change a PIN and a second action to unblock a PIN.
These actions are not of type ProtocolPlugin nor AppPluginAction, but of type AppExtensionAction, as they expand the function of the Open eCard App independent from a context.
This means two classes implementing the AppExtensionAction interface need to be added to the project and the two AppExtensionActionDescription that belong to them need to be added to the XML description.
Assume we are working in the org.openecard.plugins.pinplugin namespace and the two actions are called ChangePINAction and UnblockPINAction, the resulting XML would now look similar to this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AddonBundleDescription>
    <ID>PIN-Plugin</ID>
    <Version>1.0</Version>
    <About />
    <License />
    <LocalizedName xml:lang="DE">PIN Verwaltung</LocalizedName>
    <LocalizedDescription xml:lang="DE">Verwaltung von PIN/ PUK und gegebenenfalls anderen Geheimnissen der Chipkarte.
    </LocalizedDescription>
    <LocalizedName xml:lang="EN">PIN Management</LocalizedName>
    <LocalizedDescription xml:lang="EN">Management of PIN/ PUK and possibly other secrets of the smart-card.</LocalizedDescription>
    <Logo>images/pin-management.png</Logo>
    <ConfigDescription />
    <BindingActions />
    <ApplicationActions>
        <AppExtensionActionDescription>
            <ID>ChangePINAction</ID>
            <ClassName>org.openecard.plugins.pinplugin.ChangePINAction</ClassName>
            <LocalizedName xml:lang="DE">PIN ändern</LocalizedName>
            <LocalizedDescription xml:lang="DE">Mit dieser Aktion können Sie ihre PIN ändern.</LocalizedDescription>
            <LocalizedName xml:lang="EN">Change PIN</LocalizedName>
            <LocalizedDescription xml:lang="EN">With this action you can change your PIN.</LocalizedDescription>
            <ConfigDescription />
        </AppExtensionActionDescription>
        <AppExtensionActionDescription>
            <ID>UnblockPINAction</ID>
            <ClassName>org.openecard.plugins.pinplugin.UnblockPINAction</ClassName>
            <LocalizedName xml:lang="DE">PIN entsperren</LocalizedName>
            <LocalizedDescription xml:lang="DE">Mit dieser Aktion können Sie ihre PIN entsperren.</LocalizedDescription>
            <LocalizedName xml:lang="EN">Unblock PIN</LocalizedName>
            <LocalizedDescription xml:lang="EN">With this action you can unblock your PIN.</LocalizedDescription>
            <ConfigDescription />
        </AppExtensionActionDescription>
    </ApplicationActions>
    <IFDActions />
    <SALActions />
</AddonBundleDescription>

For the actual implementation part of the add-on, the following has to be considered.
The actions need to implement the AppExtensionAction interface, which itself extends the FactoryBaseType interface.
Altogether, three functions are to be implemented:

void execute();
the actual logic of the action, in this case the PIN change, will take place here
void init(Context context) throws FactoryInitializationException;
initialization of the action; the given Context allows access to components of the Open eCard App like UserConsent or Dispatcher
void destroy();
closing resources and further cleanup.