Recommended Practices - Implementation of FileConnection APIs within JSR 118 Security Models

Addendum to JSR 75 FileConnection API Specification

Copyright 2002-2004, PalmSource, Inc.  All Rights Reserved.

Version 1.0, Proposed Final Draft, 06/30/2003.


JSR 118 (also known as MIDP 2.0) is a profile that contains its own security policy.  Its security policy is open ended in the sense that optional packages that are included in an implementation with it are capable of defining how the optional packages' restricted APIs are used within the MIDP security model. 

This addendum is informative. However, all implementations of the JSR 75 FileConnection APIs on a MIDP 2.0 implementation are expected to comply with this addendum for a standardized and consistent security framework.


The term "file://..." is used as a placeholder to represent any properly formed file URI description.  It is not intended to be taken literally as a valid URI.

Untrusted MIDlet Suites

The MIDP 2.0 security policy defines an untrusted MIDlet suite to be "a MIDlet suite for which the origin and the integrity of the JAR file can NOT be trusted by the device". Furthermore, the MIDP 2.0 security policy requires that "untrusted MIDlet suites MUST execute in the untrusted domain using a restricted environment where access to protected APIs or functions either is not allowed or is allowed with explicit user permission".

In concordance with this security policy, it is defined that untrusted MIDlet suites that access the protected APIs and functions of the FileConnection APIs MUST be subject to explicit confirmation by the user (this is a similar policy surrounding the use of the http and https protocols).   This mandate conforms to requirements defined in both the FileConnection security policy and the MIDP 2.0 security policy.

Trusted MIDlet Suites

The MIDP 2.0 security policy states that "for APIs defined outside of MIDP 2.0 there must be a single document that specifies any necessary permissions and the behavior of the API when it is implemented on MIDP 2.0".  This document describes the permissions that are applicable to the FileConnection APIs within the MIDP 2.0 security model.


Permissions are the MIDP 2.0 mechanism by which a MIDlet may request security access to protected APIs or functions.  A MIDlet can request access by including the permissions in the MIDlet-Permissions and MIDlet-Permissions-Opt attributes in its JAD or manifest.  Table 1 defines the permissions applicable to the FileConnection APIs, and the API methods that are protected by those permissions:

Table 1: FileConnection Permissions and Protected Methods

Permission Protected API Calls methods:
   open("file://...", Connector.READ)
   open("file://...", Connector.READ_WRITE)
   openInputStream("file://...") methods:
   setFileConnection, when instance opened with READ
   setFileConnection, when instance opened with READ_WRITE methods:
   listRoots methods:
   open("file://...", Connector.WRITE)
   open("file://...", Connector.READ_WRITE)
   openOutputStream("file://...") methods:
   setFileConnection, when instance opened with WRITE
   setFileConnection, when instance opened with READ_WRITE

Note that the following protected API calls from the Table 1 require both read and write permissions:"file://...")"file://...", Connector.READ_WRITE)
if the FileConnection instance is opened in READ_WRITE

Permission Scope

It should be noted that the permissions protect API calls, regardless of the data that is being accessed.  For example, a successful grant of READ_WRITE access to the"file://...") method allows the application to read/write any file or directory, not just the file/directory used as the method's parameter.  The parameters of the API calls (which indicate the data being accessed)  is not a factor at all in the granting of the permissions, as dictated by MIDP 2.0 security definitions.   For this reason, it is recommended that a user interaction mode of "one-shot" be used when user authorization is required so that the user is notified on every instance that a file or directory is accessed.

Implementation Additions

This recommended practice specifies security based on API access, consistent with the MIDP 2.0 security model.  Additionally, if an implementation wishes to have a more granular security model (for example, a model based per file or directory), then the implementation may provide a more granular security model as long as all recommended practices from this document and the MIDP 2.0 security model are also adhered to. 

MIDP 2.0 GSM/UMTS Recommended Security Model

The MIDP 2.0 specification additionally includes a recommended practices document describing the recommended security model for implementing MIDP 2.0 on GSM/UMTS devices.  This section describes how the FileConnection APIs can be fit into that recommended security model.  Note that this section is for GSM/UMTS devices only, and is not applicable to MIDP 2.0 implementations on devices not supporting those protocols.

All previously defined recommended practices for the FileConnection APIs in the MIDP 2.0 security model are also applicable in this instance.

Function Groups

The GSM/UMTS Recommended Security model indicates that permissions should be, but are not required to be, mapped to a defined function group in the recommended model for user convenience.   This document recommends that the permissions not be mapped to any of the function groups listed in the GSM/UMTS Recommended Security, but rather leave it to the implementation to choose how the permissions are presented to the user and what the default interaction modes are for the permissions.