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 card reader 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 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

An Add-on package is an Java archive (JAR) file which bundles all requires resources like libraries etc. The recognition in the base application is done with via an add-on manifest file located in the _META-INF_ directory. The manifest file has to have the name _addon.xml_ else the archive is not recognized as add-on. This file describes the data model of the add-on you'll find it below. The data model is an XML structure containing general information such as the name, the textual description and configuration entries for changeable settings of the add-on. Furthermore actions are contained which represent the different add-on types from above. The settings are stored in an add-on specific directory and are loaded as Java Properties by the ad-on framework.

p=. !{width:70%; height:70%}description.png(Add-on manifest data model in UML)!

h3. The Add-on Manifest

This section shows all possible entries for an add-on manifest file and explain there meaning. The manifest is more or less divided into two parts the first one states the general information about the add-on and the second one contains the description of the add-on classes and configuration. So lets start with the general information section.

<pre>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<AddonSpecification>

    <ID>123</ID>

    <Version>1.0-SNAPSHOT</Version>

    <License>WTFPL</License>

    <LicenseText xml:lang="EN">

        <![CDATA[<center><b>DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE</b>

        <br><br>

        Version 2, December 2004

        <br><br>

        Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>

        </center>

        <br><br>

        Everyone is permitted to copy and distribute verbatim or modified

        copies of this license document, and changing it is allowed as long

        as the name is changed.

        <br><br>

        DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE

        TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

        <br><br>

        0. You just DO WHAT THE FUCK YOU WANT TO.]]>

    </LicenseText>

    <LocalizedName xml:lang="DE">DummyAddon</LocalizedName>

    <LocalizedName xml:lang="EN">DummyAddon</LocalizedName>

    <LocalizedDescription xml:lang="EN">Dummy addon which prints some text to standard output and log file.</LocalizedDescription>

    <LocalizedDescription xml:lang="DE">Dummy Addon, das nur etwas Text auf der Standardausgabe ausgibt und in die Logdatei schreibt.</LocalizedDescription>

    <About xml:lang="EN">

        <![CDATA[About:

        This plugin is just for testing purpose of the Open eCard Addons about dialog. It follows some dummy text to check formatting and wrapping. Lorem ipsum dolor 

        sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et

        accusam et justo duo dolores et ea rebum.]]>

    </About>

    <Logo>DummyLogo.gif</Logo>

    <ConfigDescription>

        <Entries>

            <EnumListEntry>

                <Key>Animal_key</Key>

                <Value>Dog</Value>

                <Value>Cat</Value>

                <Value>Mouse</Value>

                <Value>Elephant</Value>

                <Value>Donkey</Value>

                <LocalizedName xml:lang="DE">Tier-ConfigurationEntry</LocalizedName>

                <LocalizedName xml:lang="EN">Animal configuration entry</LocalizedName>

                <LocalizedDescription xml:lang="DE">Beschreibung des Tier-ConfigurationEntry</LocalizedDescription>

                <LocalizedDescription xml:lang="EN">Description of the animal configuration entry</LocalizedDescription>

            </EnumListEntry>

            <EnumEntry>

                <Key>Kitchen_key</Key>

                <Value>Spoon</Value>

                <Value>Fork</Value>

                <Value>Knife</Value>

                <Value>Cup</Value>

                <Value>Mug</Value>

                <LocalizedName xml:lang="DE">Küchen-ConfigurationEntry</LocalizedName>

                <LocalizedName xml:lang="EN">Kitchen configuration entry</LocalizedName>

                <LocalizedDescription xml:lang="DE">Beschreibung des Küchen-ConfigurationEntry</LocalizedDescription>

                <LocalizedDescription xml:lang="EN">Description of the Kitchen configuation entry</LocalizedDescription>

            </EnumEntry>

        </Entries>

    </ConfigDescription>

    [...]

</AddonSpecification>

</pre>

As you can see the manifest starts with the @<AddonSpecification>@ tag which covers the complete description. Every add-on requires at least the elements @<ID>@, @<Version>@, @<License>@, @<Logo>@ and a @<ConfigDescription>@ which are explained below. 

|@<ID>@                |A unique identifier for the add-on package.                                                                                                                         |

|@<Version>@           |The version number of the add-on. This number is used to select an add-on in case there are several versions available.                                             |

|@<License>@           |This element is expected to contain the name of the license of the add-on. For instance _LGPL Version 3_ or _Proprietary_ are such names but in case of a custom or proprietary license you should state the text of the license in the optional element @<LicenseText>@ field.                                                                                 |

|@<Logo>@              |This element states a name of a logo file contained in the add-on package. This logo is displayed in the GUI in case there are configuration options for your add-on.                                                                                                                                                                                     |

|@<ConfigDescription>@ |The element is used to state configuration entries which are used by all parts of the addon. For complete description of the @<ConfigDescription>@ see the next section. If there are no such configuration entries the element may be set to empty witht the element tag @<ConfigDescription/>@. A detailed description of this element is available [[Add-on System#Types available in the configuration|here]].                                                                                                                                |

The optional elements of this first section are @<LicenseText>@, @<LocalizedName>@, @<LocalizedDescription>@ and @<About>@.

|@<About>@                |Localized string containing the typical information state in an about dialog. The elements may appear several times for different languages. |

|@<LicenseText>@          |Localized string containing the license text of the add-on. The element may appear several times for different languages.                    |

|@<LocalizedDescription>@ |Localized string containing a description of the add-on. The element may appear several times for different languages.                       |

|@<LocalizedName>@        |Localized string containing the name of the add-on. The element may appear several times for different languages.                            |

*Note:* The elements @<About>@ and @<LicenseText>@ may contain a @CDATA@ block containing basic HTML code to format the text. This feature heavily depends on the UI implementation. For example the richclient which uses the Swing Framework supports just HTML in version 3.2. Other gui implementations may support higher versions and so more tags.

 

 

Now we have the general part of the add-on so let's go on with the second part. The second part contains the descriptions of the available actions which have to appear in the following order @<BindingActions>@, @<ApplicationActions>@, @<IFDActions>@ and @<SALActions>@.

* *BindingActions* contain the descriptions of Application Plugin

* *ApplicationActions* contain the descriptions of Application Extensions

* *IFDActions* contain the descriptions of IFD Plugins

* *SALActions* contain the descriptions of SAL Plugins

Every *Actions element may contain zero or more elements which describe the actions. An example of the second part is below but note there don't have to be all actions available it's just an example non relevant actions do not have to appear or may be stated as empty.

<pre>

    <AddonSpecification>

        [...]

        <BindingActions>

            <AppPluginSpecification>

                <ClassName>package.path.to.my.class</ClassName>

                <LoadOnStartup>true</LoadOnStartup>

                <LocalizedName xml:lang="EN">Test class</LocalizedName>

                <LocalizedDescription xml:lang="EN">Test descriptions</LocalizedDescription>

                <ResourceName>/test</ResourceName>

                <ConfigDescription/>

                <Parameters>

                    <Name>Foo</Name>

                    <Value>Bar</Value>

                </Parameters>

                <Body>

                    <MimeType>text/html</MimeType>

                    <Node><![CDATA[<html><head></head><body>test</body></html>]]></Node>

                </Body>

                <Attachments>

                    <MimeType>application/octet-stream</MimeType>

                    <Name>signature.asc</Name>

                </Attachments>

            </AppPluginSpecification>

        </BindingActions>

        <ApplicationActions>

            <AppExtensionSpecification>

                <ID>123</ID>

                <ClassName>org.openecard.addon.openecarddummyaddon.DummyAddonStep</ClassName>

                <LoadOnStartup>true</LoadOnStartup>

                <LocalizedName xml:lang="DE">Test-ExtensionAction</LocalizedName>

                <LocalizedName xml:lang="EN">Test extension action</LocalizedName>

                <LocalizedDescription xml:lang="DE">Testbeschreibung</LocalizedDescription>

                <LocalizedDescription xml:lang="EN">test description</LocalizedDescription>

                <ConfigDescription>

                    <Entries>

                        <EnumEntry>

                            <Key>Foo</Key>

                            <Value>bar</Value>

                            <LocalizedName xml:lang="DE">Test-ConfigurationEntry</LocalizedName>

                            <LocalizedName xml:lang="EN">Test configuration entry</LocalizedName>

                            <LocalizedDescription xml:lang="DE">Testbeschreibung</LocalizedDescription>

                            <LocalizedDescription xml:lang="EN">test description</LocalizedDescription>

                        </EnumEntry>

                    </Entries>

                </ConfigDescription>

            </AppExtensionSpecification>

        </ApplicationActions>

        <IFDActions>

            <ProtocolPluginSpecification>

                <URI>urn:uri:1.2.3</URI>

                <ClassName>package.path.to.protocol.class</ClassName>

                <LoadOnStartup>false</LoadOnStartup>

                <LocalizedName xml:lang="EN">Test Protocol</LocalizedName>

                <LocalizedDescription xml:lang="EN">Description of test protocol</LocalizedDescription>

                <ConfigDescription/>

            </ProtocolPluginSpecification>

        </IFDActions>

        <SALActions/>

    </AddonSpecification>

</pre>

An entry for the SALActions is omitted in example because the definition is the same in XML both are _ProtocolPluginSpecifications_. As you may have noticed there are entries in every specification which are the same. They are discussed following and after that the elements which are not unique for a specification are clarified.

|@<ClassName>@|States the name of the class which implements the the interface specific for the action. The field is required in an valid description.|

|@<LoadOnStartup>@|States whether the add-on shall be initialized on start of the core application. The element is not required and defaults to *false* if it is not given. |

|@<LocalizedName>@|States the name of the action. The elements is optional and may appear several times for different languages.|

|@<LocalizedDescription>@|Here you may provide an optional description of what the action does. The number of this element is not limited so several languages can be supported.|

|@<ConfigDescription>@|Description of the configuration options which are changeable by the user. The element is required but it may be empty. A detail discussion about this element is in an extra section [[Add-on System#Types available in the configuration|here]].|

*Application Plugin specific elements*

|@<Parameter>@||

|@<ResourceName>@|Name of the resource where the action shall be available. The default address of the HTTP Binding is http://localhost:24727/ the resourece name needs to be relativ to this address. E.g. the integrated status add-on is available unter http://localhost:24727/getStatus.|

|@<Body>@||

|@<Attachment>@||

*Application Extension specific elements*

|@<ID>@|A unique ID for the action which is used to query the add-on in the registry. The element is required.|

*Protocol plugin specific elements*

Both, SAL and IFD plugin, are represented by an protocol plugin.

|@<URI>@|An unique uri which represents the plugin. The selection of the protocol is performed by the evaluation of this element. The element is required.|

h3. Types available in the configuration

The _ConfigDescription_ element used in the actions and in the general description of the add-on represent always configuration options which are changeable by the user. Configuration entries which are not connected with a user decision should be placed into a separate configuration. This means every entry in the _ConfigDescription_ has an representation as an UI element so the support of an entry type depends on the UI implementation. The Swing implementation implements all options the other GUI implementations are currently not complete.

_ConfigDescription_ elements may contain the following entry types: EnumEntry, EnumListEntry, FileEntry, FileListEntry, ScalarEntry and ScalarListEntry. They are mapped to the following UI elements:

|EnumEntry|The localized name is displayed as label (fallback key name) and the values are represented as checkboxes.|

|EnumListEntry|A list with fixed size containing the values. The UI element is an drop down box.|

|FileEntry|A entry which allows the user to select a file. A file selection dialog represents the entry.|

|FileListEntry|Dynamic list of _FileEntry_'s which are displayed as multiple file selection dialogs.|

|ScalarEntry|The representation depends on the type of the scalar. Availble types are BOOLEAN, BIGDECIMAL, BIGINTEGER and STRING. The BOOLEAN type is represented by a single checkbox, the BIGDECIMAL and BIGINTEGER are represented by text field with a spin button and the STRING type is displayed as single text field.|

|ScalarListEntry|The element represents a dynamic list of _ScalarEntry_'s restricted to the types BIGDECIMAL, BIGINTEGER and STRING.|

*NOTE*: Descriptions of the GUI representation is taken from the Swing GUI other GUI implementations may use other objects.

h2. Add-on Implementation

The implementation of an add-on depends always on the type of the add-on but there are also similarities between them. The specific interfaces of the add-ons are displayed following.

|=.!AppPlugin.png!|=.!IFDInterface.png!|

|=.!SALInterface.png!|=.!AppExtension.png!|

As you can see every add-on interface extends the LivecycleTrait which provides the functions @init(Context ctx)@ and @destroy()@ which mark the beginning and the end of an add-on. The @init(Context ctx)@ method is call on the initialization and provides access to core components via the @Context@ object. The accessible core components are: AddonManager, Dispatcher, EventManager, EventHandler, UserConsent, CardRecognition and some other elements for informational use.

h3. Application extension implementation details

h3. Application plugin implementation details

h3. IFD protocol implementation details

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