Over The Air User Initiated
Provisioning Specification

for the Mobile Information Device Profile

Preface

This document, Over The Air User Initiated Provisioning, is for the Mobile Information Device Profile (MIDP) specification version 2.0. The original JSR and expert group details can be found at http://jcp.org/jsr/detail/118.jsp. The terminology used herein is defined in the Definitions section of the MIDP 2.0 specification except where noted.

How This Specification Is Organized

The topics in this specification are organized in the following sections:

• Section 1, "Over The Air User Initiated Provisioning", defines how MIDP applications should be distributed to wireless devices.
• Section 2, "MIDP Provisioning and Networking in the WAP June2000 Environment", describes the specific requirements for deploying MIDP applications via a proxied WAP Gateway.

References

1. Connected, Limited Device Configuration (CLDC)
   http://jcp.org/jsr/detail/30.jsp
2. Mobile Information Device Profile (MIDP 1.0)
   http://jcp.org/jsr/detail/37.jsp
3. Mobile Information Device Profile 2.0 (MIDP 2.0)
   http://jcp.org/jsr/detail/118.jsp
4. HTTP 1.1 Specification
   http://www.ietf.org/rfc/rfc2616.txt
5. HTTP Authentication: Basic and Digest Access Authentication
   http://www.ietf.org/rfc/rfc2617.txt
6. Java(tm) Servlet 2.3 Specification
   http://jcp.org/jsr/detail/53.jsp

Changes since the OTA Recommended Practice

After the MIDP 1.0 specification was published, a document entitled, Over The Air User Initiated Provisioning Recommended Practice for the Mobile Information Device Profile, was published. This specification replaces that document, and the following changes were made for MIDP 2.0:

• Removed the Cookie support requirement. This was necessary because in some network architectures the cookie information may not be transmitted to the client. The cookies were used to maintain state information between the Application Descriptor, JAR downloads, and Install-Notify reports. An alternative approach of URL rewriting is possible, and can serve the same purpose. For example, when sending the Application Descriptor, the server can insert unique JAR, MIDlet-Install-Notify, and MIDlet-Delete-Notify URLs that associate these with this a particular download session. Other options may also be possible.

Section 1, Over The Air User Initiated Provisioning

Overview and Goals

The purpose of this document is to describe how MIDlet suites can be deployed Over-The-Air (OTA), and the requirements imposed upon the client device to support these deployments. Following these recommendations will help ensure interoperability between clients and servers from all manufacturers and provide guidance to mobile network operators deploying MIDP devices.

Devices MUST provide mechanisms that allow users to discover MIDlet suites that can be loaded into the device. In some cases, discovery will be via the device's resident browser (e.g., i-mode or WAP). In other cases, it may be a resident application written specifically to identify MIDlet suites for the user to download. Throughout this document, an application with this functionality will be referred to as the discovery application, or DA.

Other installation mechanisms (e.g. Bluetooth^TM wireless technology, serial cable, IrDA^TM, etc.) MAY be supported by devices, but are outside the scope of this version of the specification.

The term Application Management Software (AMS) is a generic term used to describe the software on the device that manages the downloading and lifecycle of MIDlets. This term does not refer to any specific implementation and is used for convenience only. In some implementations, the term Java Application Manager (JAM) is used interchangeably.

This document describes the general functional requirements on the device and the functions supporting the MIDlet suite lifecycle. The lifecycle of a MIDlet suite consists of discovery, installation, update, invocation and removal. Descriptions are included for additional Application Descriptor attributes and mechanisms that identify the device type and characteristics to servers providing MIDlet suites.

Functional Requirements

A MIDP-compliant device MUST be capable of:

• Browsing, or otherwise locating MIDlet suite Application Descriptors in the network.
• Transferring a MIDlet suite and its associated Application Descriptor to the device from a server using HTTP 1.1 or a session protocol that implements the HTTP 1.1 functionality (including the header and entity fields) as required in this document.
• Responding to a 401 (Unauthorized) or 407 (Proxy Authentication Required) response to an HTTP request by asking the user for a user name and password and re-sending the HTTP request with the credentials supplied. The device MUST be able to support at least the RFC2617 Basic Authentication Scheme.
• Installing the MIDlet suite on the device
• Invoking MIDlets
• Allowing the user to delete MIDlet suites stored on the device. Single MIDlets cannot be deleted since the MIDlet suite is the unit of transfer and installation.

MIDlet Suite Discovery

Application discovery is the process by which a user locates a MIDlet suite using the device. User-initiated discovery and installation of MIDlet suites MUST be supported in the following high-level manner:

• While using the DA, the user is presented with a link to a MIDlet suite or Application Descriptor.
• The user selects the link to begin the installation process
• If available, the Application Descriptor is transferred to the device first. This descriptor contains information about the MIDlet suite and can be used by the device's AMS to start installation
• If the Application Descriptor is not available, or after the AMS has downloaded the Application Descriptor and determined that installation should continue, the MIDlet suite JAR file download begins.

Using the DA, the user SHOULD be able to access a network location and see a description of the MIDlet suite along with a link that, when selected, initiates the installation of the MIDlet suite. If the link refers to a JAR file as described in the MIDP specification, the JAR file and its URL are passed to the AMS on the device to start the installation process. If the link refers to an Application Descriptor, as described in the MIDP specification:

1. Once the link has been selected, the server MUST indicate in the response that the data being transferred (i.e., the Application Descriptor) has a MIME type of "text/vnd.sun.j2me.app-descriptor".
2. After completing this transfer, the application descriptor and its URL are passed to the AMS on the device to start the installation process. The Application Descriptor is used by the AMS to determine if the associated MIDlet suite can be successfully installed and executed on the device. If not, the user MUST be notified of the conditions that prevent its installation. The user SHOULD be informed of unusual conditions as early as possible to minimize wasted time and network bandwidth. The request-header attributes described in Device Identification and Request Headers SHOULD be used when retrieving the Application Descriptor.
3. The Application Descriptor MUST be converted from its transport format to the Unicode-encoding that is specified by the MIDP specification before it can be used. The default character set specified for the MIME type "text/vnd.sun.j2me.app-descriptor" is "UTF-8". If the device supports other character sets, the appropriate Accept-Charset header SHOULD be included in the request, and the content SHOULD be converted based on the charset attribute returned on the Content-Type header. If charset is undefined, the encoding defaults to "UTF-8", and it SHOULD be converted accordingly. The attributes in the descriptor MUST be formatted according to the syntax in the MIDP specification and all of the attributes required by the MIDP specification MUST be present in the descriptor. If this is not the case, then the client MUST return Status Code 906 in the status report.
4. Using the information in the Application Descriptor including the vendor, name, version, and size attributes, the user SHOULD be given a chance to confirm that they want to install the MIDlet suite. Situations such as trying to install an older version, or installing the same version, SHOULD be brought to the user's attention. Conditions that can prevent the successful installation and execution of the MIDlet suite SHOULD be identified, and the user notified. For example, if it is known that insufficient memory is available, the software SHOULD aid the user in reviewing memory usage and freeing sufficient memory for installation of the new MIDlet suite.

MIDlet Suite Installation

Application installation is the process by which a MIDlet suite is downloaded onto the device and made available to the user. Application installation MUST be supported. The network supporting the devices, as well any proxies and origin servers that are used during provisioning, MUST be able to support this requirement. The user retains control of the resources used by MIDlet suites on the device and MUST be allowed to delete or install MIDlet suites.

The device MUST make the MIDlet(s) in the MIDlet suite available for execution by the user. When multiple MIDlets are contained in a MIDlet suite, the user MAY need to be aware that there is more than one. The device MAY run a MIDlet from the MIDlet suite immediately at the user's option.

During installation, the user SHOULD be informed of progress and MUST be given an opportunity to cancel the process. Interrupting installation MUST leave the device in the state it was in before installation began.

If the MIDlet suite is already installed on the device, it SHOULD be treated as an update. See MIDlet Suite Update for additional information on how to handle an update.

To install a MIDlet suite, the AMS performs the following series of steps and checks and provides the user with feedback about the progress:

1. The device initiates the download of the MIDlet suite via HTTP. If an Application Descriptor was first downloaded as described in the MIDlet suite Discovery section, the request for the MIDlet suite MUST be for exactly the URL specified in the descriptor; additional headers are unnecessary.
2. If the server or proxy responds to the request for the MIDlet suite with a 401 (Unauthorized) or 407 (Proxy Authentication Required), the device SHOULD re-send the request with the user-supplied credentials in an Authorization or Proxy-Authorization header field as specified in RFC2617. The credentials SHOULD be provided by the user--for example, a common mechanism would be to present a dialog to the user to enter a user name and password. The device MUST be able to support at least the Basic Authentication Scheme as described in RFC2617.
3. The MIDlet suite and the headers that are received MUST be checked to verify that the retrieved MIDlet suite is valid and can be installed on the device. The user MUST be alerted to at least the following problems that prevent installation:
• If there is insufficient memory to store the MIDlet suite on the device, the device MUST return Status Code 901 in the Status Report.
• If the JAR is not available at the MIDlet-Jar-URL attribute in the descriptor, the device MUST return Status Code 907 in the Status Report.
• If the received JAR file size does not match the size specified in the Application Descriptor, the device MUST return Status Code 904 in the Status Report.
• If the manifest or any other file can not be extracted from the JAR, the device MUST return Status Code 907 in the Status Report.
• If the JAR manifest is not in the correct syntax, or if any of the required attributes are missing in the JAR manifest, the device MUST return Status Code 907 in the Status Report.
• If the mandatory attributes in the descriptor "MIDlet-Name", "MIDlet-Version", and "MIDlet-Vendor" do not match those in the JAR manifest, the device MUST return Status Code 905 in the Status Report.
• If the MIDlet suite is trusted, then the values in the application descriptor for MIDlet-* attributes MUST be identical to the corresponding attribute values in the Manifest. If not, the device MUST return Status Code 905 in the Status Report.
• If the application failed to be authenticated, the device MUST return Status Code 909 in the Status Report.
• If the application is an unsigned version of an installed signed version of the same application, the device MUST return Status Code 910 in the Status Report.
• If the application is not authorized for a permission listed in the MIDlet-Permissions attribute, the device MUST return Status Code 910 in the Status Report.
• If a static push registration fails for a reason other than not being authorized, the device MUST return Status Code 911 in the Status Report.
• If the network service is lost during installation, Status Code 903 SHOULD be used in a Status Report if possible (it may be impossible to deliver the status report due to the network-service outage).
4. Provided there are no problems that prevent installation, the MIDlets contained in the MIDlet suite MUST be installed and made available for execution by the user via the device's MIDlet selection mechanism.
5. Installation is complete when the MIDlet suite has been made available on the device, or an unrecoverable failure has occurred. In either case, the status MUST be reported as described in Installation Status Reports..

MIDlet Suite Update

A MIDlet suite update is defined as the operation of installing a specific MIDlet suite when that same MIDlet suite (either the same version or a different version) is already installed on the device. Devices MUST support the updating of MIDlet suites. In order to be meaningful to the user, the device MUST allow the user to obtain information about the MIDlet suite(s) on the device and determine which versions of software are installed. See Device Identification and Request Headers. for the attributes that apply to updates.

When a MIDlet suite update is started, the device MUST notify the user if the MIDlet suite is a newer, older, or the same version of an existing MIDlet suite and MUST get confirmation from the user before proceeding.

The RMS record stores of a MIDlet suite being updated MUST be managed as follows:

• If the cryptographic signer of the new MIDlet suite and the original MIDlet suite are identical, then the RMS record stores MUST be retained and made available to the new MIDlet suite.
• If the scheme, host, and path of the URL that the new Application Descriptor is downloaded from is identical to the scheme, host, and path of the URL the original Application Descriptor was downloaded from, then the RMS MUST be retained and made available to the new MIDlet suite.
• If the scheme, host, and path of the URL that the new MIDlet suite is downloaded from is identical to the scheme, host, and path of the URL the original MIDlet suite was downloaded from, then the RMS MUST be retained and made available to the new MIDlet suite.
• If the above statements are false, then the device MUST ask the user whether the data from the original MIDlet suite should be retained and made available to the new MIDlet suite.

In all cases, an unsigned MIDlet MUST NOT be allowed to update a signed MIDlet suite. The format, contents and versioning of the record stores is the responsibility of the MIDlet suite. The user-granted permissions given to the original MIDlet suite SHOULD also be given to the new MIDlet suite, if they are in the security domain of the new MIDlet suite.

MIDlet Suite Execution

When the user selects a MIDlet to be run, the device MUST invoke the MIDlet with the CLDC and MIDP classes required by the MIDP specification. If multiple MIDlets are present, the user interface MUST allow the user to select each one for execution.

MIDlet Suite Removal

Devices MUST allow users to remove MIDlet suites. When a MIDlet suite is to be removed from the device, the user SHOULD be prompted to confirm that the MIDlet suite may be removed. The device SHOULD warn the user of any special circumstances that arise during the deletion of the MIDlet suite. For example, the MIDlet suite MAY contain multiple MIDlets, and the user SHOULD be made aware that all of the MIDlets and associated RMS record stores are being removed.

If the Application Descriptor includes the attribute MIDlet-Delete-Confirm, its value SHOULD be included in the prompt. This will allow the MIDlet suite provider to highlight any specific conditions that might arise if the MIDlet suite were to be removed.

Installation/Deletion Status Reports

The success or failure of the installation, upgrade, or deletion of a MIDlet suite is of interest to the service providing the MIDlet suite. The service MAY specify URLs in the Application Descriptor that MUST be used to report installation and deletion status. See Additional Descriptor Attributes for more information. If the device cannot send the installation status report, the requested action MUST still be completed. For example, if the device cannot send the installation status report to the MIDlet-Install-Notify URL, the MIDlet suite MUST still be enabled, and the user MUST be allowed to use it. Likewise if the device cannot send the deletion status report to the MIDlet-Delete-Notify URL, the MIDlet suite MUST still be deleted.

The operation status is reported by means of an HTTP POST to the URL specified in the MIDlet-Install-Notify attribute for installations, or the MIDlet-Delete-Notify attribute for deletions. The only protocol that MUST be supported is "http://". Other protocols MAY be ignored by the device.

The content of the body of the POST request MUST include a status code and status message on the first line. See Status Codes and Message for list of valid codes and status messages.

In the case of a deletion status report, the notification is sent only when the MIDlet is deleted; Status Code 912 MUST be sent, notifying that the deletion occurred.

In response to a status report, the server MUST reply with a "200 OK" response. No content SHOULD be returned to the device and, if any is sent, it MUST be ignored. If a response is received the request SHOULD NOT be retried. Contrary to the MIDP 1.0 OTA Recommended Practice, the server MUST NOT include a Set-Cookie header with the attribute Max-Age=0 to request that the cookie be discarded. If such an attribute is received, the device MUST ignore it. As an example, please see Example: Install Status via HTTP Post Request.

For installations, if the status report cannot be sent, or if the server reply is not received, the installation status report MAY be sent again (as described above) each time a MIDlet in this suite is executed and the device has data network connectivity. This will improve the likelihood of the status report being successfully sent. The number of retries attempted SHOULD be kept small since each one may result in a charge to the user's bill. The MIDlet suite MUST be made available for use, whether or not the installation status report has been successfully sent and the acknowledgement have been received.

For deletions, an attempt to send the status report MUST be made the next time either an OTA installation is performed or an installation status report is being sent. This will improve the likelihood of the status report being successfully sent and will minimize confusion by the user when they see network activity. If the status report cannot be sent, or if the server reply is not received, the deletion status report MAY be sent again (as described above) each time an OTA installation installation is performed or an installation status report is being sent. The number of retries attempted SHOULD be kept small since each one may result in a charge to the user's bill. The MIDlet suite MUST be removed from memory, whether or not the installation status report has been successfully sent and the acknowledgement have been received.

Additional Descriptor Attributes

The following additional attributes are defined in the Application Descriptor. Each may appear only once in the descriptor.

Device Identification and Request Headers

The process of discovering a MIDlet suite via the DA can be customized by the device sending information about itself to the server. The DA MUST provide the network server with information (e.g. the manufacturer and device model number) so that the server can determine the device's capabilities. In many cases, a DA will already have identified the device type to the server by means consistent with its network connection and markup language.

During the download of a MIDlet suite, a device SHOULD identify its characteristics and the type of the content being requested as completely as possible to the server. The HTTP request-headers used to fetch the content MUST include, User-Agent, Accept-Language, and Accept. Servers SHOULD use this additional information to select the appropriate Application Descriptor for the device.

User-Agent Product Tokens

The MIDP specification identifies HTTP User-Agent request headers to identify the client to the server. RFC2616 specifies a format for product tokens such as:

"User-Agent" ":" 1*(product | comment)

The product tokens used to identify the device as supporting CLDC and MIDP are specified the Networking portion of the MIDP specification. As in RFC2616, the comment field is optional.

In addition, the device SHOULD further identify itself by adding a device-specific product token to the User-Agent header as defined by RFC2616. The device-identifying token SHOULD be the first token. The product-token and product-version values are specific to each device and are outside of the scope of this specification.

Accept-Language Header

The device MAY supply the Accept-Language request-header as specified in RFC2616 to indicate the language that is in use on the device.

Accept Header

The Accept HTTP header is used to indicate the type of content being requested. When requesting MIDlet suites, this header SHOULD include application/java-archive. For retrieving application descriptors, this header SHOULD include text/vnd.sun.j2me.app-descriptor.

Example: HTTP Request for Application Descriptor

When requesting the download of an Application Descriptor, the request headers might look as follows:

GET http://host.foo.bar/app-dir/game.jad HTTP/1.1
Host: host.foo.bar
Accept: text/vnd.sun.j2me.app-descriptor
User-Agent: CoolPhone/1.4 Profile/MIDP-2.0 Configuration/CLDC-1.0
Accept-Language: en-US, fi, fr
Accept-Charset: utf-8

The response headers from the server might look as follows:

HTTP/1.1 200 OK
Server: CoolServer/1.3.12
Content-Length: 2345
Content-Type: text/vnd.sun.j2me.app-descriptor; charset=utf-8

Example: HTTP Request to Install/Update a MIDlet suite

When requesting the download of a MIDlet suite JAR file, the request headers might look as follows:

GET http://host.foo.bar/app-dir/game.jar HTTP/1.1
Host: host.foo.bar
Accept: application/java, application/java-archive

The response headers from the server might look as follows:

HTTP/1.1 200 OK
Server: CoolServer/1.3.12
Content-Length: 25432
Content-Type: application/java-archive

Example: Install Status via HTTP Post Request

For example, installing a MIDlet suite with an application descriptor given below:

...
MIDlet-Install-Notify: http://foo.bar.com/status
...

After a successful install of the MIDlet suite, the following would be posted:

POST http://foo.bar.com/status HTTP/1.1
Host: foo.bar.com
Content-Length: 13
900 Success

The response from the server might be:

HTTP/1.1 200 OK
Server: CoolServer/1.3.12

Section 2, MIDP Provisioning and Networking in the WAP June2000 Environment

Purpose of This Section

The purpose of this section is to complement the OTA and MIDP specifications by providing requirements and recommendations specific to MIDP Over The Air Provisioning and MIDlet networking in the WAP June2000 environment. Future WAP developments will be addressed in future versions of the MIDP. Following these recommendations will help ensure interoperability between different WAP elements from all manufacturers. It will also provide guidance to network operators in deploying MIDP services when provisioning is performed via a browser using the WAP protocol stack, as well as to MIDlet developers in creating MIDlets that function optimally when the transport is WSP.

Overview

MIDlet suites are downloaded using HTTP from a provisioning server (possibly via a gateway in between). Also, the MIDP library MUST support network access in the form of the HTTP/1.1 protocol.

Depending on the end-user device and the wireless network, the communication MAY occur between the end-user device and provisioning server with the HTTP protocol end-to-end, or the end-user device MAY use another protocol, and have a gateway convert this protocol to HTTP. The provisioning server needs to only support HTTP in any case (unless there are other reasons for the same service provider to operate the protocol gateway as well). In WAP June2000 environments, there is always a WAP gateway between the terminal and the provisioning server to translate between the WSP protocol used to communicate with the device and TCP/IP used to communicate with the server.

There are essentially two basic interfaces that need to be considered:

• the interface from the end-user device to the network
• the interface from the provisioning server to the network

The latter of these interfaces will always be HTTP carried as usual over TCP/IP.

For the former interface, this document describes one of the two basic cases:

• the end-user device uses a browser using the WAP protocol stack and
• the WSP protocol is used for communication between the terminal and the WAP gateway.

When the end-user device uses a browser using the WAP protocol stack and has the WAP transport protocols, WSP MAY be used instead of HTTP in the end-user device. Only connection-oriented WSP and only the following WAP protocol stack configurations and bearers are supported:

• WAP/UDP/IPv4/PPP/CSD
• WAP/UDP/IPv4/GPRS

Where WAP can be either:

• WSP/WTP/WTLS, or
• WSP/WTP

(The other bearers in [WAP_WDPS.], such as SMS- or USSD -based bearers are not supported). These restrictions are made in order to achieve maximal interoperability in MIDP provisioning in WAP environments.

Depending on the wireless network and the capabilities of the end-user device, different mechanisms for obtaining the IP connection are used. These mechanisms and their required configurations are outside the scope of this document.

Terminal Requirements and Recommendations

This section lists the requirements and recommendations related to the WAP terminals. In the case of common requirements to both terminals and gateways, the requirements and recommendations are listed in both terminal and gateway sections.

WAP terminals used MUST be WAP June2000 conformant.

Specifically, the following issues are critical:

• JAD and JAR MIME-types, as described in previous sections, MUST be supported.
• HTTP authentication (server responses 401 and 407) MUST be supported.
• POST-messages from the terminal to provisioning server MUST be supported.

Requirements and recommendations in addition to those in the WAP Specifications

In the case where the HTTP connections are implemented over WSP, the system implementation of HTTP MUST add the request header "Accept: */*" to GET and POST requests when a MIDlet creates an HTTP-request, but the MIDlet does not include a non-empty Accept header in the request. This ensures that the WAP Gateway will always have an explicit set of types and will pass the requested data. This is conceptually the same as leaving out the Accept header for its HTTP-request, no change is made (the MIDlet's own Gateway Requirements and Recommendations

This section lists the requirements and recommendations related to the WAP gateways. The purpose of presenting these issues here is to make sure that they are taken into consideration when WAP-based MIDlet provisioning is considered.