# Security for MIDP Applications

The MIDP 1.0 specification constrained each MIDlet suite to operate in a sandbox wherein all of the APIs available to the MIDlets would prevent access to sensitive APIs or functions of the device. That sandbox concept is used in this specification and all untrusted MIDlet suites are subject to its limitations. Every implementation of this specification MUST support running untrusted MIDlet suites.

MIDP 2.0 introduces the concept of trusted applications that may be permitted to use APIs that are considered sensitive and are restricted. If and when a device determines that a MIDlet suite can be trusted then access is allowed as indicated by the domain policy. The Trusted MIDlet Suite Security section below describes the concepts. Any MIDlet suite that is not trusted by the device MUST be run as untrusted. If errors occur in the process of verifying that a MIDlet suite is trusted then the MIDlet suite MUST be rejected.

## Untrusted MIDlet Suites

An untrusted MIDlet suite is a MIDlet suite for which the origin and the integrity of the JAR file can NOT be trusted by the device. 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. Any MIDP 1.0 compliant MIDlet suite MUST be able to run in an implementation of this specification as untrusted. Any APIs or functions of this specification which are not security sensitive, having no permissions defined for them, are implicitly accessible by both trusted and untrusted MIDlet suites. Untrusted MIDlet suites do not request permissions explicitly in the JAR manifest or application descriptor.

The untrusted domain for untrusted MIDlet suites MUST allow, without explicit confirmation by the user, access to:

API | Description
--- | ---
`javax.microedition.rms` | RMS APIs
`javax.microedition.midlet` | MIDlet Lifecycle APIs
`javax.microedition.lcdui` | User Interface APIs
`javax.microedition.lcdui.game` | The Game APIs
`javax.microedition.media` `javax.microedition.media.control` | The multi-media APIs for playback of sound

The untrusted domain for untrusted MIDlet suites MUST allow, with explicit confirmation by the user, access to protected APIs or functions:

API | Protocol
--- | ---
`javax.microedition.io.HttpConnection` | `http`
`javax.microedition.io.HttpsConnection` | `https`

## Trusted MIDlet Suite Security

Security for Trusted MIDlet suites is based on protection domains. Each protection domain defines the permissions that may be granted to a MIDlet suite in that domain. The protection domain owner specifies how the device identifies and verifies that it can trust a MIDlet suite and bind it to a protection domain with the permissions that authorize access to protected APIs or functions. The mechanisms the device uses to identify and trust MIDlet suites are defined separately to allow them to be selected appropriately to the device, network, and business case.

The Trusted MIDlet Suites Using X.509 PKI describes a mechanism for identifying trusted MIDlet suites though signing and verification. If an implementation of this specification will recognize MIDlet suites signed using PKI as trusted MIDlet suites they must be signed and verified according to the formats and processes specified in Trusted MIDlet Using X.509 PKI.

### Definition of Terms

Term | Definition
--- | ---
Protection Domain | A set of Allowed and User permissions that may be granted to a MIDlet suite
Permission | A named permission defined by an API or function to prevent it from being used without authorization
Trusted MIDlet Suite | A MIDlet suite for which the authentication and the integrity of JAR file can be trusted by the device and bound to a protection domain

## Authorization Model

The basic authorization of a MIDlet suite is established by the relationships between the following elements:

- A protection domain consisting of a set of Allowed and User permissions
- A set of permissions requested by the MIDlet suite in `MIDlet-Permissions` and `MIDlet-Permissions-Opt` attributes
- A set of permissions for each protected API or function on the device which is a union of all permissions defined by every API on the device for protected functions
- The user who may be asked to grant permissions

### Assumptions

- MIDlets do not need to be aware of the security policy except for security exceptions that may occur when using APIs.
- A MIDlet suite is subject to a single protection domain and its permissible actions.
- The internal representation of protection domains and permissions is implementation specific.
- The details of how authentication results and configuration settings are presented to the user in the user interface are implementation dependent and are outside the scope of this specification.
- The device must protect the security policy and protection domain information stored in the device from viewing or modification except by authorized parties.
- If the security policy for a device is static and disallows use of some functions of the security framework then the implementation of unused and inaccessible security functions may be removed.
- Security policy allows an implementation to restrict access but MUST NOT be used to avoid implementing functionality. For example, unimplemented protocols under the Generic Connection framework MUST throw `ConnectionNotFoundException`.

### Permissions

Permissions are the means to protect access to APIs or functions which require explicit authorization before being invoked. Permissions described in this section only refer to those APIs and functions which need security protection and do not refer to other APIs which can be accessed by both trusted and untrusted MIDlet suites and do not need explicit permission. Permissions are checked by the implementation prior to the invocation of the protected function.

The names of permissions have a hierarchical organization similar to Java package names. The names of permissions are case sensitive. All of the permissions for an API MUST use the prefix that is the same as the package name of the API. If the permission is for a function of a specific class in the package then the permission MUST include the package and classname. The set of valid characters for permissions is the same as that for package and class names. The conventions for use of capitalization in package names SHOULD be used for permission names. For example, `javax.microedition.io`. Following the permission name, whether by package or class, additional modifiers may be appended with a separator of "." (Unicode U+002E).

Each API in this specification that provides access to a protected function will define the permissions. 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.

### Permissions for Protected Functions

Each function (or entire API) which was identified as protected must have its permission name defined in the class or package documentation for the API.

Refer to the documentation of the `javax.microedition.io` package for permissions on all Generic Connection schemes defined in this specification. All APIs and functions within this specification that do not explicitly define permissions MUST be made available to all trusted and untrusted MIDlet suites.

### Requesting Permissions for a MIDlet Suite

A MIDlet suite that requires access to protected APIs or functions must request the corresponding permissions. Permissions requested can be required by listing the permissions in the attribute `MIDlet-Permissions`. These permissions are critical to the function of the MIDlet suite and it will not operate correctly without them.

If the MIDlet suite can function correctly with or without particular permission(s) it should request them using the `MIDlet-Permissions-Opt` attribute. The MIDlet suite is able to run with reduced functionality (for example, as a single player game instead of a net game) without these non-critical permissions and MUST be installed and run.

The `MIDlet-Permissions` and `MIDlet-Permissions-Opt` attributes contain a list of one or more permissions. Multiple permissions are separated by a comma (Unicode U+002C). Leading and trailing whitespace (Unicode U+0020) and tabs (Unicode U+0009) are ignored.

### Permissions on the Device

Each device that implements this specification and any other Java APIs will have a total set of permissions referring to protected APIs and functions. It is the union of all permissions defined by every protected function or API on the device.

### Protection Domain

A protection domain defines a set of permissions and related interaction modes. A protection domain consists of:

- a set of permissions that should be allowed (Allowed)
- a set of permissions that the user may authorize (User); each with its user interaction mode

Within a protection domain each permission may be either allowed or user but not both.

The Allowed permissions are any permissions which explicitly allow access to a given protected API or function on the basis of MIDlet suite being associated with the protection domain. Allowed permissions do not require any user interaction.

The User permissions are any permissions for a protected API or function on the basis of MIDlet suite being bound to the protection domain and will allow access to protected API or function after the prompt given to the user and explicit user permission being granted.

### User Permission Interaction Modes

A User Permission is defined to allow the user to deny permission or to grant permission to a specific API with one of the following interaction modes:

- "`blanket`" is valid for every invocation of an API by a MIDlet suite until it is uninstalled or the permission is changed by the user.
- "`session`" is valid from the invocation of a MIDlet suite until it terminates. "`session`" mode MUST prompt the user on or before the first invocation of the API or function which is protected. When the user re-invokes the MIDlet suite the prompt MUST be repeated.
- "`oneshot`" MUST prompt the user on each invocation of the API or function which is protected.

The choice of user permission interaction modes is driven by the security policy and the device implementation. Each user permission has a default interaction mode and a set of other available interaction modes. The user SHOULD be presented with a choice of interaction modes. The default interaction mode may be offered if it is supplied. The user MUST always be able to deny permission.

If and when prompted, the user SHOULD be provided with a user friendly description of the requested permissions sufficient to make a well-informed choice.

The range of blanket to oneshot action permission modes represents a tradeoff between usability and user notification and should behave smoothly and consistently with the human interface of the device.

### Granting Permissions to Trusted MIDlet Suites

Authorization of trusted MIDlet suites uses protection domain information, permissions on the device, and permissions requested in the MIDlet suite. Permissions in the domain are Allowed or User. Permissions requested by the application are either critical or non-critical.

To establish the permissions granted to a trusted MIDlet suite when it is to be invoked all of the following MUST be true:

- The MIDlet suite must have been bound to a protection domain.
- The requested critical permissions are retrieved from the attributes `MIDlet-Permissions` and non-critical permissions from `MIDlet-Permissions-Opt`. If these attributes appear in the application descriptor they MUST be identical to corresponding attributes in the manifest. If they are not identical, the MIDlet suite MUST NOT be installed or invoked.
- If any of the requested permissions are unknown to the device and are not marked as critical then they are removed from the requested permissions.
- If any of the requested permissions are unknown to the device and marked as critical, the MIDlet suite MUST NOT be installed or invoked.
- If any of the requested permissions are not present in the protection domain (Allowed or User) permission sets and the requested permission was marked as critical then the MIDlet suite does not have sufficient authorization and MUST NOT be installed or invoked.
- If any of the requested permissions are not present in the protection domain (Allowed or User) permission sets, and the requested permissions are not marked as critical, the application MUST still be installed and MUST be able to be invoked by the user.
- If any of the requested permissions match the User permissions of the protection domain then the user MUST explicitly provide authorization to grant those permissions to the MIDlet suite. The implementation is responsible for making the request to the user and getting the response to allow or deny the request.
- The permissions granted to the MIDlet suite are the intersection of the requested permissions with the union of the allowed and user granted permissions.
- During execution, any protected APIs MUST check for the appropriate permissions and throw a `SecurityException` if the permission has not been granted.

The successful result of authorization is that the MIDlet suite is granted access to protected APIs or functions for which it requested permissions.

### Example External Domain Policy Format

An external representation for protection domains allows clear communication between developers, operators and manufacturers. This format is provided only as an example. There is no requirement for an implementation of this specification to use this format. The policy file character set is UTF-8 encoding of Unicode to support any language. The policy file syntax is based on the JAR manifest format.

A policy consists of the definitions of domains and aliases. Each domain consists of the definition of granted permissions and user permissions. Aliases permit groups of named permissions to be reused in more than one domain and helps keep the policy compact. Aliases may only be defined and used within a single policy file. References to an alias MUST follow the definition of the alias in the policy file.

A domain is defined with a domain identifier and a sequence of permissions. The domain identifier is implementation specific. Each permission line begins with "`allow`" or user permissions "`blanket`", "`session`", or "`oneshot`" to indicate the interaction level for the list of permissions that follow. User permissions may also include a default mode. Multiple permission lines are allowed. The permissions are processed in order and if a permission occurs multiple times within a domain only the last definition of the permission is used. It is not recommended that permissions appear more than once.

BNF Syntax:

        policy_file = 1*(directive)

        directive = (domain_def | alias_def) [newlines]

        domain_def = "domain:" *WS domain_id *WS newlines
                     1*permission

        domain_id = 1*<any Unicode char and continuation, but not newline>

        permission = permision_level ":" api_names newlines

        api_names: *WS alias_or_name *(*WS "," *WS alias_or_name) *WS

        alias_or_name = alias_ref | api_name

        alias_ref = <alias_name from a previous alias_def in the same policy_file>

        permission_level = allow | user_permission_levels

        user_permision_levels = highest_level ["(" default_level ")"]

        highest_level = user_permission_level

        default_level = user_permision_level ; cannot be greater the highest_level

        user_permission_level = blanket | session | oneshot

        allow = "allow" ; allow access without asking the user.

        blanket = "blanket" ; Allow access, do not ask again.
                            ; Include session and oneshot when asking.

        session = "session" ; Allow access, ask again at next MIDlet suite startup.
                            ; Include oneshot when asking.

        oneshot = "oneshot" ; Allow access, ask again at next use.
                              ; If no default provided, default is to deny access.

        alias_def = "alias:" *WS alias_name 1*WS alias_api_names

        alias_api_names =  api_name
                            *(*WS "," *WS api_name) *WS newlines

        alias_name = java_name

        api_name = java_class_name

        WS = continuation | SP | HT

        continuation = newline SP

        newlines = 1*newline  ; allow blank lines to be ignored

        newline = CR LF | LF | CR <not followed by LF>

        CR = <Unicode carriage return (U+000D)>

        LF = <Unicode linefeed (U+000A)>

        SP = <Unicode space (U+0020)>

        HT = <Unicode horizontal-tab (U+0009)>

        java_name = 1*<characters allowed in a java_class_name except for ".">

        java_class_name = 1*<characters allowed in a Java class name>

Example policy file:

        domain: O="MIDlet Underwriters, Inc.", C=US
        allow: javax.microedition.io.HttpConnection
        oneshot(oneshot): javax.microedition.io.CommConnection

        alias: client_connections javax.microedition.io.SocketConnection,
          javax.microedition.io.SecureConnection,
          javax.microedition.io.HttpConnection,
          javax.microedition.io.HttpsConnection

        domain: O=Acme Wireless, OU=Software Assurance
        allow: client_connections
        allow: javax.microedition.io.ServerSocketConnection,
          javax.microedition.io.UDPDatagramConnection
        oneshot(oneshot): javax.microedition.io.CommConnection

        domain: allnet
        blanket(session): client_connections
        oneshot: javax.microedition.io.CommConnection