Trusted MIDlet Suite Security Model

18.3.1 Permissions

Permission Names

The names of permissions are case-sensitive and have a hierarchical organization similar to package names in the Java™ programming language. The names of the permissions for an API must begin with the package name of the API. If the permission is for functionality provided by a specific class in the package, then the permission must begin with both the package and class names. Any additional modifiers may be appended after a period (.) separator.

The set of valid characters for permission names is the same as the set for package and class names. Permission names should use the same conventions for capitalization as package names.

For example, javax.microedition.io.Connector.datagram is the permission that protects the use of datagram functionality. As the permission name indicates, the class javax.microedition.io.Connector (a static factory class for creating new connection objects) provides the datagram connection. The class also provides connection objects for other protocols, hence the period followed by the modifier datagram in the permission name.

Creating New Permissions

Each API that provides access to protected functionality defines its own permissions. The MIDP Specification version 2.0 defines permissions for its protected APIs. APIs defined outside of the MIDP Specification version 2.0 must have a single document that specifies any necessary permissions and the behavior of the API when it is implemented for MIDP 2.0.

18.3.2 Requesting Permissions for a MIDlet Suite

A MIDlet suite might require access to some protected APIs or functions and consider access to others optional. A MIDlet suite that requires access to protected APIs or functions must request the corresponding permissions by listing them in the MIDlet-Permissions attribute of its JAR manifest or application descriptor (JAD). A MIDlet should list permissions using this attribute only if the permissions are critical to the function of the MIDlet suite (that is, the MIDlet will not operate correctly without them).

A MIDlet suite that can use protected APIs, but can function correctly without them, should request the corresponding permissions by listing them in the MIDlet-Permissions-Opt attribute of its JAR manifest or application descriptor. The MIDlet suite should be able to run with reduced functionality without these non-critical permissions. For example, perhaps the user can play a game MIDlet as a single-player game if the permissions cannot be granted, instead of as a network-aware game.

For example, to require permission to be launched for an alarm (a PushRegistry function) and to conditionally require a SecureConnection, a MIDlet suite would use the following attribute-value pairs in its JAR manifest or application descriptor:

MIDlet-Permission: javax.microedition.io.PushRegistry
MIDlet-Permission-Opt: javax.microedition.io.Connector.ssl

Multiple permissions are separated by a comma. Leading and trailing white space and tabs are ignored.

18.3.3 Protection Domain

A User permission requires the user to either deny permission to use a specific API or function or to grant permission by choosing one of the following interaction modes:

• blanket: Grants permission for every invocation of an API or function by the MIDlet suite until it is uninstalled or the permission is changed by the user.

• session: Grants permission for invocations of an API or function by the MIDlet until the MIDlet terminates. A session interaction mode must prompt the user on or before the first invocation of the protected API or function. When the user relaunches the MIDlet suite, the prompt must be repeated.

• oneshot: Grants permission for only the current invocation of an API or function. A oneshot interaction mode must prompt the user on each invocation of the protected API or function.

The security policy of the device implementation determines the choice of interaction modes for user permissions. The policy defines, for each user permission, the default interaction mode and a set of other interaction modes from which the user may choose. The implementation may offer the user the default interaction mode if it is supplied.

18.3.5 Granting Permissions to Trusted MIDlet Suites

The process of authorizing a MIDlet suite is established by the relationships between:

• A set of permissions for the protected APIs and functions on the device. This is a union of all permissions defined by every API on the device for protected functions.

• A protection domain consisting of a set of Allowed and User permissions.

• A set of permissions requested by the MIDlet suite in the MIDlet-Permissions and MIDlet-Permissions-Opt attributes of its JAR manifest or application descriptor.

• The user who may be asked to grant permissions.

To authorize a trusted MIDlet suite, the MIDlet suite must be in a protection domain. In addition, the MIDP implementation must have gotten the critical and non-critical permission requests from its JAR manifest or application descriptor, and must remove from consideration any non-critical permissions that are unknown to it. The permissions that can be granted to the MIDlet suite are the intersection of the requested permissions with the union of the Allowed and user-granted permissions in the protection domain.

A MIDP implementation authorizes a MIDlet suite for the first time when the user tries to install it. The MIDlet suite must meet the following authorization requirements, or it will not be installed:

• If the MIDlet-Permissions and MIDlet-Permissions-Opt attributes are in both the application descriptor and in the JAR manifest, their values must be identical. If the values are not identical, the system will not install the MIDlet suite.

• All requested critical permissions must be known to the implementation. If any of the requested critical permissions are unknown, the MIDlet suite is not installed and cannot be launched.

• All requested critical permissions must be present in the protection domain. If any of the requested critical permissions are not present in the protection domain, the MIDlet suite is not installed and cannot be launched.

A MIDP implementation also authorizes a MIDlet suite when it tries to access a protected API. (During execution, protected APIs must check for the appropriate permissions.) If the MIDlet's protection domain protects the security-sensitive API with a User permission, the user must provide authorization in order to grant those permissions to the MIDlet suite. The MIDP implementation is responsible for making the request to the user and getting the response to allow or deny the request. When the implementation prompts the user, it should provide a description of the requested permissions that is clear enough to enable a well-informed choice. The user must always be able to deny permission.

The result of a successful authorization is that the MIDlet suite is granted access to the protected API. If the permission was not granted, the protected API must throw a SecurityException.