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

Addendum to JSR 75 PIM API Specification

Copyright © 2003-2004, PalmSource, Inc.  All Rights Reserved.

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

Preface

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 PIM APIs on a MIDP 2.0 implementation are expected to comply with this addendum for a standardized and consistent security framework.

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 PIM 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 PIM 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 PIM APIs within the MIDP 2.0 security model.

Permissions

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 PIM APIs, and the API methods that are protected by those permissions:

Table 1: PIM Permissions and Protected Methods

Note that the following protected API calls from the Table 1 require both read and write permissions for their perspective lists:

openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE)
openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE)
openPIMList(PIM.TODO_LIST, PIM.READ_WRITE)
openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE, java.lang.String)
openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE, java.lang.String)
openPIMList(PIM.TODO_LIST, PIM.READ_WRITE, java.lang.String)

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  openPIMList method allows the application to read/write to any PIM list, not just the PIM list  sepcified by 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 PIM list 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 PIM 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 PIM 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.