-
Notifications
You must be signed in to change notification settings - Fork 8
/
service.provisioning.html
5321 lines (5292 loc) · 659 KB
/
service.provisioning.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>110 Initial Provisioning Specification - OSGi Compendium 7</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
<link rel="home" href="toc.html" title="OSGi Compendium" />
<link rel="up" href="toc.html" title="OSGi Compendium" />
<link rel="prev" href="service.io.html" title="109 IO Connector Service Specification" />
<link rel="next" href="service.upnp.html" title="111 Device Service Specification for UPnP™ Technology" />
<meta name="Section-title" content="110 Initial Provisioning Specification" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="shortcut icon" href="images/favicon.png" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="css/custom.css" />
<link rel="stylesheet" type="text/css" href="css/github.css" />
<link rel="stylesheet" type="text/css" href="//fonts.googleapis.com/css?family=Ubuntu:regular,bold&subset=Latin" /><script type="text/javascript" src="js/highlight.pack.js"></script><script type="text/javascript" src="js/main.js"></script></head>
<body>
<div id="fullbody">
<div id="header">
<div class="menu-top-container"></div>
<div id="shadow-block"><a class="logo" href="index.html"><img src="images/logo.svg" alt="OSGi Alliance Documentation" /><h1>OSGi Compendium Release 7</h1></a></div>
</div>
<div id="mobile-menu-icon">⋮</div>
<div id="column-two">
<div id="content">
<div id="scrollable">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<td width="20%" align="left"><a accesskey="p" href="service.io.html">Prev</a>
</td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="service.upnp.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter">
<div xmlns="" class="titlepage">
<div>
<div>
<h1 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="service.provisioning"></a><span xmlns="" class="number">110</span> Initial Provisioning Specification
</h1>
</div>
<div>
<p xmlns="http://www.w3.org/1999/xhtml" class="releaseinfo"><a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning" title="110.11 org.osgi.service.provisioning">Version 1.2</a></p>
</div>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e31950"></a><span xmlns="" class="number">110.1</span> Introduction
</h2>
</div>
</div>
</div>
<p>To allow freedom regarding the choice of management protocol, the
OSGi Specifications assumes an architecture to remotely manage a OSGi
framework with a Management Agent. The Management Agent is implemented
with a Management Bundle that can communicate with an unspecified
management protocol.
</p>
<p>This specification defines how the Management Agent can make its way
to the OSGi framework, and gives a structured view of the problems and
their corresponding resolution methods.
</p>
<p>The purpose of this specification is to enable the management of a
OSGi framework by an Operator, and (optionally) to hand over the
management of the OSGi framework later to another Operator. This approach
is in accordance with the OSGi remote management reference
architecture.
</p>
<p>This bootstrapping process requires the installation of a Management
Agent, with appropriate configuration data, in the OSGi framework.
</p>
<p>This specification consists of a prologue, in which the principles
of the Initial Provisioning are outlined, and a number of mappings to
different mechanisms.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e31963"></a><span xmlns="" class="number">110.1.1</span> Essentials
</h3>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Policy Free</em></span> - The proposed solution must
be business model agnostic; none of the affected parties (Operators,
SPS Manufacturers, etc.) should be forced into any particular
business model.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Interoperability</em></span> - The Initial
Provisioning must permit arbitrary interoperability between
management systems and OSGi frameworks. Any compliant Remote Manager
should be able to manage any compliant OSGi framework, even in the
absence of a prior business relationship. Adhering to this
requirement allows a particular Operator to manage a variety of
makes and models of OSGi framework Servers using a single management
system of the Operator's choice. This rule also gives the consumer
the greatest choice when selecting an Operator.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Flexible</em></span> - The management process should
be as open as possible, to allow innovation and specialization while
still achieving interoperability.
</p>
</li>
</ul>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e31982"></a><span xmlns="" class="number">110.1.2</span> Entities
</h3>
</div>
</div>
</div>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="emphasis"><em>Provisioning Service</em></span> - A service
registered with the Framework that provides information about the
initial provisioning to the Management Agent.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Provisioning Dictionary</em></span> - A
<code class="code">Dictionary</code> object that is filled with information from
the ZIP files that are loaded during initial setup.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>RSH Protocol</em></span> - An OSGi specific secure
protocol based on HTTP.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>Management Agent</em></span> - A bundle that is
responsible for managing a OSGi framework under control of a Remote
Manager.
</p>
</li>
</ul>
</div>
<div class="figure"><a xmlns="" class="anchor" id="d0e32009"></a><p class="title"><strong>Figure <span xmlns="" class="number">110</span>.1 Initial Provisioning</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/110-ip-classes.png" align="middle" width="444" height="267" alt="Initial Provisioning" /></div>
</div>
</div><br class="figure-break" /></div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="i1365233"></a><span xmlns="" class="number">110.2</span> Procedure
</h2>
</div>
</div>
</div>
<p>The following procedure should be executed by an OSGi Framework
implementation that supports this Initial Provisioning
specification.
</p>
<p>When the OSGi framework is first brought under management control,
it must be provided with an initial request URL in order to be
provisioned. Either the end user or the manufacturer may provide the
initial request URL. How the initial request URL is transferred to the
Framework is not specified, but a mechanism might, for example, be a
command line parameter when the framework is started.
</p>
<p>When asked to start the Initial Provisioning, the OSGi framework
will send a request to the management system. This request is encoded in a
URL, for example:
</p><pre xmlns="" class="programlisting"><code>http://osgi.acme.com/remote-manager</code></pre><p>This URL may use any protocol that is available on the OSGi
framework Server. Many standard protocols exist, but it is also possible
to use a proprietary protocol. For example, software could be present
which can communicate with a smart card and could handle, for example,
this URL:
</p><pre xmlns="" class="programlisting"><code>smart-card://com1:0/7F20/6F38</code></pre><p>Before the request URL is executed, the OSGi framework information
is appended to the URL. This information includes at least the OSGi
framework Identifier, but may also contain proprietary information, as
long as the keys for this information do not conflict. Different URL
schemes may use different methods of appending parameters; these details
are specified in the mappings of this specification to concrete
protocols.
</p>
<p>The result of the request must be a ZIP file. (The content type
should be <code class="code">application/zip</code>). It is the responsibility of the
underlying protocol to guarantee the integrity and authenticity of this
ZIP file.
</p>
<p>This ZIP file is unpacked and its entries (except
<code class="code">bundle</code> and <code class="code">bundle-url</code> entries, described in
<a xmlns="" class="xref" href="service.provisioning.html#service.provisioning-rsh.headers" title="Table 110.2 RSH Header description">Table <span class="number">110</span>.2</a> ) are placed in a
<code class="code">Dictionary</code> object. This <code class="code">Dictionary</code> object is
called the <span class="emphasis"><em>Provisioning Dictionary</em></span>. It must be made
available from the Provisioning Service in the service registry. The names
of the entries in the ZIP file must not start with a solidus (<code class="code">'/'
\u002F</code>).
</p>
<p>The ZIP file may contain only four types of dictionary entries:
<code class="code">text</code>, <code class="code">binary</code>, <code class="code">bundle</code>, or
<code class="code">bundle-url</code>. The type of an entry can be specified in
different ways. An Initial Provisioning service must look in the following
places to find the information about an entry's (MIME) type (in the given
order):
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>The manifest header <code class="code">InitialProvisioning-Entries</code> of
the given ZIP file. This header is defined in <a xmlns="" class="xref" href="service.provisioning.html#i1442770" title="110.2.1 InitialProvisioning-Entries Manifest Header">InitialProvisioning-Entries Manifest Header</a>. If this header is present, but a given entry's
path is not named then try the next step.
</p>
</li>
<li class="listitem">
<p>The extension of the entry path name if one of
<code class="code">.txt</code>, <code class="code">.jar</code>, <code class="code">.url</code> extensions.
See <a xmlns="" class="xref" href="service.provisioning.html#service.provisioning-content.types" title="Table 110.1 Content types of provisioning ZIP file">Table <span class="number">110</span>.1 on page </a> for the mapping of types,
MIME types, and extensions.
</p>
</li>
<li class="listitem">
<p>The entry is assumed to be a binary type</p>
</li>
</ol>
</div>
<p>The types can optionally be specified as a MIME type as defined in
<a xmlns="" class="xref" href="service.provisioning.html#i1296602" title="MIME Types">[7] <em>MIME Types</em></a>. The <code class="code">text</code> and
<code class="code">bundle-url</code> entries are translated into a <code class="code">String</code>
object from an <code class="code">UTF-8</code> encoded byte array. All other entries
must be stored as a <code class="code">byte[]</code>.
</p>
<div class="table"><a xmlns="" class="anchor" id="service.provisioning-content.types"></a><p class="title"><strong>Table <span xmlns="" class="number">110</span>.1 Content types of provisioning ZIP file</strong></p>
<div class="table-contents">
<table summary="Content types of provisioning ZIP file" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; ">
<colgroup>
<col />
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Type</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">MIME Type</th>
<th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Ext</th>
<th style="border-bottom: 0.5pt solid ; ">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">text</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p><a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.MIME_STRING" title="110.11.2.6 public static final String MIME_STRING = "text/plain;charset=utf-8"">MIME_STRING</a></p>
<p><code class="code">text/plain;charset=utf-8</code></p>
</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">.txt</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>Must be represented as a String object</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">binary</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p><a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.MIME_BYTE_ARRAY" title="110.11.2.5 public static final String MIME_BYTE_ARRAY = "application/octet-stream"">MIME_BYTE_ARRAY</a></p>
<p><code class="code">application/octet-stream</code></p>
</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p>not <code class="code">txt</code>, <code class="code">.url</code>, or
<code class="code">.jar</code></p>
</td>
<td style="border-bottom: 0.5pt solid ; ">
<p>Must be represented as a byte array
(<code class="code">byte[]</code>).
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">bundle</code></td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">
<p><a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.MIME_BUNDLE" title="110.11.2.2 public static final String MIME_BUNDLE = "application/vnd.osgi.bundle"">MIME_BUNDLE</a></p>
<p><code class="code">application/vnd.osgi.bundle</code>
</p>
<p><code class="code">MIME_BUNDLE_ALT</code></p>
<p><code class="code">application/x-osgi-bundle</code></p>
</td>
<td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="code">.jar</code></td>
<td style="border-bottom: 0.5pt solid ; ">
<p>Entries must be installed using
<code class="code">BundleContext.installBundle(String, InputStream)</code>,
with the <code class="code">InputStream</code> object constructed from the
contents of the ZIP entry. The location must be the name of the
ZIP entry without leading solidus (<code class="code">'/' \u002F</code>). This
entry must not be stored in the Provisioning
Dictionary.
</p>
<p>If a bundle with this location name is
already installed in this system, then this bundle must be updated
instead of installed.
</p>
<p>The <code class="code">MIME_BUNDLE_ALT</code>
version is intended for backward compatibility, it specifies the
original MIME type for bundles before there was an official IANA
MIME type.
</p>
</td>
</tr>
<tr>
<td style="border-right: 0.5pt solid ; "><code class="code">bundle-url</code></td>
<td style="border-right: 0.5pt solid ; ">
<p><a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.MIME_BUNDLE_URL" title="110.11.2.4 public static final String MIME_BUNDLE_URL = "text/x-osgi-bundle-url"">MIME_BUNDLE_URL</a></p>
<p><code class="code">text/x-osgi-bundle-url;
charset=utf-8</code></p>
</td>
<td style="border-right: 0.5pt solid ; "><code class="code">.url</code></td>
<td style="">
<p>The content of this entry is a string coded in
<code class="code">utf-8</code>. Entries must be installed using
<code class="code">BundleContext.installBundle(String, InputStream)</code>,
with the <code class="code">InputStream</code> object created from the given
URL. The location must be the name of the ZIP entry without
leading solidus (<code class="code">'/' \u002F</code>). This entry must not be
stored in the Provisioning Dictionary.
</p>
<p>If a bundle
with this location URL is already installed in this system, then
this bundle must be updated instead of installed.
</p>
</td>
</tr>
</tbody>
</table>
</div>
</div><br class="table-break" /><p>The Provisioning Service must install (but not start) all entries in
the ZIP file that are typed with <code class="code">bundle</code> or
<code class="code">bundle-url</code>.
</p>
<p>If an entry named <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_START_BUNDLE" title="110.11.2.12 public static final String PROVISIONING_START_BUNDLE = "provisioning.start.bundle"">PROVISIONING_START_BUNDLE</a> is present in the Provisioning Dictionary, then
its content type must be text as defined in <a xmlns="" class="xref" href="service.provisioning.html#service.provisioning-content.types" title="Table 110.1 Content types of provisioning ZIP file">Table <span class="number">110</span>.1</a>. The content of this entry
must match the bundle location of a previously loaded bundle. This
designated bundle must be given <code class="code">AllPermission</code> and
started.
</p>
<p>If no <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_START_BUNDLE" title="110.11.2.12 public static final String PROVISIONING_START_BUNDLE = "provisioning.start.bundle"">PROVISIONING_START_BUNDLE</a> entry is present in the Provisioning Dictionary,
the Provisioning Dictionary should contain a reference to another ZIP file
under the <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> key. If both keys are absent, no further action
must take place.
</p>
<p>If this <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> key is present and holds a <code class="code">String</code>
object that can be mapped to a valid URL, then a new ZIP file must be
retrieved from this URL. The <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> link may be repeated multiple times in
successively loaded ZIP files.
</p>
<p>Referring to a new ZIP file with such a URL allows a manufacturer to
place a fixed reference inside the OSGi framework Server (in a file or
smart card) that will provide some platform identifying information and
then also immediately load the information from the management system. The
<a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> link may be repeated multiple times in
successively loaded ZIP files. The entry <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_UPDATE_COUNT" title="110.11.2.13 public static final String PROVISIONING_UPDATE_COUNT = "provisioning.update.count"">PROVISIONING_UPDATE_COUNT</a> must be an <code class="code">Integer</code> object that must
be incremented on every iteration.
</p>
<p>Information retrieved while loading subsequent <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> URLs may replace previous key/values in the
Provisioning Dictionary, but must not erase unrecognized key/values. For
example, if an assignment has assigned the key <code class="code">proprietary-x</code>,
with a value '3', then later assignments must not override this value,
unless the later loaded ZIP file contains an entry with that name. All
these updates to the Provisioning Dictionary must be stored persistently.
At the same time, each entry of type <code class="code">bundle</code> or
<code class="code">bundle-url</code> (see <a xmlns="" class="xref" href="service.provisioning.html#service.provisioning-content.types" title="Table 110.1 Content types of provisioning ZIP file">Table <span class="number">110</span>.1</a> ) must be installed and not
started.
</p>
<p>Once the Management Agent has been started, the Initial Provisioning
service has become operational. In this state, the Initial Provisioning
service must react when the Provisioning Dictionary is updated with a new
<a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> property. If this key is set, it should start the
cycle again. For example, if the control of a OSGi framework needs to be
transferred to another Remote Manager, the Management Agent should set the
<a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> to the location of this new Remote Manager's
Initial Provisioning ZIP file. This process is called
<span class="emphasis"><em>re-provisioning</em></span>.
</p>
<p>If errors occur during this process, the Initial Provisioning
service should try to notify the Service User of the problem.
</p>
<p>The previous description is depicted in <a xmlns="" class="xref" href="service.provisioning.html#i1302126" title="Figure 110.2 Flow chart installation Management Agent bundle">Figure <span class="number">110</span>.2</a>
as a flow chart.
</p>
<div class="figure"><a xmlns="" class="anchor" id="i1302126"></a><p class="title"><strong>Figure <span xmlns="" class="number">110</span>.2 Flow chart installation Management Agent bundle</strong></p>
<div class="figure-contents">
<div class="mediaobject" align="center"><img src="images/110-installation-flow.png" align="middle" width="443" height="302" alt="Flow chart installation Management Agent bundle" /></div>
</div>
</div><br class="figure-break" /><p>The Management Agent may require configuration data that is specific
to the OSGi framework instance. If this data is available outside the
Management Agent bundle, the merging of this data with the Management
Agent may take place in the OSGi framework. Transferring the data
separately will make it possible to simplify the implementation on the
server side, as it is not necessary to create
<span class="emphasis"><em>personalized</em></span> OSGi framework bundles. The <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_AGENT_CONFIG" title="110.11.2.7 public static final String PROVISIONING_AGENT_CONFIG = "provisioning.agent.config"">PROVISIONING_AGENT_CONFIG</a> key is reserved for this purpose, but the
Management Agent may use another key or mechanisms if so desired.
</p>
<p>The <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_SPID" title="110.11.2.11 public static final String PROVISIONING_SPID = "provisioning.spid"">PROVISIONING_SPID</a> key must contain the OSGi framework
Identifier.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="i1442770"></a><span xmlns="" class="number">110.2.1</span> InitialProvisioning-Entries Manifest Header
</h3>
</div>
</div>
</div>
<p>The <code class="code">InitialProvisioning-Entries</code> manifest header
optionally specifies the type of the entries in the ZIP file. The syntax
for this header is:
</p><pre xmlns="" class="programlisting"><code>InitialProvisioning-Entries ::= ip-entry (',' ip-entry ) *
ip-entry ::= path ( ';' parameter ) *</code></pre><p>The entry is the path name of a resource in the ZIP file. This
<code class="code">InitialProvisioning-Entries</code> header recognizes the following
attribute:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><code class="code">type</code> - Gives the type of the dictionary entry.
The type can have one of the following values: <code class="code">text</code>,
<code class="code">binary</code>, <code class="code">bundle</code>, or
<code class="code">bundle-url</code></p>
</li>
</ul>
</div>
<p>If the type parameter entry is not specified for an entry, then
the type will be inferred from the extension of the entry, as defined in
table <a xmlns="" class="xref" href="service.provisioning.html#service.provisioning-content.types" title="Table 110.1 Content types of provisioning ZIP file">Table <span class="number">110</span>.1 on page </a>.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e32373"></a><span xmlns="" class="number">110.3</span> Special Configurations
</h2>
</div>
</div>
</div>
<p>The next section shows some examples of specially configured types
of OSGi framework Servers and how they are treated with the respect to the
specifications in this document.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e32378"></a><span xmlns="" class="number">110.3.1</span> Branded OSGi framework Server
</h3>
</div>
</div>
</div>
<p>If a OSGi framework Operator is selling OSGi framework Servers
branded exclusively for use with their service, the provisioning will
most likely be performed prior to shipping the OSGi framework Server to
the User. Typically the OSGi framework is configured with the
<code class="code">Dictionary</code> entry <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> pointing at a location controlled by the
Operator.
</p>
<p>Up-to-date bundles and additional configuration data must be
loaded from that location at activation time. The OSGi framework is
probably equipped with necessary security entities, like certificates,
to enable secure downloads from the Operator's URL over open networks,
if necessary.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e32390"></a><span xmlns="" class="number">110.3.2</span> Non-connected OSGi framework
</h3>
</div>
</div>
</div>
<p>Circumstances might exist in which the OSGi framework Server has
no WAN connectivity, or prefers not to depend on it for the purposes not
covered by this specification.
</p>
<p>The non-connected case can be implemented by specifying a
<code class="code">file://</code> URL for the initial ZIP file ( <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> ). That <code class="code">file://</code> URL would name a
local file containing the response that would otherwise be received from
a remote server.
</p>
<p>The value for the Management Agent <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> found in that file will be used as input to the
load process. The <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_REFERENCE" title="110.11.2.8 public static final String PROVISIONING_REFERENCE = "provisioning.reference"">PROVISIONING_REFERENCE</a> may point to a bundle file stored either locally
or remotely. No code changes are necessary for the non-connected
scenario. The <code class="code">file://</code> URLs must be specified, and the
appropriate files must be created on the OSGi framework.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e32414"></a><span xmlns="" class="number">110.4</span> The Provisioning Service
</h2>
</div>
</div>
</div>
<p>Provisioning information is conveyed between bundles using the
Provisioning Service, as defined in the <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService" title="110.11.2 public interface ProvisioningService">ProvisioningService</a> interface. The Provisioning Dictionary is
retrieved from the <code class="code">ProvisioningService</code> object using the <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.getInformation--" title="110.11.2.16 public Dictionary<String, Object> getInformation()">getInformation()</a> method. This is a read-only
<code class="code">Dictionary</code> object, any changes to this
<code class="code">Dictionary</code> object must throw an
<code class="code">UnsupportedOperationException</code>.
</p>
<p>The Provisioning Service provides a number of methods to update the
Provisioning Dictionary.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.addInformation-Dictionary-" title="110.11.2.14 public void addInformation(Dictionary<String, ?> info)">addInformation(Dictionary)</a> - Add all key/value pairs in the given
<code class="code">Dictionary</code> object to the Provisioning Dictionary.
</p>
</li>
<li class="listitem">
<p><a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.addInformation-ZipInputStream-" title="110.11.2.15 public void addInformation(ZipInputStream zis) throws IOException">addInformation(ZipInputStream)</a> - It is also possible to add a ZIP file to the
Provisioning Service immediately. This will unpack the ZIP file and
add the entries to the Provisioning Dictionary. This method must
install the bundles contained in the ZIP file as described in <a xmlns="" class="xref" href="service.provisioning.html#i1365233" title="110.2 Procedure">Procedure</a>.
</p>
</li>
<li class="listitem">
<p><a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.setInformation-Dictionary-" title="110.11.2.17 public void setInformation(Dictionary<String, ?> info)">setInformation(Dictionary)</a> - Set a new Provisioning Dictionary. This will
remove all existing entries.
</p>
</li>
</ul>
</div>
<p>Each of these method will increment the <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_UPDATE_COUNT" title="110.11.2.13 public static final String PROVISIONING_UPDATE_COUNT = "provisioning.update.count"">PROVISIONING_UPDATE_COUNT</a> entry.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e32459"></a><span xmlns="" class="number">110.5</span> Management Agent Environment
</h2>
</div>
</div>
</div>
<p>The Management Agent should be written with great care to minimize
dependencies on other packages and services, as <span class="emphasis"><em>all</em></span>
services in OSGi are optional. Some OSGi frameworks may have other bundles
pre-installed, so it is possible that there may be exported packages and
services available. Mechanisms outside the current specification, however,
must be used to discover these packages and services before the Management
Agent is installed.
</p>
<p>The Provisioning Service must ensure that the Management Agent is
running with <code class="code">AllPermission</code>. The Management Agent should check
to see if the Permission Admin service is available, and establish the
initial permissions as soon as possible to insure the security of the
device when later bundles are installed. As the
<code class="code">PermissionAdmin</code> interfaces may not be present (it is an
optional service), the Management Agent should export the
<code class="code">PermissionAdmin</code> interfaces to ensure they can be
resolved.
</p>
<p>Once started, the Management Agent may retrieve its configuration
data from the Provisioning Service by getting the <code class="code">byte[]</code>
object that corresponds to the <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_AGENT_CONFIG" title="110.11.2.7 public static final String PROVISIONING_AGENT_CONFIG = "provisioning.agent.config"">PROVISIONING_AGENT_CONFIG</a> key in the Provisioning Dictionary. The structure
of the configuration data is implementation specific.
</p>
<p>The scope of this specification is to provide a mechanism to
transmit the raw configuration data to the Management Agent. The
Management Agent bundle may alternatively be packaged with its
configuration data in the bundle, so it may not be necessary for the
Management Agent bundle to use the Provisioning Service at all.
</p>
<p>Most likely, the Management Agent bundle will install other bundles
to provision the OSGi framework. Installing other bundles might even
involve downloading a more full featured Management Agent to replace the
initial Management Agent.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e32489"></a><span xmlns="" class="number">110.6</span> Mapping To File Scheme
</h2>
</div>
</div>
</div>
<p>The <code class="code">file:</code> scheme is the simplest and most completely
supported scheme which can be used by the Initial Provisioning
specification. It can be used to store the configuration data and
Management Agent bundle on the OSGi framework Server, and avoids any
outside communication.
</p>
<p>If the initial request URL has a <code class="code">file</code> scheme, no
parameters should be appended, because the <code class="code">file:</code> scheme does
not accept parameters.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e32505"></a><span xmlns="" class="number">110.6.1</span> Example With File Scheme
</h3>
</div>
</div>
</div>
<p>The manufacturer should prepare a ZIP file containing only one
entry named <a xmlns="" class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_START_BUNDLE" title="110.11.2.12 public static final String PROVISIONING_START_BUNDLE = "provisioning.start.bundle"">PROVISIONING_START_BUNDLE</a> that contains a location string of an entry of
type <code class="code">bundle</code> or <code class="code">bundle-url</code>. For example, the
following ZIP file demonstrates this:
</p><pre xmlns="" class="programlisting"><code>provisioning.start.bundle text agent
agent bundle C0AF0E9B2AB..</code></pre><p>The bundle may also be specified with a URL:</p><pre xmlns="" class="programlisting"><code>provisioning.start.bundle text http://acme.com/a.jar
agent bundle-url http://acme.com/a.jar</code></pre><p>Upon startup, the framework is provided with the URL with the
<code class="code">file:</code> scheme that points to this ZIP file:
</p><pre xmlns="" class="programlisting"><code>file:/opt/osgi/ma.zip</code></pre></div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e32531"></a><span xmlns="" class="number">110.7</span> Mapping To HTTP(S) Scheme
</h2>
</div>
</div>
</div>
<p>This section defines how HTTP and HTTPS URLs must be used with the
Initial Provisioning specification.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>HTTP - May be used when the data exchange takes place over
networks that are secured by other means, such as a Virtual Private
Network (VPN) or a physically isolated network. Otherwise, HTTP is not
a valid scheme because no authentication takes place.
</p>
</li>
<li class="listitem">
<p>HTTPS - May be used if the OSGi framework is equipped with
appropriate certificates.
</p>
</li>
</ul>
</div>
<p>HTTP and HTTPS share the following qualities:</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>Both are well known and widely used</p>
</li>
<li class="listitem">
<p>Numerous implementations of the protocols exist</p>
</li>
<li class="listitem">
<p>Caching of the Management Agent will be desired in many
implementations where limited bandwidth is an issue. Both HTTP and
HTTPS already contain an accepted protocol for caching.
</p>
</li>
</ul>
</div>
<p>Both HTTP and HTTPS must be used with the GET method. The response
is a ZIP file, implying that the response header <code class="code">Content-Type</code>
header must contain <code class="code">application/zip</code>.
</p>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="d0e32563"></a><span xmlns="" class="number">110.7.1</span> HTTPS Certificates
</h3>
</div>
</div>
</div>
<p>In order to use HTTPS, certificates must be in place. These
certificates, that are used to establish trust towards the Operator, may
be made available to the OSGi framework using the Provisioning Service.
The root certificate should be assigned to the Provisioning Dictionary
before the HTTPS provider is used. Additionally, the OSGi framework
should be equipped with a OSGi framework certificate that allows the
OSGi framework to properly authenticate itself towards the Operator.
This specification does not state how this certificate gets installed
into the OSGi framework.
</p>
<p>The root certificate is stored in the Provisioning Dictionary
under the key:
</p><pre xmlns="" class="programlisting"><code><a class="xref" href="service.provisioning.html#org.osgi.service.provisioning.ProvisioningService.PROVISIONING_ROOTX509" title="110.11.2.9 public static final String PROVISIONING_ROOTX509 = "provisioning.rootx509"">PROVISIONING_ROOTX509</a></code></pre><p>The Root X.509 Certificate holds certificates used to represent a
handle to a common base for establishing trust. The certificates are
typically used when authenticating a Remote Manager to the OSGi
framework. In this case, a Root X.509 certificate must be part of a
certificate chain for the Operator's certificate. The format of the
certificate is defined in <a xmlns="" class="xref" href="service.provisioning.html#i1287116" title="110.7.2 Certificate Encoding">Certificate Encoding</a>.
</p>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="i1287116"></a><span xmlns="" class="number">110.7.2</span> Certificate Encoding
</h3>
</div>
</div>
</div>
<p>Root certificates are X.509 certificates. Each individual
certificate is stored as a <code class="code">byte[]</code> object. This
<code class="code">byte[]</code> object is encoded in the default Java manner, as
follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p>The original, binary certificate data is DER encoded</p>
</li>
<li class="listitem">
<p>The DER encoded data is encoded into base64 to make it
text.
</p>
</li>
<li class="listitem">
<p>The base64 encoded data is prefixed with</p><pre xmlns="" class="programlisting"><code>-----BEGIN CERTIFICATE-----</code></pre><p>and suffixed with:</p><pre xmlns="" class="programlisting"><code>-----END CERTIFICATE-----</code></pre></li>
<li class="listitem">
<p>If a record contains more than one certificate, they are
simply appended one after the other, each with a delimiting prefix
and suffix.
</p>
</li>
</ul>
</div>
<p><a xmlns="" class="anchor" id="i1323445"></a>The decoding of such a certificate may be done
with the <code class="code">java.security.cert.CertificateFactory</code>
class:
</p><pre xmlns="" class="programlisting"><code>InputStream bis = new ByteArrayInputStream(x509);// byte[]
CertificateFactory cf =
CertificateFactory.getInstance("X.509");
Collection c = cf.generateCertificates(bis);
Iterator i = c.iterator();
while (i.hasNext()) {
Certificate cert = (Certificate)i.next();
System.out.println(cert);
} </code></pre></div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a xmlns="" class="anchor" id="i1297554"></a><span xmlns="" class="number">110.7.3</span> URL Encoding
</h3>
</div>
</div>
</div>
<p>The URL must contain the OSGi framework Identity, and may contain
more parameters. These parameters are encoded in the URL according to
the HTTP(S) URL scheme. A base URL may be set by an end user but the
Provisioning Service must add the OSGi framework Identifier.
</p>
<p>If the request URL already contains HTTP parameters (if there is a
'?' in the request), the <code class="code">service_platform_id</code> is appended to
this URL as an additional parameter. If, on the other hand, the request
URL does not contain any HTTP parameters, the
<code class="code">service_platform_id</code> will be appended to the URL after a
'?', becoming the first HTTP parameter. The following two examples show
these two variants:
</p><pre xmlns="" class="programlisting"><code>http://server.operator.com/service-x? «
foo=bar&service_platform_id=VIN:123456789
http://server.operator.com/service-x? «
service_platform_id=VIN:123456789</code></pre><p>Proper URL encoding must be applied when the URL contains
characters that are not allowed. See <a xmlns="" class="xref" href="service.provisioning.html#i1297476" title="RFC 2396 - Uniform Resource Identifier (URI)">[6] <em>RFC 2396 - Uniform Resource Identifier (URI)</em></a>.
</p>
</div>
</div>
<div class="section">
<div xmlns="" class="titlepage">
<div>
<div>
<h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a xmlns="" class="anchor" id="d0e32634"></a><span xmlns="" class="number">110.8</span> Mapping To RSH Scheme
</h2>
</div>
</div>
</div>
<p>The RSH protocol is an OSGi-specific protocol, and is included in
this specification because it is optimized for Initial Provisioning. It
requires a shared secret between the management system and the OSGi
framework that is small enough to be entered by the Service User.
</p>
<p>RSH bases authentication and encryption on Message Authentication
Codes (MACs) that have been derived from a secret that is shared between
the OSGi framework and the Operator prior to the start of the protocol
execution.
</p>
<p>The protocol is based on an ordinary HTTP GET request/response, in
which the request must be <span class="emphasis"><em>signed</em></span> and the response
must be <span class="emphasis"><em>encrypted</em></span> and
<span class="emphasis"><em>authenticated</em></span>. Both the
<span class="emphasis"><em>signature</em></span> and <span class="emphasis"><em>encryption key</em></span> are
derived from the shared secret using Hashed Message Access Codes (HMAC)
functions.
</p>
<p>As additional input to the HMAC calculations, one client-generated
nonce and one server-generated nonce are used to prevent replay attacks.
The nonces are fairly large random numbers that must be generated in
relation to each invocation of the protocol, in order to guarantee
freshness. These nonces are called <code class="code">clientfg</code> (client-generated
freshness guarantee) and <code class="code">serverfg</code> (server-generated freshness
guarantee).
</p>
<p>In order to separate the HMAC calculations for authentication and
encryption, each is based on a different constant value. These constants
are called the <span class="emphasis"><em>authentication constant</em></span> and the
<span class="emphasis"><em>encryption constant</em></span>.
</p>
<p>From an abstract perspective, the protocol may be described as
follows.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p><span class="symbol">δ</span> - Shared secret, 160 bits or
more
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>s</em></span> - Server nonce, called
<code class="code">servercfg</code>, 128 bits
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>c</em></span> - Client nonce, called
<code class="code">clientfg</code>, 128 bits
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>K</em></span><sub>a</sub> - Authentication
key, 160 bits
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>K</em></span><sub>e</sub> - Encryption key,
192 bits
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>r</em></span> - Response data
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>e</em></span> - Encrypted data
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>E</em></span> - Encryption constant, a
<code class="code">byte[]</code> of 05, 36, 54, 70, 00 (hex)
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>A</em></span> - Authentication constant, a
<code class="code">byte[]</code> of 00, 4f, 53, 47, 49 (hex)
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>M</em></span> - Message material, used for
K<sub>e</sub> calculation.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>m</em></span> - The calculated message authentication
code.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>3DES</em></span> - Triple DES, encryption function, see
<a xmlns="" class="xref" href="service.provisioning.html#i1326320" title="3DES">[8] <em>3DES</em></a>. The bytes of the key must be set to odd
parity. CBC mode must be used where the padding method is defined in
<a xmlns="" class="xref" href="service.provisioning.html#i1371344" title="RFC 1423 Part III: Algorithms, Modes, and Identifiers">[9] <em>RFC 1423 Part III: Algorithms, Modes, and Identifiers</em></a>. In <a xmlns="" class="xref" href="service.provisioning.html#i1371440" title="Java Cryptography API (part of Java 1.4)">[11] <em>Java Cryptography API (part of Java 1.4)</em></a> this is
addressed as <code class="code">PKCS5Padding</code>.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>IV</em></span> - Initialization vector for 3DES.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>SHA1</em></span> - Secure Hash Algorithm to generate
the Hashed Message Authentication Code, see <a xmlns="" class="xref" href="service.provisioning.html#i1371220" title="SHA-1">[12] <em>SHA-1</em></a>. The function takes a single parameter, the block
to be worked upon.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>HMAC</em></span> - The function that calculates a
message authentication code, which must HMAC-SHA1. HMAC-SHA1 is
defined in <a xmlns="" class="xref" href="service.provisioning.html#i1327494" title="HMAC: Keyed-Hashing for Message Authentication">[1] <em>HMAC: Keyed-Hashing for Message Authentication</em></a>. The HMAC function takes a key
and a block to be worked upon as arguments. Note that the lower 16
bytes of the result must be used.
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>{}</em></span> - Concatenates its arguments
</p>
</li>
<li class="listitem">
<p><span class="emphasis"><em>[]</em></span> - Indicates access to a sub-part of a
variable, in bytes. Index starts at one, not zero.
</p>
</li>
</ul>
</div>
<p>In each step, the emphasized server or client indicates the context
of the calculation. If both are used at the same time, each variable will
have server or client as a subscript.
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1">
<li class="listitem">
<p>The <span class="emphasis"><em>client</em></span> generates a random nonce, stores
it and denotes it <code class="code">clientfg</code></p>
<p><span class="emphasis"><em>c = nonce</em></span></p>
</li>
<li class="listitem">
<p>The client sends the request with the <code class="code">clientfg</code> to
the server.
</p>
<p><span class="emphasis"><em>c</em></span><sub>server</sub> <span class="symbol">⇐</span>
<span class="emphasis"><em>c</em></span><sub>client</sub></p>
</li>
<li class="listitem">
<p>The <span class="emphasis"><em>server</em></span> generates a nonce and denotes it
<code class="code">serverfg</code>.
</p>
<p><span class="emphasis"><em>s = nonce</em></span></p>
</li>
<li class="listitem">
<p>The <span class="emphasis"><em>server</em></span> calculates an authentication key
based on the SHA1 function, the shared secret, the received
<code class="code">clientfg</code>, the <code class="code">serverfg</code> and the
authentication constant.
</p>
<p><span class="emphasis"><em>K</em></span><sub>a</sub> <span class="symbol">←</span> <span class="emphasis"><em>SHA1</em></span>({<span class="symbol">δ</span>, <span class="emphasis"><em>c</em></span>,
<span class="emphasis"><em>s</em></span>, <span class="emphasis"><em>A</em></span>})
</p>
</li>
<li class="listitem">
<p><a xmlns="" class="anchor" id="i1325557"></a>The <span class="emphasis"><em>server</em></span> calculates an encryption key
using an SHA-1 function, the shared secret, the received
<code class="code">clientfg</code>, the <code class="code">serverfg</code> and the encryption
constant. It must first calculate the <span class="emphasis"><em>key
material</em></span> M.
</p>
<p><span class="emphasis"><em>M</em></span>[1, 20] <span class="symbol">←</span>
<span class="emphasis"><em>SHA1</em></span>({ <span class="symbol">δ</span>,
<span class="emphasis"><em>c</em></span>, <span class="emphasis"><em>s</em></span>,
<span class="emphasis"><em>E</em></span>})
</p>
<p><span class="emphasis"><em>M</em></span>[21, 40] <span class="symbol">←</span>
<span class="emphasis"><em>SHA1</em></span>({ <span class="symbol">δ</span>,
<span class="emphasis"><em>M</em></span>[1, 20], <span class="emphasis"><em>c</em></span>,
<span class="emphasis"><em>s</em></span>, <span class="emphasis"><em>E</em></span>})
</p>
</li>
<li class="listitem">
<p><a xmlns="" class="anchor" id="i1325580"></a>The key for DES consists K<sub>e</sub> and
IV.
</p>
<p><span class="emphasis"><em>K</em></span><sub>e</sub> <span class="symbol">←</span> <span class="emphasis"><em>M</em></span>[1, 24]
</p>
<p><span class="emphasis"><em>IV</em></span> <span class="symbol">←</span>
<span class="emphasis"><em>M</em></span>[25, 32]
</p>
<p>The <span class="emphasis"><em>server</em></span> encrypts the response data using
the encryption key derived in step <a xmlns="" class="xref" href="service.provisioning.html#i1325557">5</a>. The
encryption algorithm that must be used to encrypt/decrypt the response
data is 3DES. 24 bytes (192 bits) from M are used to generate
K<sub>e</sub>, but the low order bit of each byte must be
used as an odd parity bit. This means that before using
K<sub>e</sub>, each byte must be processed to set the low
order bit so that the byte has odd parity.
</p>
<p>The encryption/decryption key used is specified by the