Open eCard

{{toc}}

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

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

h2. Add-on Types

h3. 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 [[Add-on System#IFD protocol implementation details|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.

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

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

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

h2. Architecture of an Add-on package

h3. General architecture

h3. The Add-on Manifest

h3. Types available in the configuration

h3. Configuration of an Add-on in the client

h2. Add-on Implementation

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

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

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

<pre>

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

</pre>

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:

<pre>

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

</pre>

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.