Appendix A. Security

This appendix defines the permissions to protect the access to the RFID hardware. Permissions are checked by the platform prior to the access of the protected function. Some methods in this API are defined to throw a SecurityException if the caller does not have the permissions needed to perform the action. This must be enforced by an appropriate security framework in the platform.

Using the MIDP 2.x Security Framework

Originally the MIDP security model was defined in the MIDP 2.x Specification and the Recommended Security Policy. The Java Technology for the Wireless Industry (JTWI), JSR 185 Specification defines the policy for the third-party domain ("untrusted domain"). The Mobile Service Architecture (MSA) makes the four protection domains defined in the MIDP 2.x mandatory and defines the recommended security policies for the domains. A MIDlet suite can belong to one of the four domains:

If this API is implemented on the MIDP 2.x platform, the security framework of MIDP 2.x must be used as defined below.

The table below defines the names of the permissions used and the methods that are protected by that permission.

The permissions must be placed into some function group. This specification does not mandate any particular function group. This is left to the Mobile Service Architecture work to decide.

Security on top of CDC configuration

Since the Contactless Communication API can be implemented on top of CDC configuration or in devices with MIDP 3 profile, this appendix defines the security permissions for that environment.

The implementations of Contactless Communication API on configurations and profiles that use the fine grained security permissions based on java.security.Permission security checks must include corresponding permission classes defined in this specification. The table below lists the methods that must perform permission checks and the required permission classes.

Below are the listings of the permission classes defined in this specification.

ContactlessPermission

        package javax.microedition.contactless;

import java.security.BasicPermission;
/**
 * <p>This permission class represents access rights to general functionality of
 * Contactless Communication API. Separate permission classes are defined for the
 * protocols used to open the connections to contactless targets. These
 * permission classes can be found from the separate target packages.</p>
 * 
 * <p>A <code>ContactlessPermission</code> contains a name (also referred to as 
 * a "target name") but no actions list. The protected API calls and 
 * corresponding target names are:</p>
 * 
 * <p>API call: <code>DiscoveryManager.getInstance</code><br>
 *     Permission target name: <code>discoveryManager.getInstance</code></p>
 * 
 * <p>API call: <code>NDEFTagConnection.write</code><br>
 *     Permission target name: <code>ndef.write</code></p>
 *
 * <table border=1 cellpadding=5 summary="API call, permission target name">
 * 	<tr>
 * 		<th>API call checking the permission</th>
 * 		<th>Permission target name</th>
 * 	</tr>
 *	<tr>
 * 		<td>DiscoveryManager.getInstance</td>
 * 		<td>discoveryManager.getInstance</td>
 * 	</tr>
 *  <tr>
 *  	<td>NDEFTagConnection.write</td>
 *  	<td>ndef.write</td>
 *  </tr>
 * </table>
 * 
 * <p>As defined for <code>BasicPermission</code> the naming follows the
 * hierarchical property naming convention. An asterisk may appear by itself, or
 * if immediately preceded by a "." may appear at the end of the name, to signify
 * a wildcard match.</p>
 * 
 * <p>The action string is unused.</p> 
 *
 * @author Nokia Corporation
 * @version 1.1
 */
public class ContactlessPermission extends BasicPermission {

	/**
	 * <p>Creates a new <code>ContactlessPermission</code> instance with the
	 * specified name. The name string should conform to the specification given
	 * in the class description and follow the naming conventions described in
	 * <code>BasicPermission</code> class.</p>
	 *  
	 * @param name the name of the permission
	 * @throws NullPointerException if <code>name</code> is <code>null</code>
	 * @throws IllegalArgumentException if <code>name</code> is an empty string
	 */
	public ContactlessPermission(String name) {
	}
	
	/**
	 * <p>Creates a new <code>ContactlessPermission</code> instance with the
	 * specified name. The name string should conform to the specification given
	 * in the class description and follow the naming conventions described in
	 * <code>BasicPermission</code> class. The <code>actions</code> parameter is
	 * unused and should be <code>null</code>.</p>
	 * 
	 * @param name the name of the permission
	 * @param actions ignored
	 * @throws NullPointerException if <code>name</code> is <code>null</code>
	 * @throws IllegalArgumentException if <code>name</code> is an empty string
	 */
	public ContactlessPermission(String name, String actions) {
	}
	
}

    

NDEFProtocolPermission

        package javax.microedition.contactless.ndef;

import java.security.Permission;
import java.security.PermissionCollection;

import javax.microedition.io.GCFPermission;

/**
 * <p>This class represents access rights to connections via the "ndef" protocol.
 * An <code>NDEFProtocolPermission</code> consists of a URI string but no actions
 * list.</p>
 *
 * <p>The URI takes the following general form:</p>
 * 
 * <pre>ndef://{address_part}</pre>
 * 
 * <p>The value of the <code>{address_part}</code> field is implementation specific.
 * This is because the URI is not visible to the application before an actual
 * target is available. The <code>{address_part}</code> field may also end with
 * an asterisk. An asterisk indicates a match with any address that begins with
 * the part left from the asterisk and is followed by zero or more additional
 * characters. The asterisk alone matches all addresses.</p>
 *  
 * @author Nokia Corporation
 * @version 1.1
 */
public final class NDEFProtocolPermission extends GCFPermission {

	/**
	 * <p>Constructs <code>NDEFProtocolPermission</code> with the specified URI as
	 * its name. The URI string <span class="keyword">should</span> conform to the
	 * specification given above.</p>
	 * 
	 * @param uri the URI string
	 * @throws IllegalArgumentException if <code>uri</code> is malformed
	 * @throws NullPointerException if <code>uri</code> is <code>null</code>
	 */
	public NDEFProtocolPermission(String uri) {
	}

	/**
	 * <p>Checks if the <code>NDEFProtocolPermission</code> object "implies" the
	 * specified permission. To determine whether this object implies another
	 * permission, <code>p</code>, this method checks that the following is
	 * true and returns <code>false</code> if it is not:</p>
	 * 
	 * <ul>
	 * 	<li><code>p</code> is an instanceof <code>NDEFProtocolPermission</code>,
	 * 		and</li>
	 * 	<li><code>p</code>'s name equals or (in the case of wildcards) is
	 * 		implied by this object's name.</li>
	 * </ul>
	 * 
	 * @param p the permission to check against
	 * @return <code>true</code> if the specified permission <code>p</code> is
	 * 				implied by this object, <code>false</code> if not
	 */
	public boolean implies(Permission p) {
	}
	
	/**
	 * <p>Returns the canonical string representation of the actions. Since there
	 * are no actions defined for <code>NDEFProtocolPermission</code> an
	 * empty string "" is returned.</p>
	 * 
	 * @return an empty string ""
	 */
	public String getActions() {
	}
	
	/**
	 * <p>Returns a new <code>PermissionCollection</code> for storing
	 * <code>NDEFProtocolPermission</code> objects.</p>
	 * 
	 * <p><code>NDEFProtocolPermission</code> object <span class="keyword">must</span>
	 * be stored in a manner that allows them to be inserted into the collection
	 * in any order, but that also enables the <code>PermissionCollection.implies</code>
	 * method to be implemented in an effective (and consistent) manner.</p>
	 * 
	 * @return a new <code>PermissionCollection</code> object suitable for storing
	 * 				<code>NDEFProtocolPermission</code> objects
	 */
	public PermissionCollection newPermissionCollection() {
	}
	
	/**
	 * <p>Checks two <code>NDEFProtocolPermission</code> objects for equality.</p>
	 * 
	 * @param obj the object whose equality with this object is tested
	 * @return <code>true</code> if <code>obj</code> is a
	 * 		   <code>NDEFProtocolPermission</code> and has the same URI string
	 *  	   as this <code>NDEFProtocolPermission</code> object
	 */
	public boolean equals(Object obj) {
	}

	/**
	 * <p>Returns the hash code value for this object.</p>
	 * 
	 * @return the hash code value for this object
	 */
	public int hashCode() {
	}
	
}

    

RFProtocolPermission

        package javax.microedition.contactless.rf;

import java.security.Permission;
import java.security.PermissionCollection;

import javax.microedition.io.GCFPermission;

/**
 * <p>This class represents access rights to connections via the "rf" protocol.
 * A <code>RFProtocolPermission</code> consists of a URI string but no actions
 * list.</p>
 *
 * <p>The URI takes the following general form:</p>
 * 
 * <pre>rf://{address_part}</pre>
 * 
 * <p>The value of the <code>{address_part}</code> field is implementation specific.
 * This is because the URI is not visible to the application before an actual
 * target is available. The <code>{address_part}</code> field may also end with
 * an asterisk. An asterisk indicates a match with any address that begins with
 * the part left from the asterisk and is followed by zero or more additional
 * characters. The asterisk alone matches all addresses.</p>
 * 
 * @author Nokia Corporation
 * @version 1.1
 */
public final class RFProtocolPermission extends GCFPermission {

	/**
	 * <p>Constructs <code>RFProtocolPermission</code> with the specified URI.
	 * The URI string <span class="keyword">should</span> conform to the
	 * specification given above.</p>
	 * 
	 * @param uri the URI for the protocol
	 * @throws IllegalArgumentException if <code>uri</code> is malformed
	 * @throws NullPointerException if <code>uri</code> is <code>null</code>
	 */
	public RFProtocolPermission(String uri) {
	}

	/**
	 * <p>Checks if the <code>RFProtocolPermission</code> object "implies" the
	 * specified permission. To determine whether this object implies another
	 * permission, <code>p</code>, this method checks that the following is
	 * true and returns <code>false</code> if it is not:</p>
	 * 
	 * <ul>
	 * 	<li><code>p</code> is an instanceof <code>RFProtocolPermission</code>, and</li>
	 * 	<li><code>p</code>'s name equals or (in the case of wildcards) is implied by
	 *      this object's name.</li>
	 * </ul>
	 * 
	 * @param p the permission to check against
	 * @return <code>true</code> if the specified permission <code>p</code> is
	 * 				implied by this object, <code>false</code> if not
	 */
	public boolean implies(Permission p) {
	}
	
	/**
	 * <p>Returns the canonical string representation of the actions. Since there
	 * are no actions defined for <code>RFProtocolPermission</code> an
	 * empty string "" is returned.</p>
	 * 
	 * @return an empty string ""
	 */
	public String getActions() {
	}
	
	/**
	 * <p>Returns a new <code>PermissionCollection</code> for storing
	 * <code>RFProtocolPermission</code> objects.</p>
	 * 
	 * <p><code>RFProtocolPermission</code> object <span class="keyword">must</span>
	 * be stored in a manner that allows them to be inserted into the collection
	 * in any order, but that also enables the <code>PermissionCollection.implies</code>
	 * method to be implemented in an effective (and consistent) manner.</p>
	 * 
	 * @return a new <code>PermissionCollection</code> object suitable for storing
	 * 				<code>RFProtocolPermission</code> objects
	 */
	public PermissionCollection newPermissionCollection() {
	}
	
	/**
	 * <p>Checks two <code>RFProtocolPermission</code> objects for equality.</p>
	 * 
	 * @param obj the object whose equality with this object is tested
	 * @return <code>true</code> if <code>obj</code> is a
	 * 		   <code>RFProtocolPermission</code> and has the same URI string as
	 * 		   this <code>RFProtocolPermission</code> object
	 */
	public boolean equals(Object obj) {
	}

	/**
	 * <p>Returns the hash code value for this object.</p>
	 * 
	 * @return the hash code value for this object
	 */
	public int hashCode() {
	}
	
}

    

SCProtocolPermission

        package javax.microedition.contactless.sc;

import java.security.Permission;
import java.security.PermissionCollection;

import javax.microedition.io.GCFPermission;

/**
 * <p>This class represents access rights to connections via the "sc" protocol.
 * A <code>SCProtocolPermission</code> consists of a URI string but no actions
 * list.</p>
 * 
 * <p>The URI takes the following general form:</p>
 * 
 * <pre>sc://{address_part}</pre>
 * 
 * <p>The value of the <code>{address_part}</code> field is implementation specific.
 * This is because the URI is not visible to the application before an actual
 * target is available. The <code>{address_part}</code> field may also end with
 * an asterisk. An asterisk indicates a match with any address that begins with
 * the part left from the asterisk and is followed by zero or more additional
 * characters. The asterisk alone matches all addresses.</p>
 * 
 * @author Nokia Corporation
 * @version 1.1
 */
public final class SCProtocolPermission extends GCFPermission {

	/**
	 * <p>Constructs <code>SCProtocolPermission</code> with the specified URI.
	 * The URI string <span class="keyword">should</span> conform to the
	 * specification given above.</p>
	 * 
	 * @param uri the URI for the protocol
	 * @throws IllegalArgumentException if <code>uri</code> is malformed
	 * @throws NullPointerException if <code>uri</code> is <code>null</code>
	 */
	public SCProtocolPermission(String uri) {
	}

	/**
	 * <p>Checks if the <code>SCProtocolPermission</code> object "implies" the
	 * specified permission. To determine whether this object implies another
	 * permission, <code>p</code>, this method checks that the following is
	 * true and returns <code>false</code> if it is not:</p>
	 * 
	 * <ul>
	 * 	<li><code>p</code> is an instanceof <code>SCProtocolPermission</code>, and</li>
	 * 	<li><code>p</code>'s name equals or (in the case of wildcards) is implied by
	 *      this object's name.</li>
	 * </ul>
	 * 
	 * @param p the permission to check against
	 * @return <code>true</code> if the specified permission <code>p</code> is
	 * 				implied by this object, <code>false</code> if not
	 */
	public boolean implies(Permission p) {
	}
	
	/**
	 * <p>Returns the canonical string representation of the actions. Since there
	 * are no actions defined for <code>SCProtocolPermission</code> an
	 * empty string "" is returned.</p>
	 * 
	 * @return an empty string ""
	 */
	public String getActions() {
	}
	
	/**
	 * <p>Returns a new <code>PermissionCollection</code> for storing
	 * <code>SCProtocolPermission</code> objects.</p>
	 * 
	 * <p><code>SCProtocolPermission</code> object <span class="keyword">must</span>
	 * be stored in a manner that allows them to be inserted into the collection
	 * in any order, but that also enables the <code>PermissionCollection.implies</code>
	 * method to be implemented in an effective (and consistent) manner.</p>
	 * 
	 * @return a new <code>PermissionCollection</code> object suitable for storing
	 * 				<code>SCProtocolPermission</code> objects
	 */
	public PermissionCollection newPermissionCollection() {
	}
	
	/**
	 * <p>Checks two <code>SCProtocolPermission</code> objects for equality.</p>
	 * 
	 * @param obj the object whose equality with this object is tested
	 * @return <code>true</code> if <code>obj</code> is a
	 * 		   <code>SCProtocolPermission</code> and has the same URI string as
	 * 		   this <code>SCProtocolPermission</code> object
	 */
	public boolean equals(Object obj) {
	}

	/**
	 * <p>Returns the hash code value for this object.</p>
	 * 
	 * @return the hash code value for this object
	 */
	public int hashCode() {
	}
	
}

    

VTagProtocolPermission

        package javax.microedition.contactless.visual;

import java.security.Permission;
import java.security.PermissionCollection;

import javax.microedition.io.GCFPermission;

/**
 * <p>This class represents access rights to connections via the "vtag" protocol.
 * A <code>VTagProtocolPermission</code> consists of a URI string but no actions
 * list.</p>
 *
 * <p>The URI takes the following general form:</p>
 * 
 * <pre>vtag://{address_part}</pre>
 * 
 * <p>The value of the <code>{address_part}</code> field is implementation specific.
 * This is because the URI is not visible to the application before an actual
 * target is available. The <code>{address_part}</code> field may also end with
 * an asterisk. An asterisk indicates a match with any address that begins with
 * the part left from the asterisk and is followed by zero or more additional
 * characters. The asterisk alone matches all addresses.</p>
 *
 * @author Nokia Corporation
 * @version 1.1
 */
public final class VTagProtocolPermission extends GCFPermission {

	/**
	 * <p>Constructs <code>VTagProtocolPermission</code> with the specified URI.
	 * The URI string <span class="keyword">should</span> conform to the
	 * specification given above.</p>
	 * 
	 * @param uri the URI for the protocol
	 * @throws IllegalArgumentException if <code>uri</code> is malformed
	 * @throws NullPointerException if <code>uri</code> is <code>null</code>
	 */
	public VTagProtocolPermission(String uri) {
	}

	/**
	 * <p>Checks if the <code>VTagProtocolPermission</code> object "implies" the
	 * specified permission. To determine whether this object implies another
	 * permission, <code>p</code>, this method checks that the following is
	 * true and returns <code>false</code> if it is not:</p>
	 * 
	 * <ul>
	 * 	<li><code>p</code> is an instanceof <code>VTagProtocolPermission</code>,
	 * 		and</li>
	 * 	<li><code>p</code>'s name equals or (in the case of wildcards) is
	 * 		implied by this object's name.</li>
	 * </ul>
	 * 
	 * @param p the permission to check against
	 * @return <code>true</code> if the specified permission <code>p</code> is
	 * 				implied by this object, <code>false</code> if not
	 */
	public boolean implies(Permission p) {
	}
	
	/**
	 * <p>Returns the canonical string representation of the actions. Since there
	 * are no actions defined for <code>VTagProtocolPermission</code> an
	 * empty string "" is returned.</p>
	 * 
	 * @return an empty string ""
	 */
	public String getActions() {
	}
	
	/**
	 * <p>Returns a new <code>PermissionCollection</code> for storing
	 * <code>VTagProtocolPermission</code> objects.</p>
	 * 
	 * <p><code>VTagProtocolPermission</code> object <span class="keyword">must</span>
	 * be stored in a manner that allows them to be inserted into the collection
	 * in any order, but that also enables the <code>PermissionCollection.implies</code>
	 * method to be implemented in an effective (and consistent) manner.</p>
	 * 
	 * @return a new <code>PermissionCollection</code> object suitable for storing
	 * 				<code>VTagProtocolPermission</code> objects
	 */
	public PermissionCollection newPermissionCollection() {
	}
	
	/**
	 * <p>Checks two <code>VTagProtocolPermission</code> objects for equality.</p>
	 * 
	 * @param obj the object whose equality with this object is tested
	 * @return <code>true</code> if <code>obj</code> is a
	 * 		   <code>VTagProtocolPermission</code> and has the same URI string
	 * 		   as this <code>VTagProtocolPermission</code> object
	 */
	public boolean equals(Object obj) {
	}

	/**
	 * <p>Returns the hash code value for this object.</p>
	 * 
	 * @return the hash code value for this object
	 */
	public int hashCode() {
	}
	
}