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


    123
    1.0-SNAPSHOT
    WTFPL
    
        DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
        


        Version 2, December 2004
        


        Copyright (C) 2004 Sam Hocevar 
        
        


        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.
        


        DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
        TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
        


        0. You just DO WHAT THE FUCK YOU WANT TO.]]>
    
    DummyAddon
    DummyAddon
    Dummy addon which prints some text to standard output and log file.
    Dummy Addon, das nur etwas Text auf der Standardausgabe ausgibt und in die Logdatei schreibt.
    
        
    
    DummyLogo.gif
    
        
            
                Animal_key
                Dog
                Cat
                Mouse
                Elephant
                Donkey
                Tier-ConfigurationEntry
                Animal configuration entry
                Beschreibung des Tier-ConfigurationEntry
                Description of the animal configuration entry
            
            
                Kitchen_key
                Spoon
                Fork
                Knife
                Cup
                Mug
                Küchen-ConfigurationEntry
                Kitchen configuration entry
                Beschreibung des Küchen-ConfigurationEntry
                Description of the Kitchen configuation entry
            
        
    
    [...]
As you can see the manifest starts with the @@ tag which covers the complete description. Every add-on requires at least the elements @@, @@, @@, @@ and a @@ which are explained below. |@@ |A unique identifier for the add-on package. | |@@ |The version number of the add-on. This number is used to select an add-on in case there are several versions available. | |@@ |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 @@ field. | |@@ |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. | |@@ |The element is used to state configuration entries which are used by all parts of the addon. For complete description of the @@ see the next section. If there are no such configuration entries the element may be set to empty witht the element tag @@. 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 @@, @@, @@ and @@. |@@ |Localized string containing the typical information state in an about dialog. The elements may appear several times for different languages. | |@@ |Localized string containing the license text of the add-on. The element may appear several times for different languages. | |@@ |Localized string containing a description of the add-on. The element may appear several times for different languages. | |@@ |Localized string containing the name of the add-on. The element may appear several times for different languages. | *Note:* The elements @@ and @@ 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 @@, @@, @@ and @@. * *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. 
    
        [...]
        
            
                package.path.to.my.class
                true
                Test class
                Test descriptions
                /test
                
                
                    Foo
                    Bar
                
                
                    text/html
                    test]]>
                
                
                    application/octet-stream
                    signature.asc
                
            
        
        
            
                123
                org.openecard.addon.openecarddummyaddon.DummyAddonStep
                true
                Test-ExtensionAction
                Test extension action
                Testbeschreibung
                test description
                
                    
                        
                            Foo
                            bar
                            Test-ConfigurationEntry
                            Test configuration entry
                            Testbeschreibung
                            test description
                        
                    
                
            
        
        
            
                urn:uri:1.2.3
                package.path.to.protocol.class
                false
                Test Protocol
                Description of test protocol
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. |@@|States the name of the class which implements the the interface specific for the action. The field is required in an valid description.| |@@|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. | |@@|States the name of the action. The elements is optional and may appear several times for different languages.| |@@|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.| |@@|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* |@@|| |@@|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.| |@@|| |@@|| *Application Extension specific elements* |@@|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. |@@|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: 


	PIN-Plugin
	1.0
	
	
	PIN Verwaltung
	Verwaltung von PIN/ PUK und gegebenenfalls anderen Geheimnissen der Chipkarte.
	
	PIN Management
	Management of PIN/ PUK and possibly other secrets of the smart-card.
	images/logo.png
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: 


	PIN-Plugin
	1.0
	
	
	PIN Verwaltung
	Verwaltung von PIN/ PUK und gegebenenfalls anderen Geheimnissen der Chipkarte.
	
	PIN Management
	Management of PIN/ PUK and possibly other secrets of the smart-card.
	images/pin-management.png
	
	
	
		
			ChangePINAction
			org.openecard.plugins.pinplugin.ChangePINAction
			PIN ändern
			Mit dieser Aktion können Sie ihre PIN ändern.
			Change PIN
			With this action you can change your PIN.
			
		
		
			UnblockPINAction
			org.openecard.plugins.pinplugin.UnblockPINAction
			PIN entsperren
			Mit dieser Aktion können Sie ihre PIN entsperren.
			Unblock PIN
			With this action you can unblock your PIN.
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.