Project

General

Profile

Add-on System » History » Version 8

Hans-Martin Haase, 08/18/2015 07:43 AM
Fix some typos.

1 4 Hans-Martin Haase
{{toc}}
2
3 1 Dirk Petrautzki
h1. Add-on System
4 4 Hans-Martin Haase
5
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.
6
7
h2. Definition of Add-on in the Open eCard context
8
9
_Add-on_ is the generic term for a component that enhances the functionality of the Open eCard App.
10
11
_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_.
12
13
_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.
14
15
h2. Add-on Types
16
17
h3. IFD Plug-ins
18
19 8 Hans-Martin Haase
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.
20 5 Hans-Martin Haase
21 4 Hans-Martin Haase
h3. SAL Plug-ins
22
23 5 Hans-Martin Haase
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.
24
25
26 4 Hans-Martin Haase
h3. Application Plug-ins
27
28 5 Hans-Martin Haase
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,
29 6 Hans-Martin Haase
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 
30 5 Hans-Martin Haase
31
# a request-response semantic,
32
# a mapping mechanism to identify the appropriate plug-in for a request,
33
# messages comprising a body, named parameters and attachments,
34
# an error delivery mechanism, and
35
# a redirect semantic.
36
37 4 Hans-Martin Haase
h3. Application Extensions
38
39 5 Hans-Martin Haase
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.
40
41
42 4 Hans-Martin Haase
h2. Architecture of an Add-on package
43
44
h3. General architecture
45
46 7 Hans-Martin Haase
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.
47
48
p=. !{width:70%; height:70%}description.png(Add-on manifest data model in UML)!
49
50 4 Hans-Martin Haase
h3. The Add-on Manifest
51 7 Hans-Martin Haase
52
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.
53
54
<pre>
55
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
56
<AddonSpecification>
57
    <ID>123</ID>
58
    <Version>1.0-SNAPSHOT</Version>
59
    <License>WTFPL</License>
60
    <LicenseText xml:lang="EN">
61
        <![CDATA[<center><b>DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE</b>
62
        <br><br>
63
        Version 2, December 2004
64
        <br><br>
65
        Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
66
        </center>
67
        <br><br>
68
        Everyone is permitted to copy and distribute verbatim or modified
69
        copies of this license document, and changing it is allowed as long
70
        as the name is changed.
71
        <br><br>
72
        DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
73
        TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
74
        <br><br>
75
        0. You just DO WHAT THE FUCK YOU WANT TO.]]>
76
    </LicenseText>
77
    <LocalizedName xml:lang="DE">DummyAddon</LocalizedName>
78
    <LocalizedName xml:lang="EN">DummyAddon</LocalizedName>
79
    <LocalizedDescription xml:lang="EN">Dummy addon which prints some text to standard output and log file.</LocalizedDescription>
80
    <LocalizedDescription xml:lang="DE">Dummy Addon, das nur etwas Text auf der Standardausgabe ausgibt und in die Logdatei schreibt.</LocalizedDescription>
81
    <About xml:lang="EN">
82
        <![CDATA[About:
83
84
        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 
85
        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
86
        accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit met. Lorem ipsum dolor sit amet,
87
        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
88
        justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur 
89
        adipscing 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 
90
        olores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing 
91
        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
92
        rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.]]>
93
    </About>
94
    <Logo>DummyLogo.gif</Logo>
95
    <ConfigDescription>
96
        <Entries>
97
            <EnumListEntry>
98
                <Key>Animal_key</Key>
99
                <Value>Dog</Value>
100
                <Value>Cat</Value>
101
                <Value>Mouse</Value>
102
                <Value>Elephant</Value>
103
                <Value>Donkey</Value>
104
                <LocalizedName xml:lang="DE">Tier-ConfigurationEntry</LocalizedName>
105
                <LocalizedName xml:lang="EN">Animal configuration entry</LocalizedName>
106
                <LocalizedDescription xml:lang="DE">Beschreibung des Tier-ConfigurationEntry</LocalizedDescription>
107
                <LocalizedDescription xml:lang="EN">Description of the animal configuration entry</LocalizedDescription>
108
            </EnumListEntry>
109
            <EnumEntry>
110
                <Key>Kitchen_key</Key>
111
                <Value>Spoon</Value>
112
                <Value>Fork</Value>
113
                <Value>Knife</Value>
114
                <Value>Cup</Value>
115
                <Value>Mug</Value>
116
                <LocalizedName xml:lang="DE">Küchen-ConfigurationEntry</LocalizedName>
117
                <LocalizedName xml:lang="EN">Kitchen configuration entry</LocalizedName>
118
                <LocalizedDescription xml:lang="DE">Beschreibung des Küchen-ConfigurationEntry</LocalizedDescription>
119
                <LocalizedDescription xml:lang="EN">Description of the Kitchen configuation entry</LocalizedDescription>
120
            </EnumEntry>
121
        </Entries>
122
    </ConfigDescription>
123
    [...]
124
</AddonSpecification>
125
</pre>
126
127
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. 
128
129
|@<ID>@                |A unique identifier for the add-on package.                                                                                                  |
130
|@<Version>@           |The version number of the add-on. This number is used to select an add-on in case there are several versions available.                      |
131
|@<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.                                   |
132
|@<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.                                                                                                                                                         |
133 8 Hans-Martin Haase
|@<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/>@. |
134 7 Hans-Martin Haase
135
The optional elements of this first section are @<LicenseText>@, @<LocalizedName>@, @<LocalizedDescription>@ and @<About>@.
136
137 8 Hans-Martin Haase
|@<About>@|Localized string containing the typical information state in an about dialog. The elements may appear several times for different languages.|
138 7 Hans-Martin Haase
|@<LicenseText>@|Localized string containing the license text of the add-on. The element may appear several times for different languages.|
139
|@<LocalizedDescription>@|Localized string containing a description of the add-on. The element may appear several times for different languages.|
140
|@<LocalizedName>@|Localized string containing the name of the add-on. The element may appear several times for different languages.|
141
142
*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.
143
&nbsp;
144
&nbsp;
145
&nbsp;
146 8 Hans-Martin Haase
Now we have the general part of the add-on so let's go on with the second part. The second part starts with the tag @<ApplicationActions>@ this elements contains all actions available in the add-on package. The complete structure of this second part is displayed below.
147 7 Hans-Martin Haase
<pre>
148
    <AddonSpecification>
149
        [...]
150
        <ApplicationActions>
151
            <AppExtensionSpecification>
152
                <ID>123</ID>
153
                <ClassName>org.openecard.addon.openecarddummyaddon.DummyAddonStep</ClassName>
154
                <LoadOnStartup>true</LoadOnStartup>
155
                <LocalizedName xml:lang="DE">Test-ExtensionAction</LocalizedName>
156
                <LocalizedName xml:lang="EN">Test extension action</LocalizedName>
157
                <LocalizedDescription xml:lang="DE">Testbeschreibung</LocalizedDescription>
158
                <LocalizedDescription xml:lang="EN">test description</LocalizedDescription>
159
                <ConfigDescription>
160
                    <Entries>
161
                        <EnumEntry>
162
                            <Key>Foo</Key>
163
                            <Value>bar</Value>
164
                            <LocalizedName xml:lang="DE">Test-ConfigurationEntry</LocalizedName>
165
                            <LocalizedName xml:lang="EN">Test configuration entry</LocalizedName>
166
                            <LocalizedDescription xml:lang="DE">Testbeschreibung</LocalizedDescription>
167
                            <LocalizedDescription xml:lang="EN">test description</LocalizedDescription>
168
                        </EnumEntry>
169
                        <FileEntry>
170
                            <Key>FileEntry1</Key>
171
                            <RequiredBeforeAction>false</RequiredBeforeAction>
172
                            <FileType>jpg;mp4;mp3;p12</FileType>
173
                            <LocalizedName xml:lang="EN">File Entry</LocalizedName>
174
                            <LocalizedDescription xml:lang="EN">Test file entry description</LocalizedDescription>
175
                        </FileEntry>
176
                        <FileListEntry>
177
                            <Key>FileListEntry1</Key>
178
                            <RequiredBeforeAction>false</RequiredBeforeAction>
179
                            <FileType>jpg;mp4;mp3;p12</FileType>
180
                            <LocalizedName xml:lang="EN">File list Entry</LocalizedName>
181
                            <LocalizedDescription xml:lang="EN">Test file list entry description</LocalizedDescription>
182
                        </FileListEntry>
183
                        <ScalarEntry>
184
                            <Key>ScalarEntryBool</Key>
185
                            <Type>BOOLEAN</Type>
186
                            <LocalizedName xml:lang="EN">Scalar Bool</LocalizedName>
187
                            <LocalizedDescription xml:lang="EN">Scalar Bool description</LocalizedDescription>
188
                        </ScalarEntry>
189
                        <ScalarEntry>
190
                            <Key>ScalarEntryString</Key>
191
                            <Type>STRING</Type>
192
                            <LocalizedName xml:lang="EN">Scalar String</LocalizedName>
193
                            <LocalizedDescription xml:lang="EN">Scalar String description</LocalizedDescription>
194
                        </ScalarEntry>
195
                            <ScalarEntry>
196
                            <Key>ScalarEntryBigdecimal</Key>
197
                            <Type>BIGDECIMAL</Type>
198
                            <LocalizedName xml:lang="EN">Scalar BigDecimal</LocalizedName>
199
                            <LocalizedDescription xml:lang="EN">Scalar BigDecimal description</LocalizedDescription>
200
                        </ScalarEntry>
201
                        <ScalarEntry>
202
                            <Key>ScalarEntryBigInteger</Key>
203
                            <Type>BIGINTEGER</Type>
204
                            <LocalizedName xml:lang="EN">ScalarBigInteger</LocalizedName>
205
                            <LocalizedDescription xml:lang="EN">Scalar BigInteger description</LocalizedDescription>
206
                        </ScalarEntry>
207
                        <ScalarListEntry>
208
                            <Key>ScalarListEntryBigInteger</Key>
209
                            <Type>BIGINTEGER</Type>
210
                            <LocalizedName xml:lang="EN">ScalarListBigInteger</LocalizedName>
211
                            <LocalizedDescription xml:lang="EN">Scalar List BigInteger description</LocalizedDescription>
212
                        </ScalarListEntry>
213
                        <ScalarListEntry>
214
                            <Key>ScalarListEntryBigDecimalr</Key>
215
                            <Type>BIGDECIMAL</Type>
216
                            <LocalizedName xml:lang="EN">ScalarListBigDecimal</LocalizedName>
217
                            <LocalizedDescription xml:lang="EN">Scalar List BigDecimal description</LocalizedDescription>
218
                        </ScalarListEntry>
219
                        <ScalarListEntry>
220
                            <Key>ScalarListEntryString</Key>
221
                            <Type>STRING</Type>
222
                            <LocalizedName xml:lang="EN">ScalarListStringl</LocalizedName>
223
                            <LocalizedDescription xml:lang="EN">Scalar List String description</LocalizedDescription>
224
                        </ScalarListEntry>
225
                    </Entries>
226
                </ConfigDescription>
227
            </AppExtensionSpecification>
228
        </ApplicationActions>
229
    </AddonSpecification>
230
</pre>
231
232
233
234
235
236
237
238
239
240 4 Hans-Martin Haase
241
h3. Types available in the configuration
242
243
h3. Configuration of an Add-on in the client
244
245
h2. Add-on Implementation
246 5 Hans-Martin Haase
247
h3. IFD protocol implementation details
248
249 1 Dirk Petrautzki
250
This section describes the add-on system from the perspective of a developer.
251
The implementation of the add-on system is located in the maven module with the group Id *org.openecard* and the artifact Id *addon*.
252
All classes are in a sub namespace of *org.openecard.addon*. The module is divided into the following five packages:
253
* *org.openecard.addon*
254
In this package are the main classes of the add-on system, for example the AddonManager or the different AddonRegistries.
255
* *org.openecard.addon.bind*
256
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.
257
* *org.openecard.addon.ifd*
258
In here are the classes that specify the interface for an IFD protocol and the factory to instantiate such a protocol.
259
* *org.openecard.addon.manifest*
260
This package accumulates all classes needed to convert (automatically) between the XML represantation of the add-on description and it's java object pendants.
261
* *org.openecard.addon.sal*
262
In here are the classes that specify the interface for an SAL protocol and the factory to instantiate such a protocol.
263
264
h1. Types of add-ons
265
266 2 Dirk Petrautzki
In the context of Open eCard App, the terms add-on, plug-in and extension are defined as follows.
267
268
Add-on is the generic term for a component that enhances the functionality of the Open eCard App.
269
270
Extensions are independent from the context. Moreover, they are included directly into
271
the user interface and can be executed by the user. For instance, an add-on that provides a
272
PIN change functionality for smart cards is classified as an extension.
273
274
Plug-ins depend on the context in which the user uses the application. Performing
275
an authentication to a service using a particular smart card, for instance, requires a plug-in
276
which is capable of providing such functionality. Subsequently, plug-ins require a communication
277
with bindings to interact with external applications and services. Furthermore,
278
we distinguish between IFD, SAL, and application plug-ins.
279
280 1 Dirk Petrautzki
h1. Add-on development
281
282
This section describes the steps to take when developing an add-on.
283
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.
284
An example file for a PIN Management addon could look like this:
285
<pre>
286
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
287
<AddonBundleDescription>
288
	<ID>PIN-Plugin</ID>
289
	<Version>1.0</Version>
290
	<About />
291
	<License />
292
	<LocalizedName xml:lang="DE">PIN Verwaltung</LocalizedName>
293
	<LocalizedDescription xml:lang="DE">Verwaltung von PIN/ PUK und gegebenenfalls anderen Geheimnissen der Chipkarte.
294
	</LocalizedDescription>
295
	<LocalizedName xml:lang="EN">PIN Management</LocalizedName>
296
	<LocalizedDescription xml:lang="EN">Management of PIN/ PUK and possibly other secrets of the smart-card.</LocalizedDescription>
297
	<Logo>images/logo.png</Logo>
298
	<ConfigDescription />
299
	<BindingActions />
300
	<ApplicationActions />
301
	<IFDActions />
302
	<SALActions />
303
</AddonBundleDescription>
304
</pre>
305
As can be seen, some fields can be localized. That fields are: *LocalizedName*, *LocalizedDescription* and *About*
306
The next step is to think about what actions should be offerd by the add-on and of what type these actions are.
307
For the PIN management example there are two actions. An action to change a PIN and a second action to unblock a PIN.
308 2 Dirk Petrautzki
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.
309
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.
310
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:
311
<pre>
312
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
313
<AddonBundleDescription>
314
	<ID>PIN-Plugin</ID>
315
	<Version>1.0</Version>
316
	<About />
317
	<License />
318
	<LocalizedName xml:lang="DE">PIN Verwaltung</LocalizedName>
319
	<LocalizedDescription xml:lang="DE">Verwaltung von PIN/ PUK und gegebenenfalls anderen Geheimnissen der Chipkarte.
320
	</LocalizedDescription>
321
	<LocalizedName xml:lang="EN">PIN Management</LocalizedName>
322
	<LocalizedDescription xml:lang="EN">Management of PIN/ PUK and possibly other secrets of the smart-card.</LocalizedDescription>
323
	<Logo>images/pin-management.png</Logo>
324
	<ConfigDescription />
325
	<BindingActions />
326
	<ApplicationActions>
327
		<AppExtensionActionDescription>
328
			<ID>ChangePINAction</ID>
329
			<ClassName>org.openecard.plugins.pinplugin.ChangePINAction</ClassName>
330
			<LocalizedName xml:lang="DE">PIN ändern</LocalizedName>
331
			<LocalizedDescription xml:lang="DE">Mit dieser Aktion können Sie ihre PIN ändern.</LocalizedDescription>
332
			<LocalizedName xml:lang="EN">Change PIN</LocalizedName>
333
			<LocalizedDescription xml:lang="EN">With this action you can change your PIN.</LocalizedDescription>
334
			<ConfigDescription />
335
		</AppExtensionActionDescription>
336
		<AppExtensionActionDescription>
337
			<ID>UnblockPINAction</ID>
338
			<ClassName>org.openecard.plugins.pinplugin.UnblockPINAction</ClassName>
339
			<LocalizedName xml:lang="DE">PIN entsperren</LocalizedName>
340
			<LocalizedDescription xml:lang="DE">Mit dieser Aktion können Sie ihre PIN entsperren.</LocalizedDescription>
341
			<LocalizedName xml:lang="EN">Unblock PIN</LocalizedName>
342
			<LocalizedDescription xml:lang="EN">With this action you can unblock your PIN.</LocalizedDescription>
343
			<ConfigDescription />
344
		</AppExtensionActionDescription>
345
	</ApplicationActions>
346
	<IFDActions />
347
	<SALActions />
348
</AddonBundleDescription>
349
</pre>
350 3 Dirk Petrautzki
351
For the actual implementation part of the add-on, the following has to be considered.
352
The actions need to implement the AppExtensionAction interface, which itself extends the FactoryBaseType interface. 
353
Altogether, three functions are to be implemented:
354
* void execute();
355
the actual logic of the action, in this case the PIN change, will take place here
356
* void init(Context context) throws FactoryInitializationException;
357
initialization of the action; the given Context allows access to components of the Open eCard App like UserConsent or Dispatcher
358
* void destroy();
359
closing resources and further cleanup.