Open eCard

{{toc}}

h1. Add-on System

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.

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. 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 the example because the definition is the same as for the IFDActions both contain _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 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>@   |This element is just specified and not implemented yet.|

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

|@<Body>@        |This element is just specified and not implemented yet.|

|@<Attachment>@  |This element is just specified and not implemented yet.|

 

*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. Available 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 explained in the following sections in this section we provide information about the similarities. Every add-on specific interface extends the LifecycleTrait interface which which provides the functions @init(Context ctx)@ and @destroy()@ which mark the beginning and the end of an add-on in their life cycle.. 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, AddonProperties, Dispatcher, EventManager, EventHandler, UserConsent, CardRecognition and some other elements for informational use.

|AddonManager   |Provides access to the add-on registries and other add-ons.                                                                                             |

|AddonProperies |Provides access to the changeable configuration of the add-on.                                                                                          |

|Dispatcher     |Provides access to credentials via SAL and IFD commands.                                                                                                |

|EventManager   |Allows to register _EventCallbacks_ this enables an add-on e.g. to react to the insertion of a card.                                                    |

|EventHandler   |Allows to issue own signals which may be interpreted by other components or add-ons. For instance an add-on which is able to identify a card which is not know by the core and sends a card recognized signal.                                                                                                                 |

|CardRecognition|Provides access to CardInfo objects and card images.                                                                                                    |

|UserConsent    |Provides access to the UI. With the UserConsent you are able to just display simple information dialogs or also complex step oriented user interfaces.  |

h3. Application extension implementation details

p=. !AppExtension.png!

The figure shows the _AppExtensionAction_ interface which have to be implements by in case of an application extension. The implementing party has to implement the @init(Context ctx)@, @destroy()@ methods which are inherited from the LifecycleTrait and @execute()@ method which comes directly from the _AppExtensionAction_. The extension is included directly into the user interface so the user is able to start it directly from there because the extension does not have any context and is independent it needs to be triggered manually. The execution in the GUI triggers the @execute()@ method which does not have parameters or a return value which means it cannot be used with a binding.

h3. Application plugin implementation details

p=. !AppPlugin.png!

As you can see in the figure the _AppPluginAction_ interfaces _execute_ method takes now three parameters a _Body_ which is represented by a Node which has the advantage that it might be instead of a XML or HTML document also just a string or a number. Furthermore _Parameters_ are given which contain the query parameters of the request sent to the add-on. The last parameter _Attachment_ may contain a binary file or something like that which shall be processed by the add-on. In return to that input the _execute_ method has to issue a _BindingResult_which is able to cover the same object so they are contained in the response which is issued by the corresponding binding but there is more in this object which needs to be specified. The following picture indicates what the others are.

p=. !{width: 20%;height: 10%}BindingResult.png!

The previously stated elements _Attachment_, _Body_ and _Parameters_ are optional but the _BindingResultCode_ is required and dependent on the code also the _AuxResultData_ so if the result code is _REDIRECT_ the _AuxResultData_ has to contain the location with the redirect destination. The _ResultMessage_ is also optional but shall be used in case the response is an error response which is directly displayed in the browser. So the user may get an impression what's wrong and correct the input or get in touch with some kind of support.

h3. IFD protocol implementation details

The _IFDProtocol_ interface defines functions for IFD protocols. The _establish()_ method executes the protocol and is triggered by a @EstablishChannel@ IFD API call which is guided to the responsible protocol implementation which takes the request containing a @SlotHandle@ to address a specific card and @AuthenticationProtocolData@ which may be required for the channel establishment. Furthermore the methods _applySM(byte[] commandAPDU)_ and _removeSM(byte[] responseAPDU)_ have to be implemented. They are used to add and remove Secure Messaging to the communication between the card and the terminal.

p=. !IFDInterface.png!

h3. SAL protocol implementation details

As depicted in the picture below the _SALProtocol_ interface is probably the most complex available one in the add-on context. The interface covers also the LifecyleTreat methods and also the @applySM(byte[] commandAPDU)@ and @removeSM(byte[] responseAPDU)@ which are known from the _IFDProtocol_ interface. In addition the cryptographic and differential identity functions have to be implemented the functions are:

 

|cardApplicationStartSession|Starts a session with a specific card.                                     |

|cardApplicationEndSession  |Ends a session with a specific card.                                       |

|encipher                   |Enciphers the data contained in the parameter.                             |

|decipher                   |Deciphers the data contained in the parameter.                             |

|getRandom                  |Generates a random number according to the specifications in the parameter.|

|hash                       |Creates a hash from the given data.                                        |

|sign                       |Signs the given data.                                                      |

|verifySignature            |Verifies the given signature.                                              |

|verifyCertificate          |Verifies the given certificate.                                            |

|didCreate                  |Creates a new differential identity.                                       |

|didUpdate                  |Updates an existing differential identity.                                 |

|didDelete                  |Deletes an existing differential identity.                                 |

|didAuthenticate            |Authenticates a differential identity.                                     |

For detailed information about the functions see TR-03112 especially part four and seven.

 

Now there just the methods _getInternalData_, _isFinished_, _hasNextStep_ and_needsSM_ left. They are probably self explaining if not take a look into the class @SALProtocolBaseImpl@ which is an abstract class providing base functionality and provides an easy way to implement step based protocols. The @ProtocolStep@ interface is used for this purpose.

p=. !SALInterface.png!