Add-on System » History » Revision 11
Revision 10 (Hans-Martin Haase, 08/18/2015 04:17 PM) → Revision 11/12 (Hans-Martin Haase, 08/19/2015 11:49 AM)
{{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. 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 the example because the definition is the same as for the IFDActions in XML both contain 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 |@<ClassName>@|States the name of the class which implements the the interface specific for the action. The field is required in an valid description. | description.|
|@<LoadOnStartup>@ |States |@<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 |@<LocalizedName>@|States the name of the action. The elements is optional and may appear several times for different languages. | 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. | supported.|
|@<ConfigDescription>@ |Description |@<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]]. | configuration|here]].|
*Application Plugin specific elements*
|@<Parameter>@ || |@<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>@| | |@<Body>@||
|@<Attachment>@ || |@<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 |EnumEntry|The localized name is displayed as label (fallback key name) and the values are represented as checkboxes. | checkboxes.|
|EnumListEntry |A |EnumListEntry|A list with fixed size containing the values. The UI element is an drop down box. | box.|
|FileEntry |A |FileEntry|A entry which allows the user to select a file. A file selection dialog represents the entry. | entry.|
|FileListEntry |Dynamic |FileListEntry|Dynamic list of _FileEntry_'s which are displayed as multiple file selection dialogs. | dialogs.|
|ScalarEntry |The |ScalarEntry|The representation depends on the type of the scalar. Available 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. | field.|
|ScalarListEntry|The element represents a dynamic list of _ScalarEntry_'s restricted to the types BIGDECIMAL, BIGINTEGER and STRING. | 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 displayed following.
|=.!AppPlugin.png!|=.!IFDInterface.png!|
|=.!SALInterface.png!|=.!AppExtension.png!|
As you can see every add-on specific interface extends the LifecycleTrait interface LivecycleTrait 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.. 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, AddonProperties, Dispatcher, EventManager, EventHandler, UserConsent, CardRecognition and some other elements for informational use.
|AddonManager |Provides access to 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 registries 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 other add-ons. | the artifact Id *addon*.
|AddonProperies |Provides access to the changeable configuration All classes are in a sub namespace of *org.openecard.addon*. The module is divided into the add-on. | following five packages:
|Dispatcher |Provides access to credentials via SAL and IFD commands. | * *org.openecard.addon*
|EventManager |Allows to register _EventCallbacks_ In this enables an package are the main classes of the add-on e.g. to react to system, for example the insertion of a card. | AddonManager or the different AddonRegistries.
|EventHandler |Allows to issue own signals which may be interpreted by other components or add-ons. For instance * *org.openecard.addon.bind*
This package includes all classes representing the interface between an add-on which addon and a specific binding. That is able to identify say, here are the classes needed to convert a card specific request, for example a HTTP request that arrives via the localhost binding, into a generic request, which is not know by independent from binding and vice versa for the core response.
* *org.openecard.addon.ifd*
In here are the classes that specify the interface for an IFD protocol and sends the factory to instantiate such a card recognized signal. | protocol.
|CardRecognition|Provides access * *org.openecard.addon.manifest*
This package accumulates all classes needed to CardInfo objects convert (automatically) between the XML represantation of the add-on description and card images. | it's java object pendants.
|UserConsent |Provides access to * *org.openecard.addon.sal*
In here are the UI. With classes that specify the UserConsent you are able interface for an SAL protocol and the factory to just display simple information dialogs or also complex step oriented user interfaces. | instantiate such a protocol.
h3. Application h1. Types of add-ons
In the context of Open eCard App, the terms add-on, plug-in and extension implementation details are defined as follows.
p=. !AppExtension.png!
The figure shows Add-on is the _AppExtensionAction_ interface which have to be implements by in case generic term for a component that enhances the functionality of an application extension. The implementing party has to implement the @init(Context ctx)@, @destroy()@ methods which Open eCard App.
Extensions are inherited independent from the LifecycleTrait and @execute()@ method which comes directly from the _AppExtensionAction_. The extension is context. Moreover, they are included directly into
the user interface so and can be executed by the user user. For instance, an add-on that provides a
PIN change functionality for smart cards is able to start it directly from there because classified as an extension.
Plug-ins depend on the extension does not have any context and is independent it needs to be triggered manually. The execution in which the GUI triggers user uses the @execute()@ method which does not have parameters or application. Performing
an authentication to a return value which means it cannot be used with service using 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 particular smart card, for instance, requires a _Body_ plug-in
which is represented by capable of providing such functionality. Subsequently, plug-ins require a Node which has 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 advantage that it might be instead of steps to take when developing an add-on.
As first step a new XML or HTML document also just a string or a number. Furthermore _Parameters_ are given which contain file called *Addon.xml* in the query parameters *META-INF* directory of the request sent to the add-on. The last parameter _Attachment_ may contain a binary file or something like that which shall project should be processed by created and the add-on. In return to fields that input describe the _execute_ method has to issue a _BindingResult_which is able to cover general part of 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 add-ons can already be specified. The following picture indicates what the others are.
p=. !{width: 20%;height: 10%}BindingResult.png!
The previously stated elements _Attachment_, _Body_ 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 _Parameters_ are optional but possibly other secrets of the _BindingResultCode_ is required 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 dependent on the code also the _AuxResultData_ so if the result code *About*
The next step is _REDIRECT_ the _AuxResultData_ has to contain the location with the redirect destination. The _ResultMessage_ is also optional but shall think about what actions should be used in case offerd by the response is an error response which is directly displayed in the browser. So the user may get an impression what's wrong add-on 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 what type these actions are.
For the protocol PIN management example there are two actions. An action to change a PIN and is triggered by a @EstablishChannel@ IFD API call which is guided second action to unblock a PIN.
These actions are not of type *ProtocolPlugin* nor *AppPluginAction*, but of type *AppExtensionAction*, as they expand the responsible protocol implementation which takes function of the request containing Open eCard App independent from a @SlotHandle@ context.
This means two classes implementing the *AppExtensionAction* interface need to address a specific card and @AuthenticationProtocolData@ which may be required for added to the channel establishment. Furthermore project and the methods _applySM(byte[] commandAPDU)_ and _removeSM(byte[] responseAPDU)_ have two AppExtensionActionDescription that belong to them need to be implemented. They added to the XML description.
Assume we are used to add working in the org.openecard.plugins.pinplugin namespace and remove Secure Messaging to the communication between two actions are called ChangePINAction and UnblockPINAction, the card 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 terminal. 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>
p=. !IFDInterface.png!
h3. SAL protocol For the actual implementation details
As depicted in part of the picture below add-on, the _SALProtocol_ interface is probably the most complex available one in the add-on context. following has to be considered.
The interface covers also actions need to implement the LifecyleTreat methods and also the @applySM(byte[] commandAPDU)@ and @removeSM(byte[] responseAPDU)@ AppExtensionAction interface, which are known from itself extends the _IFDProtocol_ FactoryBaseType interface. In addition the cryptographic and differential identity
Altogether, three functions have are to be implemented the functions are: implemented:
|cardApplicationStartSession|Starts a session with a specific card. | * void execute();
|cardApplicationEndSession |Ends a session with a specific card. |
|encipher |Enciphers the data contained in actual logic of the parameter. |
|decipher |Deciphers the data contained action, in this case the parameter. | PIN change, will take place here
|getRandom |Generates a random number according to the specifications in the parameter.| * void init(Context context) throws FactoryInitializationException;
|hash |Creates a hash from initialization of the given data. |
|sign |Signs action; the given data. |
|verifySignature |Verifies Context allows access to components of the given signature. | Open eCard App like UserConsent or Dispatcher
|verifyCertificate |Verifies the given certificate. | * void destroy();
|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 closing resources 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!
further cleanup.