110 Initial Provisioning Specification

110.1 Introduction

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.

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.

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.

This bootstrapping process requires the installation of a Management Agent, with appropriate configuration data, in the OSGi framework.

This specification consists of a prologue, in which the principles of the Initial Provisioning are outlined, and a number of mappings to different mechanisms.

110.1.1 Essentials

  • Policy Free - 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.

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

  • Flexible - The management process should be as open as possible, to allow innovation and specialization while still achieving interoperability.

110.1.2 Entities

  • Provisioning Service - A service registered with the Framework that provides information about the initial provisioning to the Management Agent.

  • Provisioning Dictionary - A Dictionary object that is filled with information from the ZIP files that are loaded during initial setup.

  • RSH Protocol - An OSGi specific secure protocol based on HTTP.

  • Management Agent - A bundle that is responsible for managing a OSGi framework under control of a Remote Manager.

Figure 110.1 Initial Provisioning

Initial Provisioning

110.2 Procedure

The following procedure should be executed by an OSGi Framework implementation that supports this Initial Provisioning specification.

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.

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:


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:


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.

The result of the request must be a ZIP file. (The content type should be application/zip). It is the responsibility of the underlying protocol to guarantee the integrity and authenticity of this ZIP file.

This ZIP file is unpacked and its entries (except bundle and bundle-url entries, described in Table 110.2 ) are placed in a Dictionary object. This Dictionary object is called the Provisioning Dictionary. 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 ('/' \u002F).

The ZIP file may contain only four types of dictionary entries: text, binary, bundle, or bundle-url. 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):

  1. The manifest header InitialProvisioning-Entries of the given ZIP file. This header is defined in InitialProvisioning-Entries Manifest Header. If this header is present, but a given entry's path is not named then try the next step.

  2. The extension of the entry path name if one of .txt, .jar, .url extensions. See Table 110.1 on page for the mapping of types, MIME types, and extensions.

  3. The entry is assumed to be a binary type

The types can optionally be specified as a MIME type as defined in [7] MIME Types. The text and bundle-url entries are translated into a String object from an UTF-8 encoded byte array. All other entries must be stored as a byte[].

Table 110.1 Content types of provisioning ZIP file

Type MIME Type Ext Description




Must be represented as a String object




not txt, .url, or .jar

Must be represented as a byte array (byte[]).







Entries must be installed using BundleContext.installBundle(String, InputStream), with the InputStream object constructed from the contents of the ZIP entry. The location must be the name of the ZIP entry without leading solidus ('/' \u002F). This entry must not be stored in the Provisioning Dictionary.

If a bundle with this location name is already installed in this system, then this bundle must be updated instead of installed.

The MIME_BUNDLE_ALT version is intended for backward compatibility, it specifies the original MIME type for bundles before there was an official IANA MIME type.



text/x-osgi-bundle-url; charset=utf-8


The content of this entry is a string coded in utf-8. Entries must be installed using BundleContext.installBundle(String, InputStream), with the InputStream object created from the given URL. The location must be the name of the ZIP entry without leading solidus ('/' \u002F). This entry must not be stored in the Provisioning Dictionary.

If a bundle with this location URL is already installed in this system, then this bundle must be updated instead of installed.

The Provisioning Service must install (but not start) all entries in the ZIP file that are typed with bundle or bundle-url.

If an entry named PROVISIONING_START_BUNDLE is present in the Provisioning Dictionary, then its content type must be text as defined in Table 110.1. The content of this entry must match the bundle location of a previously loaded bundle. This designated bundle must be given AllPermission and started.

If no PROVISIONING_START_BUNDLE entry is present in the Provisioning Dictionary, the Provisioning Dictionary should contain a reference to another ZIP file under the PROVISIONING_REFERENCE key. If both keys are absent, no further action must take place.

If this PROVISIONING_REFERENCE key is present and holds a String object that can be mapped to a valid URL, then a new ZIP file must be retrieved from this URL. The PROVISIONING_REFERENCE link may be repeated multiple times in successively loaded ZIP files.

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 PROVISIONING_REFERENCE link may be repeated multiple times in successively loaded ZIP files. The entry PROVISIONING_UPDATE_COUNT must be an Integer object that must be incremented on every iteration.

Information retrieved while loading subsequent PROVISIONING_REFERENCE 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 proprietary-x, 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 bundle or bundle-url (see Table 110.1 ) must be installed and not started.

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 PROVISIONING_REFERENCE 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 PROVISIONING_REFERENCE to the location of this new Remote Manager's Initial Provisioning ZIP file. This process is called re-provisioning.

If errors occur during this process, the Initial Provisioning service should try to notify the Service User of the problem.

The previous description is depicted in Figure 110.2 as a flow chart.

Figure 110.2 Flow chart installation Management Agent bundle

Flow chart installation Management Agent bundle

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 personalized OSGi framework bundles. The PROVISIONING_AGENT_CONFIG key is reserved for this purpose, but the Management Agent may use another key or mechanisms if so desired.

The PROVISIONING_SPID key must contain the OSGi framework Identifier.

110.2.1 InitialProvisioning-Entries Manifest Header

The InitialProvisioning-Entries manifest header optionally specifies the type of the entries in the ZIP file. The syntax for this header is:

InitialProvisioning-Entries ::= ip-entry (',' ip-entry ) *
ip-entry                    ::= path ( ';' parameter ) *

The entry is the path name of a resource in the ZIP file. This InitialProvisioning-Entries header recognizes the following attribute:

  • type - Gives the type of the dictionary entry. The type can have one of the following values: text, binary, bundle, or bundle-url

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 Table 110.1 on page .

110.3 Special Configurations

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.

110.3.1 Branded OSGi framework Server

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 Dictionary entry PROVISIONING_REFERENCE pointing at a location controlled by the Operator.

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.

110.3.2 Non-connected OSGi framework

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.

The non-connected case can be implemented by specifying a file:// URL for the initial ZIP file ( PROVISIONING_REFERENCE ). That file:// URL would name a local file containing the response that would otherwise be received from a remote server.

The value for the Management Agent PROVISIONING_REFERENCE found in that file will be used as input to the load process. The PROVISIONING_REFERENCE may point to a bundle file stored either locally or remotely. No code changes are necessary for the non-connected scenario. The file:// URLs must be specified, and the appropriate files must be created on the OSGi framework.

110.4 The Provisioning Service

Provisioning information is conveyed between bundles using the Provisioning Service, as defined in the ProvisioningService interface. The Provisioning Dictionary is retrieved from the ProvisioningService object using the getInformation() method. This is a read-only Dictionary object, any changes to this Dictionary object must throw an UnsupportedOperationException.

The Provisioning Service provides a number of methods to update the Provisioning Dictionary.

  • addInformation(Dictionary) - Add all key/value pairs in the given Dictionary object to the Provisioning Dictionary.

  • addInformation(ZipInputStream) - 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 Procedure.

  • setInformation(Dictionary) - Set a new Provisioning Dictionary. This will remove all existing entries.

Each of these method will increment the PROVISIONING_UPDATE_COUNT entry.

110.5 Management Agent Environment

The Management Agent should be written with great care to minimize dependencies on other packages and services, as all 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.

The Provisioning Service must ensure that the Management Agent is running with AllPermission. 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 PermissionAdmin interfaces may not be present (it is an optional service), the Management Agent should export the PermissionAdmin interfaces to ensure they can be resolved.

Once started, the Management Agent may retrieve its configuration data from the Provisioning Service by getting the byte[] object that corresponds to the PROVISIONING_AGENT_CONFIG key in the Provisioning Dictionary. The structure of the configuration data is implementation specific.

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.

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.

110.6 Mapping To File Scheme

The file: 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.

If the initial request URL has a file scheme, no parameters should be appended, because the file: scheme does not accept parameters.

110.6.1 Example With File Scheme

The manufacturer should prepare a ZIP file containing only one entry named PROVISIONING_START_BUNDLE that contains a location string of an entry of type bundle or bundle-url. For example, the following ZIP file demonstrates this:

provisioning.start.bundle  text        agent
agent                      bundle      C0AF0E9B2AB..

The bundle may also be specified with a URL:

provisioning.start.bundle  text        http://acme.com/a.jar
agent                      bundle-url  http://acme.com/a.jar

Upon startup, the framework is provided with the URL with the file: scheme that points to this ZIP file:


110.7 Mapping To HTTP(S) Scheme

This section defines how HTTP and HTTPS URLs must be used with the Initial Provisioning specification.

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

  • HTTPS - May be used if the OSGi framework is equipped with appropriate certificates.

HTTP and HTTPS share the following qualities:

  • Both are well known and widely used

  • Numerous implementations of the protocols exist

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

Both HTTP and HTTPS must be used with the GET method. The response is a ZIP file, implying that the response header Content-Type header must contain application/zip.

110.7.1 HTTPS Certificates

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.

The root certificate is stored in the Provisioning Dictionary under the key:


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

110.7.2 Certificate Encoding

Root certificates are X.509 certificates. Each individual certificate is stored as a byte[] object. This byte[] object is encoded in the default Java manner, as follows:

  • The original, binary certificate data is DER encoded

  • The DER encoded data is encoded into base64 to make it text.

  • The base64 encoded data is prefixed with


    and suffixed with:

    -----END CERTIFICATE-----
  • If a record contains more than one certificate, they are simply appended one after the other, each with a delimiting prefix and suffix.

The decoding of such a certificate may be done with the java.security.cert.CertificateFactory class:

InputStream bis = new ByteArrayInputStream(x509);// byte[]
CertificateFactory cf = 
Collection c = cf.generateCertificates(bis); 
Iterator i = c.iterator(); 
while (i.hasNext()) { 
    Certificate cert = (Certificate)i.next();

110.7.3 URL Encoding

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.

If the request URL already contains HTTP parameters (if there is a '?' in the request), the service_platform_id is appended to this URL as an additional parameter. If, on the other hand, the request URL does not contain any HTTP parameters, the service_platform_id will be appended to the URL after a '?', becoming the first HTTP parameter. The following two examples show these two variants:

http://server.operator.com/service-x? «

http://server.operator.com/service-x? «

Proper URL encoding must be applied when the URL contains characters that are not allowed. See [6] RFC 2396 - Uniform Resource Identifier (URI).

110.8 Mapping To RSH Scheme

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.

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.

The protocol is based on an ordinary HTTP GET request/response, in which the request must be signed and the response must be encrypted and authenticated. Both the signature and encryption key are derived from the shared secret using Hashed Message Access Codes (HMAC) functions.

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 clientfg (client-generated freshness guarantee) and serverfg (server-generated freshness guarantee).

In order to separate the HMAC calculations for authentication and encryption, each is based on a different constant value. These constants are called the authentication constant and the encryption constant.

From an abstract perspective, the protocol may be described as follows.

  • δ - Shared secret, 160 bits or more

  • s - Server nonce, called servercfg, 128 bits

  • c - Client nonce, called clientfg, 128 bits

  • Ka - Authentication key, 160 bits

  • Ke - Encryption key, 192 bits

  • r - Response data

  • e - Encrypted data

  • E - Encryption constant, a byte[] of 05, 36, 54, 70, 00 (hex)

  • A - Authentication constant, a byte[] of 00, 4f, 53, 47, 49 (hex)

  • M - Message material, used for Ke calculation.

  • m - The calculated message authentication code.

  • 3DES - Triple DES, encryption function, see [8] 3DES. The bytes of the key must be set to odd parity. CBC mode must be used where the padding method is defined in [9] RFC 1423 Part III: Algorithms, Modes, and Identifiers. In [11] Java Cryptography API (part of Java 1.4) this is addressed as PKCS5Padding.

  • IV - Initialization vector for 3DES.

  • SHA1 - Secure Hash Algorithm to generate the Hashed Message Authentication Code, see [12] SHA-1. The function takes a single parameter, the block to be worked upon.

  • HMAC - The function that calculates a message authentication code, which must HMAC-SHA1. HMAC-SHA1 is defined in [1] HMAC: Keyed-Hashing for Message Authentication. 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.

  • {} - Concatenates its arguments

  • [] - Indicates access to a sub-part of a variable, in bytes. Index starts at one, not zero.

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.

  1. The client generates a random nonce, stores it and denotes it clientfg

    c = nonce

  2. The client sends the request with the clientfg to the server.

    cserver cclient

  3. The server generates a nonce and denotes it serverfg.

    s = nonce

  4. The server calculates an authentication key based on the SHA1 function, the shared secret, the received clientfg, the serverfg and the authentication constant.

    Ka SHA1({δ, c, s, A})

  5. The server calculates an encryption key using an SHA-1 function, the shared secret, the received clientfg, the serverfg and the encryption constant. It must first calculate the key material M.

    M[1, 20] SHA1({ δ, c, s, E})

    M[21, 40] SHA1({ δ, M[1, 20], c, s, E})

  6. The key for DES consists Ke and IV.

    Ke M[1, 24]

    IV M[25, 32]

    The server encrypts the response data using the encryption key derived in step 5. 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 Ke, but the low order bit of each byte must be used as an odd parity bit. This means that before using Ke, each byte must be processed to set the low order bit so that the byte has odd parity.

    The encryption/decryption key used is specified by the following:

    e 3DES( Ke, IV, r)

  7. The server calculates a MAC m using the HMAC function, the encrypted response data and the authentication key derived in 4.

    m HMAC( Ka, e)

  8. The server sends a response to the client containing the serverfg, the MAC m and the encrypted response data

    sclient sserver

    mclient mserver

    eclient eserver

    The client calculates the encryption key Ke the same way the server did in steps 5 and 6, and uses this to decrypt the encrypted response data. The serverfg value received in the response is used in the calculation.

    r 3DES( Ke, IV, e)

  9. The client performs the calculation of the MAC m' in the same way the server did, and checks that the results match the received MAC m. If they do not match, further processing is discarded. The serverfg value received in the response is used in the calculation.

    Ka SHA1({δ, c, s, A})

    m' HMAC( Ka, e)

    m' = m

Figure 110.3 Action Diagram for RSH

Action Diagram for RSH

110.8.1 Shared Secret

The shared secret should be a key of length 160 bits (20 bytes) or more. The length is selected to match the output of the selected hash algorithm [2] NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995.

In some scenarios, the shared secret is generated by the Operator and communicated to the User, who inserts the secret into the OSGi framework through some unspecified means.

The opposite is also possible: the shared secret can be stored within the OSGi framework, extracted from it, and then communicated to the Operator. In this scenario, the source of the shared secret could be either the OSGi framework or the Operator.

In order for the server to calculate the authentication and encryption keys, it requires the proper shared secret. The server must have access to many different shared secrets, one for each OSGi framework it is to support. To be able to resolve this issue, the server must typically also have access to the OSGi framework Identifier of the OSGi framework. The normal way for the server to know the OSGi framework Identifier is through the application protocol, as this value is part of the URL encoded parameters of the HTTP, HTTPS, or RSH mapping of the Initial Provisioning.

In order to be able to switch Operators, a new shared secret must be used. The new secret may be generated by the new Operator and then inserted into the OSGi framework device using a mechanism not covered by this specification. Or the device itself may generate the new secret and convey it to the owner of the device using a display device or read-out, which is then communicated to the new operator out-of-band. Additionally, the generation of the new secret may be triggered by some external event, like holding down a button for a specified amount of time.

110.8.2 Request Coding

RSH is mapped to HTTP or HTTPS. Thus, the request parameters are URL encoded as discussed in URL Encoding. RSH requires an additional parameter in the URL: the clientfg parameter. This parameter is a nonce that is used to counter replay attacks. See also RSH Transport.

110.8.3 Response Coding

The server's response to the client is composed of three parts:

  • A header containing the protocol version and the serverfg

  • The MAC

  • The encrypted response

These three items are packaged into a binary container according to Table 110.2.

Table 110.2 RSH Header description

Bytes Description Value hex


Number of bytes in header



Major version number



Minor version number






Number of bytes in MAC



Message Authentication Code



Number of bytes of encrypted ZIP file



Encrypted ZIP file


The response content type is an RSH-specific encrypted ZIP file, implying that the response header Content-Type must be application/x-rsh for the HTTP request. When the content file is decrypted, the content must be a ZIP file.

110.8.4 RSH URL

The RSH URL must be used internally within the OSGi framework to indicate the usage of RSH for initial provisioning. The RSH URL format is identical to the HTTP URL format, except that the scheme is rsh: instead of http:. For example ( « means line continues on next line):


110.8.5 Extensions to the Provisioning Service Dictionary

RSH specifies one additional entry for the Provisioning Dictionary:


The value of this entry is a byte[] containing the shared secret used by the RSH protocol.

110.8.6 RSH Transport

RSH is mapped to HTTP or HTTPS and follows the same URL encoding rules, except that the clientfg is additionally appended to the URL. The key in the URL must be clientfg and the value must be encoded in base 64 format:

The clientfg parameter is transported as an HTTP parameter that is appended after the service_platform_id parameter. The second example above would then be:


Which, when mapped to HTTP, must become:

http://server.operator.com/service-x «
    service_platform_id=VIN:123456789& «

110.9 Exception Handling

The Initial Provisioning process is a sensitive process that must run without user supervision. There is therefore a need to handle exceptional cases in a well defined way to simplify trouble shooting.

There are only 2 types of problems that halt the provisioning process. They are:

  • IO Exception when reading or writing provisioning information.

  • IO Exception when retrieving or processing a provisioning zip file.

Other exceptions can occur and the Provisioning Service must do any attempt to log these events.

In the cases that the provisioning process stops, it is important that the clients of the provisioning service have a way to find out that the process is stopped. The mechanism that is used for this is a special entry in the provisioning dictionary. The name of the entry must be provisioning.error. The value is a String object with the following format:

  • Numeric error code

  • Space

  • A human readable string describing the error.

Permitted error codes are:

  • 0 - Unknown error

  • 1 - Couldn't load or save provisioning information

  • 2 - Malformed URL Exception

  • 3 - IO Exception when retrieving document of a URL

  • 4 - Corrupted Zip Input Stream

The provisioning.update.count will be incremented as normal when a provisioning.error entry is added to the provisioning information. After, the provisioning service will take no further action.

Some examples:

0 SIM card removed
2 "http://www.acme.com/secure/blib/ifa.zip"

110.10 Security

The security model for the OSGi framework is based on the integrity of the Management Agent deployment. If any of the mechanisms used during the deployment of management agents are weak, or can be compromised, the whole security model becomes weak.

From a security perspective, one attractive means of information exchange would be a smart card. This approach enables all relevant information to be stored in a single place. The Operator could then provide the information to the OSGi framework by inserting the smart card into the OSGi framework.

110.10.1 Concerns

The major security concerns related to the deployment of the Management Agent are:

  • The OSGi framework is controlled by the intended Operator

  • The Operator controls the intended OSGi framework(s)

  • The integrity and confidentiality of the information exchange that takes place during these processes must be considered

In order to address these concerns, an implementation of the OSGi Remote Management Architecture must assure that:

  • The Operator authenticates itself to the OSGi framework

  • The OSGi framework authenticates itself to the Operator

  • The integrity and confidentiality of the Management Agent, certificates, and configuration data are fully protected if they are transported over public transports.

Each mapping of the Initial Provisioning specification to a concrete implementation must describe how these goals are met.

110.10.2 OSGi framework Long-Term Security

Secrets for long-term use may be exchanged during the Initial Provisioning procedures. This way, one or more secrets may be shared securely, assuming that the Provisioning Dictionary assignments used are implemented with the proper security characteristics.

110.10.3 Permissions

The provisioning information may contain sensitive information. Also, the ability to modify provisioning information can have drastic consequences. Thus, only trusted bundles should be allowed to register, or get the Provisioning Service. This restriction can be enforced using ServicePermission[ ProvisioningService, GET].

No Permission classes guard reading or modification of the Provisioning Dictionary, so care must be taken not to leak the Dictionary object received from the Provisioning Service to bundles that are not trusted.

Whether message-based or connection-based, the communications used for Initial Provisioning must support mutual authentication and message integrity checking, at a minimum.

By using both server and client authentication in HTTPS, the problem of establishing identity is solved. In addition, HTTPS will encrypt the transmitted data. HTTPS requires a Public Key Infrastructure implementation in order to retrieve the required certificates.

When RSH is used, it is vital that the shared secret is shared only between the Operator and the OSGi framework, and no one else.

110.11 org.osgi.service.provisioning

Version 1.2

Provisioning Package Version 1.2.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. This package has two types of users: the consumers that use the API in this package and the providers that implement the API in this package.

Example import for consumers using the API in this package:

Import-Package: org.osgi.service.provisioning; version="[1.2,2.0)"

Example import for providers implementing the API in this package:

Import-Package: org.osgi.service.provisioning; version="[1.2,1.3)"

110.11.1 Summary

110.11.2 public interface ProvisioningService

Service for managing the initial provisioning information.

Initial provisioning of an OSGi device is a multi step process that culminates with the installation and execution of the initial management agent. At each step of the process, information is collected for the next step. Multiple bundles may be involved and this service provides a means for these bundles to exchange information. It also provides a means for the initial Management Bundle to get its initial configuration information.

The provisioning information is collected in a Dictionary object, called the Provisioning Dictionary. Any bundle that can access the service can get a reference to this object and read and update provisioning information. The key of the dictionary is a String object and the value is a String or byte[] object. The single exception is the PROVISIONING_UPDATE_COUNT value which is an Integer. The provisioning prefix is reserved for keys defined by OSGi, other key names may be used for implementation dependent provisioning systems.

Any changes to the provisioning information will be reflected immediately in all the dictionary objects obtained from the Provisioning Service.

Because of the specific application of the Provisioning Service, there should be only one Provisioning Service registered. This restriction will not be enforced by the Framework. Gateway operators or manufactures should ensure that a Provisioning Service bundle is not installed on a device that already has a bundle providing the Provisioning Service.

The provisioning information has the potential to contain sensitive information. Also, the ability to modify provisioning information can have drastic consequences. Thus, only trusted bundles should be allowed to register and get the Provisioning Service. The ServicePermission is used to limit the bundles that can gain access to the Provisioning Service. There is no check of Permission objects to read or modify the provisioning information, so care must be taken not to leak the Provisioning Dictionary received from getInformation method.

Consumers of this API must not implement this interface public static final String INITIALPROVISIONING_ENTRIES = "InitialProvisioning-Entries"

Name of the header that specifies the type information for the ZIP file entries.

1.2 public static final String MIME_BUNDLE = "application/vnd.osgi.bundle"

MIME type to be stored in the extra field of a ZipEntry object for an installable bundle file. Zip entries of this type will be installed in the framework, but not started. The entry will also not be put into the information dictionary. public static final String MIME_BUNDLE_ALT = "application/x-osgi-bundle"

Alternative MIME type to be stored in the extra field of a ZipEntry object for an installable bundle file. Zip entries of this type will be installed in the framework, but not started. The entry will also not be put into the information dictionary. This alternative entry is only for backward compatibility, new applications are recommended to use MIME_BUNDLE, which is an official IANA MIME type.

1.2 public static final String MIME_BUNDLE_URL = "text/x-osgi-bundle-url"

MIME type to be stored in the extra field of a ZipEntry for a String that represents a URL for a bundle. Zip entries of this type will be used to install (but not start) a bundle from the URL. The entry will not be put into the information dictionary. public static final String MIME_BYTE_ARRAY = "application/octet-stream"

MIME type to be stored in the extra field of a ZipEntry object for byte[] data. public static final String MIME_STRING = "text/plain;charset=utf-8"

MIME type to be stored in the extra field of a ZipEntry object for String data. public static final String PROVISIONING_AGENT_CONFIG = "provisioning.agent.config"

The key to the provisioning information that contains the initial configuration information of the initial Management Agent. The value will be of type byte[]. public static final String PROVISIONING_REFERENCE = "provisioning.reference"

The key to the provisioning information that contains the location of the provision data provider. The value must be of type String. public static final String PROVISIONING_ROOTX509 = "provisioning.rootx509"

The key to the provisioning information that contains the root X509 certificate used to establish trust with operator when using HTTPS. public static final String PROVISIONING_RSH_SECRET = "provisioning.rsh.secret"

The key to the provisioning information that contains the shared secret used in conjunction with the RSH protocol. public static final String PROVISIONING_SPID = "provisioning.spid"

The key to the provisioning information that uniquely identifies the Service Platform. The value must be of type String. public static final String PROVISIONING_START_BUNDLE = "provisioning.start.bundle"

The key to the provisioning information that contains the location of the bundle to start with AllPermission. The bundle must have be previously installed for this entry to have any effect. public static final String PROVISIONING_UPDATE_COUNT = "provisioning.update.count"

The key to the provisioning information that contains the update count of the info data. Each set of changes to the provisioning information must end with this value being incremented. The value must be of type Integer. This key/value pair is also reflected in the properties of the ProvisioningService in the service registry. public void addInformation(Dictionary<String, ?> info)

the set of Provisioning Information key/value pairs to add to the Provisioning Information dictionary. Any keys are values that are of an invalid type will be silently ignored.

Adds the key/value pairs contained in info to the Provisioning Information dictionary. This method causes the PROVISIONING_UPDATE_COUNT to be incremented. public void addInformation(ZipInputStream zis) throws IOException

the ZipInputStream that will be used to add key/value pairs to the Provisioning Information dictionary and install and start bundles. If a ZipEntry does not have an Extra field that corresponds to one of the four defined MIME types (MIME_STRING, MIME_BYTE_ARRAY, MIME_BUNDLE, and MIME_BUNDLE_URL) in will be silently ignored.

Processes the ZipInputStream and extracts information to add to the Provisioning Information dictionary, as well as, install/update and start bundles. This method causes the PROVISIONING_UPDATE_COUNT to be incremented.

IOException– if an error occurs while processing the ZipInputStream. No additions will be made to the Provisioning Information dictionary and no bundles must be started or installed. public Dictionary<String, Object> getInformation()

Returns a reference to the Provisioning Dictionary. Any change operations (put and remove) to the dictionary will cause an UnsupportedOperationException to be thrown. Changes must be done using the setInformation and addInformation methods of this service.

A reference to the Provisioning Dictionary. public void setInformation(Dictionary<String, ?> info)

the new set of Provisioning Information key/value pairs. Any keys are values that are of an invalid type will be silently ignored.

Replaces the Provisioning Information dictionary with the key/value pairs contained in info. Any key/value pairs not in info will be removed from the Provisioning Information dictionary. This method causes the PROVISIONING_UPDATE_COUNT to be incremented.

110.12 References

[1]HMAC: Keyed-Hashing for Message Authenticationhttp://www.ietf.org/rfc/rfc2104.txt Krawczyk ,et. al. 1997

[2]NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995

[3]Hypertext Transfer Protocol - HTTP/1.1http://www.ietf.org/rfc/rfc2616.txt Fielding, R., et. al.

[4]Rescorla, E., HTTP over TLS, IETF RFC 2818, May 2000http://www.ietf.org/rfc/rfc2818.txt

[6]RFC 2396 - Uniform Resource Identifier (URI)http://www.ietf.org/rfc/rfc2396.txt

[8]3DESW/ Tuchman, "Hellman Presents No Shortcut Solution to DES," IEEE Spectrum, v. 16, n. 7 July 1979, pp40-41

[9]RFC 1423 Part III: Algorithms, Modes, and Identifiershttp://www.ietf.org/rfc/rfc1423.txt

[12]SHA-1U.S. Government, Proposed Federal Information Processing Standard for Secure Hash Standard, January 1992

[13]Transport Layer Securityhttp://www.ietf.org/rfc/rfc2246.txt, January 1999, The TLS Protocol Version 1.0, T. Dierks & C. Allen