• Table of contents
• Add-on System
  • Definition of Add-on in the Open eCard context
  • Add-on Types
    • IFD Plug-ins
    • SAL Plug-ins
    • Application Plug-ins
    • Application Extensions
  • Architecture of an Add-on package
    • General architecture
    • The Add-on Manifest
    • Types available in the configuration
  • Add-on Implementation
    • Application extension implementation details
    • Application plugin implementation details
    • IFD protocol implementation details
    • SAL protocol implementation details

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.

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

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

1. a request-response semantic,
2. a mapping mechanism to identify the appropriate plug-in for a request,
3. messages comprising a body, named parameters and attachments,
4. an error delivery mechanism, and
5. 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¶

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.

 

 

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.

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

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

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

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

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.

 

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.

Application extension implementation details¶

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.

Application plugin implementation details¶

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.

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.

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.

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.