authorization.html

是MIDP 的API 查詢文件, 大家可以看一下裡面的index.html, 再用Package 或 Class 名字來查.

      in the attribute <CODE>MIDlet-Permissions</CODE>. These
      permissions are critical to the function of the MIDlet suite and
      it will not operate correctly without them.</P>

    <P>If the MIDlet suite can function correctly with or
      without particular permission(s) it should request them
      using the <CODE>MIDlet-Permissions-Opt</CODE> 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.</P> 

    <P>The <CODE>MIDlet-Permissions</CODE> and
      <CODE>MIDlet-Permissions-Opt</CODE> 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.</P> 


    <H3>Permissions on the Device</H3>
    <P>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.
    </P>

    
    <H3><A NAME=domain>Protection Domain</A></H3>

    <P>A protection domain defines a set of permissions and related
      interaction modes.  A protection domain consists of:</P>

    <UL>
      <LI>a set of permissions that should be allowed (<EM>Allowed</EM>)
      </LI>
      <LI>a set of permissions that the user may authorize (<EM>User</EM>);
	each with its user interaction mode</LI>
    </UL>

    <P>Within a protection domain each permission may be either
      <EM>allowed</EM> or <EM>user</EM> but not both.
    </P>

    <P>The <em>Allowed</em> 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.  <em>Allowed</em> permissions do not require
      any user interaction.</P>

    <P>The <em>User</em> 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.</P>


    <H3>User Permission Interaction Modes</H3>
    <P>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:
    </P>
    <UL>
      <LI>"<CODE>blanket</CODE>" is valid for every invocation of an
	API by a MIDlet suite until it is uninstalled or the
	permission is changed by the user.
	
      </LI>
      <LI>"<CODE>session</CODE>" is valid from the invocation of a
	MIDlet suite until it terminates.  "<CODE>session</CODE>"
	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.
      </LI>
      <LI>"<CODE>oneshot</CODE>" MUST prompt the user on each
	invocation of the API or function which is protected.
      </LI>
    </UL>

    <P>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.
    </P>

    <P>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.
    </P>

    <P>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.
    </P>


    <H3><A NAME=grant>Granting Permissions to Trusted MIDlet Suites</A></H3>
    <P>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
      <em>Allowed</em> or <em>User</em>. Permissions requested by the
      application are either critical or non-critical.</P>

    <P>To establish the permissions granted to a trusted MIDlet suite
      when it is to be invoked all of the following MUST be true: 
    </P>
    <UL>
      <LI>The MIDlet suite must have been bound to a protection domain.
      </LI>
      <LI>The requested critical permissions are retrieved from the
	attributes <CODE>MIDlet-Permissions</CODE>
        and non-critical permissions from
        <CODE>MIDlet-Permissions-Opt</CODE>.
	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.
      </LI>
      <LI>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.
      </LI>
      <LI>If any of the requested permissions
	are unknown to the device and marked as critical,
	the MIDlet suite MUST NOT be installed or invoked.</LI> 
      <LI>If any of the requested
	permissions are not present in the protection domain
	(<em>Allowed</em> or <em>User</em>) 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. 
      </LI>
      <LI>If any of the requested permissions are not present in the
	protection domain (<em>Allowed</em> or <em>User</em>) 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. 
      </LI>
      <LI>If any of the requested
	permissions match the <EM>User</EM> 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.
      </LI>
      <LI>The permissions granted to the
	MIDlet suite are the intersection of the requested permissions with
	the union of the allowed and user granted permissions.
      </LI>
      <LI>During execution, any protected APIs MUST check for the
	appropriate permissions and throw a
	<CODE>SecurityException</CODE> if the permission has not been
	granted.
      </LI>
    </UL>

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

    <H3><A NAME="policyfile">Example External Domain Policy Format</A></H3>
    <P>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.
    </P>

    <P>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.
    </P>

    <P>A domain is defined with a domain identifier and a sequence of
      permissions. The domain identifier is implementation specific.
      Each permission line begins with
      "<CODE>allow</CODE>" or user permissions "<CODE>blanket</CODE>",
      "<CODE>session</CODE>", or "<CODE>oneshot</CODE>" 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.
    </P>

    <P>BNF Syntax:</P>
    <PRE>
    policy_file = 1*(directive)

    directive = (domain_def | alias_def) [newlines]

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

    domain_id = 1*&lt;any Unicode char and continuation, but not newline&gt;

    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 = &lt;alias_name from a previous alias_def in the same policy_file&gt;

    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 &lt;not followed by LF&gt;

    CR = &lt;Unicode carriage return (U+000D)&gt;

    LF = &lt;Unicode linefeed (U+000A)&gt;

    SP = &lt;Unicode space (U+0020)&gt;

    HT = &lt;Unicode horizontal-tab (U+0009)&gt;

    java_name = 1*&lt;characters allowed in a java_class_name except for "."&gt;

    java_class_name = 1*&lt;characters allowed in a Java class name&gt;

    </PRE>

    <P>Example policy file:</P>
    <PRE>
    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,